Metadata-Version: 2.4
Name: agrobr
Version: 0.1.2
Summary: Dados agrícolas brasileiros em uma linha de código
Project-URL: Homepage, https://github.com/bruno-portfolio/agrobr
Project-URL: Documentation, https://agrobr.dev
Project-URL: Repository, https://github.com/bruno-portfolio/agrobr
Project-URL: Issues, https://github.com/bruno-portfolio/agrobr/issues
Author-email: Bruno <bruno@example.com>
License-Expression: MIT
License-File: LICENSE
Keywords: agricultura,agro,brasil,cepea,commodities,conab,dados,ibge,milho,scraping,soja
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: chardet>=5.2.0
Requires-Dist: duckdb>=0.9.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: openpyxl>=3.1.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: sidrapy>=0.1.4
Requires-Dist: structlog>=23.2.0
Requires-Dist: typer>=0.9.0
Provides-Extra: all
Requires-Dist: black>=23.11.0; extra == 'all'
Requires-Dist: mkdocs-material>=9.5.0; extra == 'all'
Requires-Dist: mkdocs>=1.5.0; extra == 'all'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'all'
Requires-Dist: mypy>=1.7.0; extra == 'all'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'all'
Requires-Dist: polars>=0.19.0; extra == 'all'
Requires-Dist: pre-commit>=3.5.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'all'
Requires-Dist: pytest-cov>=4.1.0; extra == 'all'
Requires-Dist: pytest-recording>=0.13.0; extra == 'all'
Requires-Dist: pytest>=7.4.0; extra == 'all'
Requires-Dist: ruff>=0.14.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: black>=23.11.0; extra == 'dev'
Requires-Dist: mypy>=1.7.0; extra == 'dev'
Requires-Dist: pandas-stubs>=2.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-recording>=0.13.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocs>=1.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: polars
Requires-Dist: polars>=0.19.0; extra == 'polars'
Description-Content-Type: text/markdown

# agrobr

> Dados agrícolas brasileiros em uma linha de código

[![PyPI version](https://badge.fury.io/py/agrobr.svg)](https://pypi.org/project/agrobr/)
[![Tests](https://github.com/bruno-portfolio/agrobr/actions/workflows/tests.yml/badge.svg)](https://github.com/bruno-portfolio/agrobr/actions/workflows/tests.yml)
[![Health Check](https://github.com/bruno-portfolio/agrobr/actions/workflows/health_check.yml/badge.svg)](https://github.com/bruno-portfolio/agrobr/actions/workflows/health_check.yml)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)

Wrapper Python production-grade para dados do **CEPEA**, **CONAB** e **IBGE**.

## Instalação

```bash
pip install agrobr
```

Com suporte a Polars e Playwright (para fontes que requerem JavaScript):
```bash
pip install agrobr[polars,browser]
playwright install chromium
```

## Uso Rápido

### CEPEA - Indicadores de Preços

```python
import asyncio
from agrobr import cepea

async def main():
    # Série histórica de soja
    df = await cepea.indicador('soja', periodo='2024')
    print(df.head())

    # Último valor disponível
    ultimo = await cepea.ultimo('soja')
    print(f"Soja: R$ {ultimo.valor}/sc em {ultimo.data}")

    # Produtos disponíveis
    print(cepea.produtos())  # ['soja', 'milho', 'boi_gordo', 'cafe', ...]

asyncio.run(main())
```

### CONAB - Safras e Balanço

```python
from agrobr import conab

async def main():
    # Dados de safra por UF
    df = await conab.safras('soja', safra='2024/25')
    print(df[['uf', 'area_plantada', 'producao', 'produtividade']])

    # Balanço oferta/demanda
    balanco = await conab.balanco('soja')
    print(balanco)

    # Total Brasil
    brasil = await conab.brasil_total()
    print(brasil)
```

### IBGE - PAM e LSPA

```python
from agrobr import ibge

async def main():
    # PAM - Produção Agrícola Municipal (anual)
    df = await ibge.pam('soja', ano=2023, nivel='uf')
    print(df[['localidade', 'area_plantada', 'producao']])

    # LSPA - Levantamento Sistemático (mensal)
    df = await ibge.lspa('soja', ano=2024, mes=6)
    print(df)

    # Múltiplos anos
    df = await ibge.pam('milho', ano=[2020, 2021, 2022, 2023])
```

### Modo Síncrono

```python
from agrobr.sync import cepea, conab, ibge

# Mesmo API, sem async/await
df = cepea.indicador('soja', periodo='2024')
safras = conab.safras('milho')
pam = ibge.pam('soja', ano=2023)
```

### Suporte Polars

```python
# Retorna polars.DataFrame em vez de pandas
df = await cepea.indicador('soja', as_polars=True)
df = await conab.safras('milho', as_polars=True)
df = await ibge.pam('soja', ano=2023, as_polars=True)
```

### CLI

```bash
# CEPEA
agrobr cepea soja --ultimo
agrobr cepea milho --inicio 2024-01-01 --formato csv

# CONAB
agrobr conab safras soja --safra 2024/25
agrobr conab balanco milho

# IBGE
agrobr ibge pam soja --ano 2023 --nivel uf
agrobr ibge lspa milho --ano 2024 --mes 6

# Health check
agrobr health --all
```

## Fontes Suportadas

| Fonte | Dados | Status |
|-------|-------|--------|
| CEPEA | Indicadores de preços (soja, milho, café, boi, algodão, trigo) | ✅ Funcional |
| CONAB | Safras, balanço oferta/demanda | ✅ Funcional |
| IBGE | PAM (anual), LSPA (mensal) | ✅ Funcional |

## Diferenciais

- 🚀 **Async-first** para pipelines de alta performance
- 💾 **Cache inteligente** com DuckDB (analytics nativo)
- 📊 **Histórico permanente** - acumula dados automaticamente
- 🐼 **Suporte pandas + polars**
- ✅ **Validação com Pydantic v2**
- 📈 **Validação estatística** de sanidade (detecta anomalias)
- 🔍 **Fingerprinting de layout** para detecção proativa de mudanças
- 🔔 **Alertas multi-canal** (Slack, Discord, Email)
- 🖥️ **CLI completo** para debug e automação
- 🔄 **Fallback automático** entre fontes

## Como Funciona

O agrobr mantém um cache local em DuckDB que acumula dados ao longo do tempo:

```
Dia 1:   Coleta 10 dias de dados → salva no DuckDB
Dia 30:  30 dias de histórico acumulado
Dia 365: 1 ano completo de dados locais
```

Consultas a períodos antigos são instantâneas (cache). Apenas dados recentes precisam de request HTTP.

## Documentação

📚 [Documentação completa](https://bruno-portfolio.github.io/agrobr/)

- [Guia Rápido](https://bruno-portfolio.github.io/agrobr/quickstart/)
- [API CEPEA](https://bruno-portfolio.github.io/agrobr/api/cepea/)
- [API CONAB](https://bruno-portfolio.github.io/agrobr/api/conab/)
- [API IBGE](https://bruno-portfolio.github.io/agrobr/api/ibge/)
- [Resiliência](https://bruno-portfolio.github.io/agrobr/advanced/resilience/)

## Contribuindo

Contribuições são bem-vindas! Veja [CONTRIBUTING.md](CONTRIBUTING.md) para detalhes.

## Licença

MIT - veja [LICENSE](LICENSE) para detalhes.
