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

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 = False
-# Flag para controlar uso de fonte alternativa (Notícias Agrícolas)
 _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
 
 

agrobr/config.py

@@ -0,0 +1,137 @@
+"""Configuracao global do agrobr."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+from typing import Literal
+
+_config: AgrobrConfig | None = None
+
+
+@dataclass
+class AgrobrConfig:
+    """Configuracao global do agrobr."""
+
+    mode: Literal["normal", "deterministic"] = "normal"
+    snapshot_date: date | None = None
+    snapshot_path: Path | None = None
+
+    cache_enabled: bool = True
+    cache_path: Path | None = None
+
+    network_enabled: bool = True
+    timeout_seconds: int = 30
+
+    browser_fallback: bool = False
+    alternative_source: bool = True
+
+    log_level: str = "INFO"
+
+    def is_deterministic(self) -> bool:
+        """Verifica se esta em modo deterministico."""
+        return self.mode == "deterministic"
+
+    def get_snapshot_dir(self) -> Path:
+        """Retorna diretorio de snapshots."""
+        if self.snapshot_path:
+            return self.snapshot_path
+        return Path.home() / ".agrobr" / "snapshots"
+
+    def get_current_snapshot_path(self) -> Path | None:
+        """Retorna caminho do snapshot atual."""
+        if not self.snapshot_date:
+            return None
+        return self.get_snapshot_dir() / self.snapshot_date.isoformat()
+
+
+def set_mode(
+    mode: Literal["normal", "deterministic"],
+    snapshot: str | date | None = None,
+    snapshot_path: str | Path | None = None,
+) -> None:
+    """
+    Define modo de operacao do agrobr.
+
+    Args:
+        mode: "normal" ou "deterministic"
+        snapshot: Data do snapshot (YYYY-MM-DD ou date)
+        snapshot_path: Caminho customizado para snapshots
+
+    Example:
+        agrobr.set_mode("normal")
+        agrobr.set_mode("deterministic", snapshot="2025-12-31")
+    """
+    global _config
+
+    if isinstance(snapshot, str):
+        snapshot = date.fromisoformat(snapshot)
+
+    if isinstance(snapshot_path, str):
+        snapshot_path = Path(snapshot_path)
+
+    _config = AgrobrConfig(
+        mode=mode,
+        snapshot_date=snapshot,
+        snapshot_path=snapshot_path,
+        network_enabled=(mode == "normal"),
+    )
+
+
+def get_config() -> AgrobrConfig:
+    """Retorna configuracao atual."""
+    global _config
+    if _config is None:
+        _config = AgrobrConfig()
+    return _config
+
+
+def reset_config() -> None:
+    """Reseta para configuracao padrao."""
+    global _config
+    _config = None
+
+
+def configure(
+    cache_enabled: bool | None = None,
+    cache_path: str | Path | None = None,
+    timeout_seconds: int | None = None,
+    browser_fallback: bool | None = None,
+    alternative_source: bool | None = None,
+    log_level: str | None = None,
+) -> None:
+    """
+    Configura opcoes do agrobr.
+
+    Args:
+        cache_enabled: Habilitar/desabilitar cache
+        cache_path: Caminho customizado para cache
+        timeout_seconds: Timeout para requisicoes HTTP
+        browser_fallback: Usar browser como fallback
+        alternative_source: Usar fontes alternativas
+        log_level: Nivel de log (DEBUG, INFO, WARNING, ERROR)
+    """
+    config = get_config()
+
+    if cache_enabled is not None:
+        config.cache_enabled = cache_enabled
+    if cache_path is not None:
+        config.cache_path = Path(cache_path) if isinstance(cache_path, str) else cache_path
+    if timeout_seconds is not None:
+        config.timeout_seconds = timeout_seconds
+    if browser_fallback is not None:
+        config.browser_fallback = browser_fallback
+    if alternative_source is not None:
+        config.alternative_source = alternative_source
+    if log_level is not None:
+        config.log_level = log_level
+
+
+__all__ = [
+    "AgrobrConfig",
+    "set_mode",
+    "get_config",
+    "reset_config",
+    "configure",
+]

agrobr/constants.py

@@ -12,7 +12,7 @@ class Fonte(StrEnum):
     CEPEA = "cepea"
     CONAB = "conab"
     IBGE = "ibge"
-    NOTICIAS_AGRICOLAS = "noticias_agricolas"  # Fonte alternativa para CEPEA
+    NOTICIAS_AGRICOLAS = "noticias_agricolas"
 
 
 URLS = {
@@ -35,7 +35,6 @@ URLS = {
     },
 }
 
-# Mapeamento de produtos para URLs do Notícias Agrícolas (indicadores CEPEA)
 NOTICIAS_AGRICOLAS_PRODUTOS = {
     "soja": "soja/soja-indicador-cepea-esalq-porto-paranagua",
     "soja_parana": "soja/indicador-cepea-esalq-soja-parana",