agrobr 0.1.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

agrobr/cepea/api.py

@@ -2,18 +2,21 @@
 
 from __future__ import annotations
 
+import hashlib
+import time
 from datetime import date, datetime, timedelta
 from decimal import Decimal
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 import pandas as pd
 import structlog
 
 from agrobr import constants
 from agrobr.cache.duckdb_store import get_store
+from agrobr.cache.policies import calculate_expiry
 from agrobr.cepea import client
 from agrobr.cepea.parsers.detector import get_parser_with_fallback
-from agrobr.models import Indicador
+from agrobr.models import Indicador, MetaInfo
 from agrobr.validators.sanity import validate_batch
 
 if TYPE_CHECKING:
@@ -21,10 +24,10 @@ if TYPE_CHECKING:
 
 logger = structlog.get_logger()
 
-# Janela de dados disponível na fonte (Notícias Agrícolas tem ~10 dias)
 SOURCE_WINDOW_DAYS = 10
 
 
+@overload
 async def indicador(
     produto: str,
     praca: str | None = None,
@@ -35,7 +38,39 @@ async def indicador(
     validate_sanity: bool = False,
     force_refresh: bool = False,
     offline: bool = False,
-) -> pd.DataFrame | pl.DataFrame:
+    *,
+    return_meta: Literal[False] = False,
+) -> pd.DataFrame | pl.DataFrame: ...
+
+
+@overload
+async def indicador(
+    produto: str,
+    praca: str | None = None,
+    inicio: str | date | None = None,
+    fim: str | date | None = None,
+    _moeda: str = "BRL",
+    as_polars: bool = False,
+    validate_sanity: bool = False,
+    force_refresh: bool = False,
+    offline: bool = False,
+    *,
+    return_meta: Literal[True],
+) -> tuple[pd.DataFrame | pl.DataFrame, MetaInfo]: ...
+
+
+async def indicador(
+    produto: str,
+    praca: str | None = None,
+    inicio: str | date | None = None,
+    fim: str | date | None = None,
+    _moeda: str = "BRL",
+    as_polars: bool = False,
+    validate_sanity: bool = False,
+    force_refresh: bool = False,
+    offline: bool = False,
+    return_meta: bool = False,
+) -> pd.DataFrame | pl.DataFrame | tuple[pd.DataFrame | pl.DataFrame, MetaInfo]:
     """
     Obtém série de indicadores de preço do CEPEA.
 
@@ -55,17 +90,23 @@ async def indicador(
         validate_sanity: Se True, valida dados estatisticamente
         force_refresh: Se True, ignora histórico e busca da fonte
         offline: Se True, usa apenas histórico local
+        return_meta: Se True, retorna tupla (DataFrame, MetaInfo)
 
     Returns:
-        DataFrame com indicadores
+        DataFrame com indicadores ou tupla (DataFrame, MetaInfo) se return_meta=True
     """
-    # Normaliza datas
+    fetch_start = time.perf_counter()
+    meta = MetaInfo(
+        source="unknown",
+        source_url="",
+        source_method="unknown",
+        fetched_at=datetime.now(),
+    )
     if isinstance(inicio, str):
         inicio = datetime.strptime(inicio, "%Y-%m-%d").date()
     if isinstance(fim, str):
         fim = datetime.strptime(fim, "%Y-%m-%d").date()
 
-    # Default: último ano
     if fim is None:
         fim = date.today()
     if inicio is None:
@@ -74,7 +115,9 @@ async def indicador(
     store = get_store()
     indicadores: list[Indicador] = []
 
-    # 1. Busca no histórico local
+    source_url = ""
+    parser_version = 1
+
     if not force_refresh:
         cached_data = store.indicadores_query(
             produto=produto,
@@ -85,6 +128,11 @@ async def indicador(
 
         indicadores = _dicts_to_indicadores(cached_data)
 
+        if indicadores:
+            meta.from_cache = True
+            meta.source = "cache"
+            meta.source_method = "duckdb"
+
         logger.info(
             "history_query",
             produto=produto,
@@ -93,54 +141,61 @@ async def indicador(
             cached_count=len(indicadores),
         )
 
-    # 2. Verifica se precisa buscar dados recentes
     needs_fetch = False
     if not offline:
         if force_refresh:
             needs_fetch = True
         else:
-            # Verifica se faltam dados na janela recente
             today = date.today()
             recent_start = today - timedelta(days=SOURCE_WINDOW_DAYS)
 
-            # Se o período solicitado inclui dados recentes
             if fim >= recent_start:
                 existing_dates = {ind.data for ind in indicadores}
-                # Verifica se tem lacunas nos últimos dias
                 for i in range(min(SOURCE_WINDOW_DAYS, (fim - max(inicio, recent_start)).days + 1)):
                     check_date = fim - timedelta(days=i)
-                    # Pula fins de semana (CEPEA não publica)
                     if check_date.weekday() < 5 and check_date not in existing_dates:
                         needs_fetch = True
                         break
 
-    # 3. Busca da fonte se necessário
     if needs_fetch:
         logger.info("fetching_from_source", produto=produto)
 
         try:
-            # Tenta buscar - pode vir do CEPEA ou Notícias Agrícolas
+            parse_start = time.perf_counter()
             html = await client.fetch_indicador_page(produto)
+            raw_content_size = len(html.encode("utf-8"))
+            raw_content_hash = f"sha256:{hashlib.sha256(html.encode('utf-8')).hexdigest()[:16]}"
 
-            # Detecta fonte pelo conteúdo do HTML
             is_noticias_agricolas = "noticiasagricolas" in html.lower() or "cot-fisicas" in html
 
             if is_noticias_agricolas:
-                # Usa parser de Notícias Agrícolas
                 from agrobr.noticias_agricolas.parser import parse_indicador as na_parse
 
                 new_indicadores = na_parse(html, produto)
+                source_url = f"https://www.noticiasagricolas.com.br/cotacoes/{produto}"
+                meta.source = "noticias_agricolas"
+                meta.source_method = "httpx"
                 logger.info(
                     "parse_success",
                     source="noticias_agricolas",
                     records_count=len(new_indicadores),
                 )
             else:
-                # Usa parser CEPEA
                 parser, new_indicadores = await get_parser_with_fallback(html, produto)
+                source_url = f"https://www.cepea.esalq.usp.br/br/indicador/{produto}.aspx"
+                meta.source = "cepea"
+                meta.source_method = "httpx"
+                parser_version = parser.version
+
+            parse_duration_ms = int((time.perf_counter() - parse_start) * 1000)
+            meta.parse_duration_ms = parse_duration_ms
+            meta.source_url = source_url
+            meta.raw_content_hash = raw_content_hash
+            meta.raw_content_size = raw_content_size
+            meta.parser_version = parser_version
+            meta.from_cache = False
 
             if new_indicadores:
-                # 4. Salva novos dados no histórico
                 new_dicts = _indicadores_to_dicts(new_indicadores)
                 saved_count = store.indicadores_upsert(new_dicts)
 
@@ -151,7 +206,6 @@ async def indicador(
                     saved=saved_count,
                 )
 
-                # Merge com dados existentes
                 existing_dates = {ind.data for ind in indicadores}
                 for ind in new_indicadores:
                     if ind.data not in existing_dates:
@@ -163,13 +217,11 @@ async def indicador(
                 produto=produto,
                 error=str(e),
             )
-            # Continua com dados do histórico
+            meta.validation_warnings.append(f"source_fetch_failed: {e}")
 
-    # 5. Validação estatística
     if validate_sanity and indicadores:
         indicadores, anomalies = await validate_batch(indicadores)
 
-    # 6. Filtra por período e praça
     indicadores = [ind for ind in indicadores if inicio <= ind.data <= fim]
 
     if praca:
@@ -177,17 +229,27 @@ async def indicador(
             ind for ind in indicadores if ind.praca and ind.praca.lower() == praca.lower()
         ]
 
-    # 7. Converte para DataFrame
     df = _to_dataframe(indicadores)
 
+    meta.fetch_duration_ms = int((time.perf_counter() - fetch_start) * 1000)
+    meta.records_count = len(df)
+    meta.columns = df.columns.tolist() if not df.empty else []
+    meta.cache_key = f"cepea:{produto}:{praca or 'all'}"
+    meta.cache_expires_at = calculate_expiry(constants.Fonte.CEPEA)
+
     if as_polars:
         try:
             import polars as pl
 
-            return pl.from_pandas(df)
+            result_df = pl.from_pandas(df)
+            if return_meta:
+                return result_df, meta
+            return result_df
         except ImportError:
             logger.warning("polars_not_installed", fallback="pandas")
 
+    if return_meta:
+        return df, meta
     return df
 
 
@@ -270,7 +332,6 @@ async def ultimo(produto: str, praca: str | None = None, offline: bool = False)
     store = get_store()
     indicadores: list[Indicador] = []
 
-    # Busca no histórico (últimos 30 dias)
     fim = date.today()
     inicio = fim - timedelta(days=30)
 
@@ -284,7 +345,6 @@ async def ultimo(produto: str, praca: str | None = None, offline: bool = False)
     if cached_data:
         indicadores = _dicts_to_indicadores(cached_data)
 
-    # Se não tem dados recentes ou não está offline, busca da fonte
     if not offline:
         has_recent = any(ind.data >= fim - timedelta(days=3) for ind in indicadores)
 
@@ -292,7 +352,6 @@ async def ultimo(produto: str, praca: str | None = None, offline: bool = False)
             try:
                 html = await client.fetch_indicador_page(produto)
 
-                # Detecta fonte pelo conteúdo do HTML
                 is_noticias_agricolas = "noticiasagricolas" in html.lower() or "cot-fisicas" in html
 
                 if is_noticias_agricolas:
@@ -303,11 +362,9 @@ async def ultimo(produto: str, praca: str | None = None, offline: bool = False)
                     parser, new_indicadores = await get_parser_with_fallback(html, produto)
 
                 if new_indicadores:
-                    # Salva no histórico
                     new_dicts = _indicadores_to_dicts(new_indicadores)
                     store.indicadores_upsert(new_dicts)
 
-                    # Merge
                     existing_dates = {ind.data for ind in indicadores}
                     for ind in new_indicadores:
                         if ind.data not in existing_dates:

agrobr/cepea/client.py

@@ -14,9 +14,7 @@ from agrobr.normalize.encoding import decode_content
 
 logger = structlog.get_logger()
 
-# Flag para controlar uso de browser
-_use_browser: bool = True
-# Flag para controlar uso de fonte alternativa (Notícias Agrícolas)
+_use_browser: bool = False
 _use_alternative_source: bool = True
 
 
@@ -141,7 +139,6 @@ async def fetch_indicador_page(
     Raises:
         SourceUnavailableError: Se não conseguir acessar após todos os fallbacks
     """
-    # Se forçar fonte alternativa, vai direto para Notícias Agrícolas
     if force_alternative:
         return await _fetch_with_alternative_source(produto)
 
@@ -157,7 +154,6 @@ async def fetch_indicador_page(
 
     last_error: str = ""
 
-    # Passo 1: Tenta httpx (a menos que force_browser)
     if not force_browser:
         try:
             return await _fetch_with_httpx(url, headers)
@@ -170,7 +166,6 @@ async def fetch_indicador_page(
                 error=last_error,
             )
 
-    # Passo 2: Tenta browser (se habilitado)
     if _use_browser:
         try:
             return await _fetch_with_browser(produto)
@@ -183,7 +178,6 @@ async def fetch_indicador_page(
                 error=last_error,
             )
 
-    # Passo 3: Tenta fonte alternativa (se habilitado)
     if _use_alternative_source:
         try:
             return await _fetch_with_alternative_source(produto)
@@ -196,7 +190,6 @@ async def fetch_indicador_page(
                 error=last_error,
             )
 
-    # Todos os métodos falharam
     logger.error(
         "all_methods_failed",
         source="cepea",

agrobr/cli.py

@@ -68,6 +68,29 @@ def health(
         typer.echo(json.dumps(result, indent=2))
 
 
+@app.command("doctor")  # type: ignore[misc]
+def doctor(
+    verbose: bool = typer.Option(False, "--verbose", "-v", help="Mostra informacoes detalhadas"),
+    json_output: bool = typer.Option(False, "--json", help="Output em formato JSON"),
+) -> None:
+    """Diagnostica saude do sistema, conectividade e cache."""
+    import asyncio
+
+    from agrobr.health.doctor import run_diagnostics
+
+    try:
+        result = asyncio.run(run_diagnostics(verbose=verbose))
+
+        if json_output:
+            typer.echo(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))
+        else:
+            typer.echo(result.to_rich())
+
+    except Exception as e:
+        typer.echo(f"Erro ao executar diagnostico: {e}", err=True)
+        raise typer.Exit(1) from None
+
+
 cache_app = typer.Typer(help="Gerenciamento de cache")
 app.add_typer(cache_app, name="cache")
 
@@ -191,10 +214,6 @@ def conab_produtos() -> None:
         typer.echo(f"  - {prod}")
 
 
-# =============================================================================
-# IBGE Commands
-# =============================================================================
-
 ibge_app = typer.Typer(help="Dados IBGE - PAM e LSPA")
 app.add_typer(ibge_app, name="ibge")
 
@@ -217,7 +236,6 @@ def ibge_pam(
     typer.echo(f"Consultando PAM para {produto}...")
 
     try:
-        # Parse ano
         ano_param: int | list[int] | None = None
         if ano:
             ano_param = [int(a.strip()) for a in ano.split(",")] if "," in ano else int(ano)
@@ -298,6 +316,9 @@ def ibge_produtos(
 config_app = typer.Typer(help="Configuracoes")
 app.add_typer(config_app, name="config")
 
+snapshot_app = typer.Typer(help="Gerenciamento de snapshots para modo deterministico")
+app.add_typer(snapshot_app, name="snapshot")
+
 
 @config_app.command("show")  # type: ignore[misc]
 def config_show() -> None:
@@ -319,5 +340,120 @@ def config_show() -> None:
     typer.echo(f"  slack_webhook: {'configured' if alerts.slack_webhook else 'not set'}")
 
 
+@snapshot_app.command("list")  # type: ignore[misc]
+def snapshot_list(
+    json_output: bool = typer.Option(False, "--json", help="Output em formato JSON"),
+) -> None:
+    """Lista todos os snapshots disponiveis."""
+    from agrobr.snapshots import list_snapshots
+
+    snapshots = list_snapshots()
+
+    if not snapshots:
+        typer.echo("Nenhum snapshot encontrado.")
+        typer.echo("Use 'agrobr snapshot create' para criar um snapshot.")
+        return
+
+    if json_output:
+        data = [
+            {
+                "name": s.name,
+                "created_at": s.created_at.isoformat(),
+                "size_mb": round(s.size_bytes / 1024 / 1024, 2),
+                "sources": s.sources,
+                "files": s.file_count,
+            }
+            for s in snapshots
+        ]
+        typer.echo(json.dumps(data, indent=2))
+    else:
+        typer.echo("Snapshots disponiveis:")
+        typer.echo("-" * 60)
+        for s in snapshots:
+            size_mb = s.size_bytes / 1024 / 1024
+            typer.echo(f"  {s.name}")
+            typer.echo(f"    Criado em: {s.created_at.strftime('%Y-%m-%d %H:%M')}")
+            typer.echo(f"    Tamanho: {size_mb:.2f} MB")
+            typer.echo(f"    Fontes: {', '.join(s.sources)}")
+            typer.echo(f"    Arquivos: {s.file_count}")
+            typer.echo()
+
+
+@snapshot_app.command("create")  # type: ignore[misc]
+def snapshot_create(
+    name: str | None = typer.Argument(None, help="Nome do snapshot (default: data atual)"),
+    sources: str | None = typer.Option(
+        None, "--sources", "-s", help="Fontes a incluir (ex: cepea,conab,ibge)"
+    ),
+) -> None:
+    """Cria um novo snapshot dos dados atuais."""
+    import asyncio
+
+    from agrobr.snapshots import create_snapshot
+
+    source_list = sources.split(",") if sources else None
+
+    typer.echo(f"Criando snapshot{f' {name}' if name else ''}...")
+
+    try:
+        info = asyncio.run(create_snapshot(name=name, sources=source_list))
+        typer.echo("Snapshot criado com sucesso!")
+        typer.echo(f"  Nome: {info.name}")
+        typer.echo(f"  Caminho: {info.path}")
+        typer.echo(f"  Arquivos: {info.file_count}")
+    except ValueError as e:
+        typer.echo(f"Erro: {e}", err=True)
+        raise typer.Exit(1) from None
+    except Exception as e:
+        typer.echo(f"Erro ao criar snapshot: {e}", err=True)
+        raise typer.Exit(1) from None
+
+
+@snapshot_app.command("delete")  # type: ignore[misc]
+def snapshot_delete(
+    name: str = typer.Argument(..., help="Nome do snapshot a remover"),
+    force: bool = typer.Option(False, "--force", "-f", help="Nao pedir confirmacao"),
+) -> None:
+    """Remove um snapshot."""
+    from agrobr.snapshots import delete_snapshot, get_snapshot
+
+    snapshot = get_snapshot(name)
+    if not snapshot:
+        typer.echo(f"Snapshot '{name}' nao encontrado.", err=True)
+        raise typer.Exit(1)
+
+    if not force:
+        confirm = typer.confirm(f"Remover snapshot '{name}'?")
+        if not confirm:
+            typer.echo("Operacao cancelada.")
+            return
+
+    if delete_snapshot(name):
+        typer.echo(f"Snapshot '{name}' removido com sucesso.")
+    else:
+        typer.echo("Erro ao remover snapshot.", err=True)
+        raise typer.Exit(1)
+
+
+@snapshot_app.command("use")  # type: ignore[misc]
+def snapshot_use(
+    name: str = typer.Argument(..., help="Nome do snapshot a usar"),
+) -> None:
+    """Configura agrobr para usar um snapshot (modo deterministico)."""
+    from agrobr.config import set_mode
+    from agrobr.snapshots import get_snapshot
+
+    snapshot = get_snapshot(name)
+    if not snapshot:
+        typer.echo(f"Snapshot '{name}' nao encontrado.", err=True)
+        typer.echo("Use 'agrobr snapshot list' para ver snapshots disponiveis.")
+        raise typer.Exit(1)
+
+    set_mode("deterministic", snapshot=name)
+    typer.echo(f"Modo deterministico ativado com snapshot '{name}'.")
+    typer.echo("Todas as chamadas usarao dados do snapshot.")
+    typer.echo("Use 'agrobr config mode normal' para voltar ao modo normal.")
+
+
 if __name__ == "__main__":
     app()

agrobr/conab/api.py

@@ -2,25 +2,54 @@
 
 from __future__ import annotations
 
-from typing import Any
+import time
+from datetime import datetime
+from typing import Any, Literal, overload
 
 import pandas as pd
 import structlog
 
 from agrobr import constants
+from agrobr.cache.policies import calculate_expiry
 from agrobr.conab import client
 from agrobr.conab.parsers.v1 import ConabParserV1
+from agrobr.models import MetaInfo
 
 logger = structlog.get_logger()
 
 
+@overload
 async def safras(
     produto: str,
     safra: str | None = None,
     uf: str | None = None,
     levantamento: int | None = None,
     as_polars: bool = False,
-) -> pd.DataFrame:
+    *,
+    return_meta: Literal[False] = False,
+) -> pd.DataFrame: ...
+
+
+@overload
+async def safras(
+    produto: str,
+    safra: str | None = None,
+    uf: str | None = None,
+    levantamento: int | None = None,
+    as_polars: bool = False,
+    *,
+    return_meta: Literal[True],
+) -> tuple[pd.DataFrame, MetaInfo]: ...
+
+
+async def safras(
+    produto: str,
+    safra: str | None = None,
+    uf: str | None = None,
+    levantamento: int | None = None,
+    as_polars: bool = False,
+    return_meta: bool = False,
+) -> pd.DataFrame | tuple[pd.DataFrame, MetaInfo]:
     """
     Obtém dados de safra por produto.
 
@@ -30,14 +59,23 @@ async def safras(
         uf: Filtrar por UF (ex: "MT", "PR")
         levantamento: Número do levantamento (default: mais recente)
         as_polars: Se True, retorna polars.DataFrame
+        return_meta: Se True, retorna tupla (DataFrame, MetaInfo)
 
     Returns:
-        DataFrame com dados de safra por UF
+        DataFrame com dados de safra por UF ou tupla (DataFrame, MetaInfo)
 
     Example:
         >>> df = await conab.safras('soja', safra='2025/26')
-        >>> df = await conab.safras('milho', uf='MT')
+        >>> df, meta = await conab.safras('milho', uf='MT', return_meta=True)
     """
+    fetch_start = time.perf_counter()
+    meta = MetaInfo(
+        source="conab",
+        source_url="https://www.conab.gov.br/info-agro/safras/graos",
+        source_method="httpx",
+        fetched_at=datetime.now(),
+    )
+
     logger.info(
         "conab_safras_request",
         produto=produto,
@@ -46,8 +84,17 @@ async def safras(
         levantamento=levantamento,
     )
 
+    parse_start = time.perf_counter()
     xlsx, metadata = await client.fetch_safra_xlsx(safra=safra, levantamento=levantamento)
 
+    if isinstance(xlsx, bytes):
+        meta.raw_content_size = len(xlsx)
+    elif hasattr(xlsx, "getbuffer"):
+        meta.raw_content_size = len(xlsx.getbuffer())
+    else:
+        meta.raw_content_size = 0
+    meta.source_url = metadata.get("url", meta.source_url)
+
     parser = ConabParserV1()
     safra_list = parser.parse_safra_produto(
         xlsx=xlsx,
@@ -56,6 +103,9 @@ async def safras(
         levantamento=metadata.get("levantamento"),
     )
 
+    meta.parse_duration_ms = int((time.perf_counter() - parse_start) * 1000)
+    meta.parser_version = parser.version
+
     if uf:
         safra_list = [s for s in safra_list if s.uf == uf.upper()]
 
@@ -66,15 +116,29 @@ async def safras(
             safra=safra,
             uf=uf,
         )
-        return pd.DataFrame()
+        df = pd.DataFrame()
+        if return_meta:
+            meta.records_count = 0
+            meta.fetch_duration_ms = int((time.perf_counter() - fetch_start) * 1000)
+            return df, meta
+        return df
 
     df = pd.DataFrame([s.model_dump() for s in safra_list])
 
+    meta.fetch_duration_ms = int((time.perf_counter() - fetch_start) * 1000)
+    meta.records_count = len(df)
+    meta.columns = df.columns.tolist()
+    meta.cache_key = f"conab:safras:{produto}:{safra or 'latest'}"
+    meta.cache_expires_at = calculate_expiry(constants.Fonte.CONAB)
+
     if as_polars:
         try:
             import polars as pl
 
-            return pl.from_pandas(df)  # type: ignore[no-any-return]
+            result_df = pl.from_pandas(df)
+            if return_meta:
+                return result_df, meta  # type: ignore[return-value,no-any-return]
+            return result_df  # type: ignore[return-value,no-any-return]
         except ImportError:
             logger.warning("polars_not_installed", fallback="pandas")
 
@@ -84,6 +148,8 @@ async def safras(
         records=len(df),
     )
 
+    if return_meta:
+        return df, meta
     return df