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

agrobr/__init__.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __author__ = "Bruno"
 
 from agrobr import cepea, conab, ibge
+from agrobr.models import MetaInfo
 
-__all__ = ["cepea", "conab", "ibge", "__version__"]
+__all__ = ["cepea", "conab", "ibge", "MetaInfo", "__version__"]

agrobr/benchmark/__init__.py

@@ -0,0 +1,343 @@
+"""Benchmark suite para testes de performance do agrobr."""
+
+from __future__ import annotations
+
+import statistics
+import time
+from collections.abc import Callable, Coroutine
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+import structlog
+
+logger = structlog.get_logger()
+
+
+@dataclass
+class BenchmarkResult:
+    """Resultado de um benchmark."""
+
+    name: str
+    iterations: int
+    total_time_ms: float
+    mean_time_ms: float
+    median_time_ms: float
+    min_time_ms: float
+    max_time_ms: float
+    std_dev_ms: float
+    times_ms: list[float] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converte para dicionario."""
+        return {
+            "name": self.name,
+            "iterations": self.iterations,
+            "total_time_ms": round(self.total_time_ms, 2),
+            "mean_time_ms": round(self.mean_time_ms, 2),
+            "median_time_ms": round(self.median_time_ms, 2),
+            "min_time_ms": round(self.min_time_ms, 2),
+            "max_time_ms": round(self.max_time_ms, 2),
+            "std_dev_ms": round(self.std_dev_ms, 2),
+            "timestamp": self.timestamp.isoformat(),
+            "metadata": self.metadata,
+        }
+
+    def summary(self) -> str:
+        """Retorna resumo formatado."""
+        return (
+            f"{self.name}: "
+            f"mean={self.mean_time_ms:.2f}ms, "
+            f"median={self.median_time_ms:.2f}ms, "
+            f"min={self.min_time_ms:.2f}ms, "
+            f"max={self.max_time_ms:.2f}ms "
+            f"({self.iterations} iterations)"
+        )
+
+
+@dataclass
+class BenchmarkSuite:
+    """Suite de benchmarks."""
+
+    name: str
+    results: list[BenchmarkResult] = field(default_factory=list)
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def add_result(self, result: BenchmarkResult) -> None:
+        """Adiciona resultado."""
+        self.results.append(result)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Converte para dicionario."""
+        return {
+            "name": self.name,
+            "timestamp": self.timestamp.isoformat(),
+            "results": [r.to_dict() for r in self.results],
+        }
+
+    def summary(self) -> str:
+        """Retorna resumo formatado."""
+        lines = [f"Benchmark Suite: {self.name}", "=" * 50]
+        for result in self.results:
+            lines.append(result.summary())
+        return "\n".join(lines)
+
+
+async def benchmark_async(
+    name: str,
+    func: Callable[..., Coroutine[Any, Any, Any]],
+    iterations: int = 10,
+    warmup: int = 1,
+    **kwargs: Any,
+) -> BenchmarkResult:
+    """
+    Executa benchmark de funcao async.
+
+    Args:
+        name: Nome do benchmark
+        func: Funcao async a testar
+        iterations: Numero de iteracoes
+        warmup: Iteracoes de aquecimento
+        **kwargs: Argumentos para a funcao
+
+    Returns:
+        BenchmarkResult com estatisticas
+    """
+    for _ in range(warmup):
+        await func(**kwargs)
+
+    times: list[float] = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        await func(**kwargs)
+        elapsed = (time.perf_counter() - start) * 1000
+        times.append(elapsed)
+
+    return BenchmarkResult(
+        name=name,
+        iterations=iterations,
+        total_time_ms=sum(times),
+        mean_time_ms=statistics.mean(times),
+        median_time_ms=statistics.median(times),
+        min_time_ms=min(times),
+        max_time_ms=max(times),
+        std_dev_ms=statistics.stdev(times) if len(times) > 1 else 0,
+        times_ms=times,
+        metadata={"warmup": warmup, "kwargs": str(kwargs)},
+    )
+
+
+def benchmark_sync(
+    name: str,
+    func: Callable[..., Any],
+    iterations: int = 10,
+    warmup: int = 1,
+    **kwargs: Any,
+) -> BenchmarkResult:
+    """
+    Executa benchmark de funcao sincrona.
+
+    Args:
+        name: Nome do benchmark
+        func: Funcao a testar
+        iterations: Numero de iteracoes
+        warmup: Iteracoes de aquecimento
+        **kwargs: Argumentos para a funcao
+
+    Returns:
+        BenchmarkResult com estatisticas
+    """
+    for _ in range(warmup):
+        func(**kwargs)
+
+    times: list[float] = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        func(**kwargs)
+        elapsed = (time.perf_counter() - start) * 1000
+        times.append(elapsed)
+
+    return BenchmarkResult(
+        name=name,
+        iterations=iterations,
+        total_time_ms=sum(times),
+        mean_time_ms=statistics.mean(times),
+        median_time_ms=statistics.median(times),
+        min_time_ms=min(times),
+        max_time_ms=max(times),
+        std_dev_ms=statistics.stdev(times) if len(times) > 1 else 0,
+        times_ms=times,
+        metadata={"warmup": warmup, "kwargs": str(kwargs)},
+    )
+
+
+async def run_api_benchmarks(iterations: int = 5) -> BenchmarkSuite:
+    """
+    Executa benchmarks das APIs principais.
+
+    Args:
+        iterations: Numero de iteracoes por benchmark
+
+    Returns:
+        BenchmarkSuite com resultados
+    """
+    from agrobr import cepea, conab, ibge
+
+    suite = BenchmarkSuite(name="agrobr_api_benchmarks")
+
+    try:
+        result = await benchmark_async(
+            "cepea.indicador(soja, offline=True)",
+            cepea.indicador,
+            iterations=iterations,
+            produto="soja",
+            offline=True,
+        )
+        suite.add_result(result)
+    except Exception as e:
+        logger.warning("benchmark_failed", name="cepea.indicador", error=str(e))
+
+    try:
+        result = await benchmark_async(
+            "cepea.produtos()",
+            cepea.produtos,
+            iterations=iterations,
+        )
+        suite.add_result(result)
+    except Exception as e:
+        logger.warning("benchmark_failed", name="cepea.produtos", error=str(e))
+
+    try:
+        result = await benchmark_async(
+            "conab.produtos()",
+            conab.produtos,
+            iterations=iterations,
+        )
+        suite.add_result(result)
+    except Exception as e:
+        logger.warning("benchmark_failed", name="conab.produtos", error=str(e))
+
+    try:
+        result = await benchmark_async(
+            "ibge.produtos_pam()",
+            ibge.produtos_pam,
+            iterations=iterations,
+        )
+        suite.add_result(result)
+    except Exception as e:
+        logger.warning("benchmark_failed", name="ibge.produtos_pam", error=str(e))
+
+    return suite
+
+
+def run_contract_benchmarks(iterations: int = 100) -> BenchmarkSuite:
+    """
+    Executa benchmarks de validacao de contratos.
+
+    Args:
+        iterations: Numero de iteracoes por benchmark
+
+    Returns:
+        BenchmarkSuite com resultados
+    """
+    import pandas as pd
+
+    from agrobr.contracts.cepea import CEPEA_INDICADOR_V1
+
+    suite = BenchmarkSuite(name="contract_validation_benchmarks")
+
+    df_small = pd.DataFrame(
+        {
+            "data": pd.date_range("2024-01-01", periods=10),
+            "produto": ["soja"] * 10,
+            "praca": ["paranagua"] * 10,
+            "valor": [150.0] * 10,
+            "unidade": ["BRL/sc60kg"] * 10,
+            "fonte": ["cepea"] * 10,
+            "metodologia": [None] * 10,
+            "anomalies": [None] * 10,
+        }
+    )
+
+    result = benchmark_sync(
+        "contract.validate(10 rows)",
+        CEPEA_INDICADOR_V1.validate,
+        iterations=iterations,
+        df=df_small,
+    )
+    suite.add_result(result)
+
+    df_large = pd.DataFrame(
+        {
+            "data": pd.date_range("2020-01-01", periods=1000),
+            "produto": ["soja"] * 1000,
+            "praca": ["paranagua"] * 1000,
+            "valor": [150.0] * 1000,
+            "unidade": ["BRL/sc60kg"] * 1000,
+            "fonte": ["cepea"] * 1000,
+            "metodologia": [None] * 1000,
+            "anomalies": [None] * 1000,
+        }
+    )
+
+    result = benchmark_sync(
+        "contract.validate(1000 rows)",
+        CEPEA_INDICADOR_V1.validate,
+        iterations=iterations,
+        df=df_large,
+    )
+    suite.add_result(result)
+
+    return suite
+
+
+def run_semantic_benchmarks(iterations: int = 50) -> BenchmarkSuite:
+    """
+    Executa benchmarks de validacao semantica.
+
+    Args:
+        iterations: Numero de iteracoes por benchmark
+
+    Returns:
+        BenchmarkSuite com resultados
+    """
+    import pandas as pd
+
+    from agrobr.validators.semantic import validate_semantic
+
+    suite = BenchmarkSuite(name="semantic_validation_benchmarks")
+
+    df = pd.DataFrame(
+        {
+            "data": pd.date_range("2024-01-01", periods=100),
+            "valor": [150.0 + i * 0.5 for i in range(100)],
+            "produto": ["soja"] * 100,
+            "produtividade": [3500.0] * 100,
+            "area_plantada": [1000.0] * 100,
+            "area_colhida": [950.0] * 100,
+            "safra": ["2024/25"] * 100,
+        }
+    )
+
+    result = benchmark_sync(
+        "validate_semantic(100 rows)",
+        validate_semantic,
+        iterations=iterations,
+        df=df,
+    )
+    suite.add_result(result)
+
+    return suite
+
+
+__all__ = [
+    "BenchmarkResult",
+    "BenchmarkSuite",
+    "benchmark_async",
+    "benchmark_sync",
+    "run_api_benchmarks",
+    "run_contract_benchmarks",
+    "run_semantic_benchmarks",
+]

agrobr/cache/policies.py

@@ -13,7 +13,7 @@ class CachePolicy(NamedTuple):
     ttl_seconds: int
     stale_max_seconds: int
     description: str
-    smart_expiry: bool = False  # Se True, usa horário fixo de expiração
+    smart_expiry: bool = False
 
 
 class TTL(Enum):
@@ -30,14 +30,13 @@ class TTL(Enum):
     DAYS_90 = 90 * 24 * 60 * 60
 
 
-# Horário de atualização do CEPEA (18:00 Brasília)
 CEPEA_UPDATE_HOUR = 18
 CEPEA_UPDATE_MINUTE = 0
 
 
 POLICIES: dict[str, CachePolicy] = {
     "cepea_diario": CachePolicy(
-        ttl_seconds=TTL.HOURS_24.value,  # Fallback se smart_expiry falhar
+        ttl_seconds=TTL.HOURS_24.value,
         stale_max_seconds=TTL.HOURS_24.value * 2,
         description="CEPEA indicador diário (expira às 18h)",
         smart_expiry=True,
@@ -73,7 +72,7 @@ POLICIES: dict[str, CachePolicy] = {
         smart_expiry=False,
     ),
     "noticias_agricolas": CachePolicy(
-        ttl_seconds=TTL.HOURS_24.value,  # Fallback
+        ttl_seconds=TTL.HOURS_24.value,
         stale_max_seconds=TTL.HOURS_24.value * 2,
         description="Notícias Agrícolas (expira às 18h, mirror CEPEA)",
         smart_expiry=True,
@@ -129,10 +128,8 @@ def _get_smart_expiry_time() -> datetime:
     today_expiry = datetime.combine(now.date(), time(CEPEA_UPDATE_HOUR, CEPEA_UPDATE_MINUTE))
 
     if now < today_expiry:
-        # Ainda não chegou às 18h hoje → expira hoje às 18h
         return today_expiry
     else:
-        # Já passou das 18h → expira amanhã às 18h
         return today_expiry + timedelta(days=1)
 
 
@@ -192,11 +189,9 @@ def is_expired(created_at: datetime, source: Fonte | str, endpoint: str | None =
     policy = get_policy(source, endpoint)
 
     if policy.smart_expiry:
-        # Smart expiry: cache válido se criado após última expiração (18h)
         last_expiry = _get_last_expiry_time()
         return created_at < last_expiry
 
-    # TTL fixo tradicional
     expires_at = created_at + timedelta(seconds=policy.ttl_seconds)
     return datetime.now() > expires_at
 

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: