agrobr 0.1.0__py3-none-any.whl

agrobr/cepea/api.py

@@ -0,0 +1,360 @@
+"""API pública do módulo CEPEA."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+from typing import TYPE_CHECKING, Any
+
+import pandas as pd
+import structlog
+
+from agrobr import constants
+from agrobr.cache.duckdb_store import get_store
+from agrobr.cepea import client
+from agrobr.cepea.parsers.detector import get_parser_with_fallback
+from agrobr.models import Indicador
+from agrobr.validators.sanity import validate_batch
+
+if TYPE_CHECKING:
+    import polars as pl
+
+logger = structlog.get_logger()
+
+# Janela de dados disponível na fonte (Notícias Agrícolas tem ~10 dias)
+SOURCE_WINDOW_DAYS = 10
+
+
+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,
+) -> pd.DataFrame | pl.DataFrame:
+    """
+    Obtém série de indicadores de preço do CEPEA.
+
+    Usa estratégia de acumulação progressiva:
+    1. Busca dados no histórico local (DuckDB)
+    2. Se faltar dados recentes, busca da fonte (CEPEA/Notícias Agrícolas)
+    3. Salva novos dados no histórico
+    4. Retorna DataFrame completo do período solicitado
+
+    Args:
+        produto: Nome do produto (soja, milho, cafe, boi, etc)
+        praca: Praça específica (opcional)
+        inicio: Data inicial (YYYY-MM-DD ou date)
+        fim: Data final (YYYY-MM-DD ou date)
+        moeda: Moeda (BRL ou USD)
+        as_polars: Se True, retorna polars.DataFrame
+        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
+
+    Returns:
+        DataFrame com indicadores
+    """
+    # Normaliza datas
+    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:
+        inicio = fim - timedelta(days=365)
+
+    store = get_store()
+    indicadores: list[Indicador] = []
+
+    # 1. Busca no histórico local
+    if not force_refresh:
+        cached_data = store.indicadores_query(
+            produto=produto,
+            inicio=datetime.combine(inicio, datetime.min.time()),
+            fim=datetime.combine(fim, datetime.max.time()),
+            praca=praca,
+        )
+
+        indicadores = _dicts_to_indicadores(cached_data)
+
+        logger.info(
+            "history_query",
+            produto=produto,
+            inicio=inicio,
+            fim=fim,
+            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
+            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:
+                # Usa parser de Notícias Agrícolas
+                from agrobr.noticias_agricolas.parser import parse_indicador as na_parse
+
+                new_indicadores = na_parse(html, produto)
+                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)
+
+            if new_indicadores:
+                # 4. Salva novos dados no histórico
+                new_dicts = _indicadores_to_dicts(new_indicadores)
+                saved_count = store.indicadores_upsert(new_dicts)
+
+                logger.info(
+                    "new_data_saved",
+                    produto=produto,
+                    fetched=len(new_indicadores),
+                    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:
+                        indicadores.append(ind)
+
+        except Exception as e:
+            logger.warning(
+                "source_fetch_failed",
+                produto=produto,
+                error=str(e),
+            )
+            # Continua com dados do histórico
+
+    # 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:
+        indicadores = [
+            ind for ind in indicadores if ind.praca and ind.praca.lower() == praca.lower()
+        ]
+
+    # 7. Converte para DataFrame
+    df = _to_dataframe(indicadores)
+
+    if as_polars:
+        try:
+            import polars as pl
+
+            return pl.from_pandas(df)
+        except ImportError:
+            logger.warning("polars_not_installed", fallback="pandas")
+
+    return df
+
+
+def _dicts_to_indicadores(dicts: list[dict[str, Any]]) -> list[Indicador]:
+    """Converte lista de dicts do banco para objetos Indicador."""
+    indicadores = []
+    for d in dicts:
+        try:
+            ind = Indicador(
+                fonte=constants.Fonte(d["fonte"]) if d.get("fonte") else constants.Fonte.CEPEA,
+                produto=d["produto"],
+                praca=d.get("praca"),
+                data=d["data"] if isinstance(d["data"], date) else d["data"].date(),
+                valor=Decimal(str(d["valor"])),
+                unidade=d.get("unidade", "BRL/unidade"),
+                metodologia=d.get("metodologia"),
+                parser_version=d.get("parser_version", 1),
+            )
+            indicadores.append(ind)
+        except Exception as e:
+            logger.warning("indicador_conversion_failed", error=str(e), data=d)
+    return indicadores
+
+
+def _indicadores_to_dicts(indicadores: list[Indicador]) -> list[dict[str, Any]]:
+    """Converte lista de Indicador para dicts para salvar no banco."""
+    return [
+        {
+            "produto": ind.produto,
+            "praca": ind.praca,
+            "data": ind.data,
+            "valor": float(ind.valor),
+            "unidade": ind.unidade,
+            "fonte": ind.fonte.value,
+            "metodologia": ind.metodologia,
+            "variacao_percentual": ind.meta.get("variacao_percentual"),
+            "parser_version": ind.parser_version,
+        }
+        for ind in indicadores
+    ]
+
+
+async def produtos() -> list[str]:
+    """Lista produtos disponíveis no CEPEA."""
+    return list(constants.CEPEA_PRODUTOS.keys())
+
+
+async def pracas(produto: str) -> list[str]:
+    """
+    Lista praças disponíveis para um produto.
+
+    Args:
+        produto: Nome do produto
+
+    Returns:
+        Lista de praças disponíveis
+    """
+    pracas_map = {
+        "soja": ["paranagua", "parana", "rio_grande_do_sul"],
+        "milho": ["campinas", "parana"],
+        "cafe": ["mogiana", "sul_de_minas"],
+        "boi": ["sao_paulo"],
+        "trigo": ["parana", "rio_grande_do_sul"],
+    }
+    return pracas_map.get(produto.lower(), [])
+
+
+async def ultimo(produto: str, praca: str | None = None, offline: bool = False) -> Indicador:
+    """
+    Obtém último indicador disponível.
+
+    Args:
+        produto: Nome do produto
+        praca: Praça específica (opcional)
+        offline: Se True, usa apenas histórico local
+
+    Returns:
+        Último Indicador disponível
+    """
+    store = get_store()
+    indicadores: list[Indicador] = []
+
+    # Busca no histórico (últimos 30 dias)
+    fim = date.today()
+    inicio = fim - timedelta(days=30)
+
+    cached_data = store.indicadores_query(
+        produto=produto,
+        inicio=datetime.combine(inicio, datetime.min.time()),
+        fim=datetime.combine(fim, datetime.max.time()),
+        praca=praca,
+    )
+
+    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)
+
+        if not has_recent:
+            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:
+                    from agrobr.noticias_agricolas.parser import parse_indicador as na_parse
+
+                    new_indicadores = na_parse(html, produto)
+                else:
+                    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:
+                            indicadores.append(ind)
+
+            except Exception as e:
+                logger.warning("source_fetch_failed", produto=produto, error=str(e))
+
+    if praca:
+        indicadores = [
+            ind for ind in indicadores if ind.praca and ind.praca.lower() == praca.lower()
+        ]
+
+    if not indicadores:
+        from agrobr.exceptions import ParseError
+
+        raise ParseError(
+            source="cepea",
+            parser_version=1,
+            reason=f"No indicators found for {produto}",
+        )
+
+    indicadores.sort(key=lambda x: x.data, reverse=True)
+    return indicadores[0]
+
+
+def _to_dataframe(indicadores: list[Indicador]) -> pd.DataFrame:
+    """Converte lista de indicadores para DataFrame."""
+    if not indicadores:
+        return pd.DataFrame()
+
+    data = [
+        {
+            "data": ind.data,
+            "produto": ind.produto,
+            "praca": ind.praca,
+            "valor": float(ind.valor),
+            "unidade": ind.unidade,
+            "fonte": ind.fonte.value,
+            "metodologia": ind.metodologia,
+            "anomalies": ind.anomalies if ind.anomalies else None,
+        }
+        for ind in indicadores
+    ]
+
+    df = pd.DataFrame(data)
+    df["data"] = pd.to_datetime(df["data"])
+    df = df.sort_values("data").reset_index(drop=True)
+
+    return df

agrobr/cepea/client.py

@@ -0,0 +1,273 @@
+"""Cliente HTTP async para CEPEA."""
+
+from __future__ import annotations
+
+import httpx
+import structlog
+
+from agrobr import constants
+from agrobr.exceptions import SourceUnavailableError
+from agrobr.http.rate_limiter import RateLimiter
+from agrobr.http.retry import retry_async, should_retry_status
+from agrobr.http.user_agents import UserAgentRotator
+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_alternative_source: bool = True
+
+
+def set_use_browser(enabled: bool) -> None:
+    """Habilita ou desabilita uso de browser para CEPEA."""
+    global _use_browser
+    _use_browser = enabled
+    logger.info("cepea_browser_mode", enabled=enabled)
+
+
+def set_use_alternative_source(enabled: bool) -> None:
+    """Habilita ou desabilita uso de fonte alternativa (Notícias Agrícolas)."""
+    global _use_alternative_source
+    _use_alternative_source = enabled
+    logger.info("cepea_alternative_source_mode", enabled=enabled)
+
+
+def _get_timeout() -> httpx.Timeout:
+    """Retorna configuração de timeout."""
+    settings = constants.HTTPSettings()
+    return httpx.Timeout(
+        connect=settings.timeout_connect,
+        read=settings.timeout_read,
+        write=settings.timeout_write,
+        pool=settings.timeout_pool,
+    )
+
+
+def _get_produto_url(produto: str) -> str:
+    """Retorna URL do indicador para o produto."""
+    produto_key = constants.CEPEA_PRODUTOS.get(produto.lower(), produto.lower())
+    base = constants.URLS[constants.Fonte.CEPEA]["indicadores"]
+    return f"{base}/{produto_key}.aspx"
+
+
+async def _fetch_with_httpx(url: str, headers: dict[str, str]) -> str:
+    """Tenta buscar com httpx (mais rápido, mas pode falhar com Cloudflare)."""
+
+    async def _fetch() -> httpx.Response:
+        async with (
+            RateLimiter.acquire(constants.Fonte.CEPEA),
+            httpx.AsyncClient(
+                timeout=_get_timeout(),
+                follow_redirects=True,
+            ) as client,
+        ):
+            response = await client.get(url, headers=headers)
+
+            if should_retry_status(response.status_code):
+                raise httpx.HTTPStatusError(
+                    f"Retriable status: {response.status_code}",
+                    request=response.request,
+                    response=response,
+                )
+
+            response.raise_for_status()
+            return response
+
+    response = await retry_async(_fetch)
+
+    declared_encoding = response.charset_encoding
+    html, actual_encoding = decode_content(
+        response.content,
+        declared_encoding=declared_encoding,
+        source="cepea",
+    )
+
+    logger.info(
+        "http_response",
+        source="cepea",
+        status_code=response.status_code,
+        content_length=len(response.content),
+        encoding=actual_encoding,
+        method="httpx",
+    )
+
+    return html
+
+
+async def _fetch_with_browser(produto: str) -> str:
+    """Busca usando Playwright (contorna Cloudflare)."""
+    from agrobr.http.browser import fetch_cepea_indicador
+
+    logger.info("browser_fallback", source="cepea", produto=produto)
+    return await fetch_cepea_indicador(produto)
+
+
+async def _fetch_with_alternative_source(produto: str) -> str:
+    """Busca usando Notícias Agrícolas (fonte alternativa sem Cloudflare)."""
+    from agrobr.noticias_agricolas.client import fetch_indicador_page as na_fetch
+
+    logger.info(
+        "alternative_source_fallback",
+        source="cepea",
+        alternative="noticias_agricolas",
+        produto=produto,
+    )
+    return await na_fetch(produto)
+
+
+async def fetch_indicador_page(
+    produto: str,
+    force_browser: bool = False,
+    force_alternative: bool = False,
+) -> str:
+    """
+    Busca página de indicador do CEPEA.
+
+    Cadeia de fallback:
+    1. httpx direto (mais rápido)
+    2. Playwright browser (contorna Cloudflare básico)
+    3. Notícias Agrícolas (fonte alternativa sem Cloudflare)
+
+    Args:
+        produto: Nome do produto (soja, milho, cafe, boi, etc)
+        force_browser: Se True, pula httpx e usa browser diretamente
+        force_alternative: Se True, usa fonte alternativa diretamente
+
+    Returns:
+        HTML da página como string
+
+    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)
+
+    url = _get_produto_url(produto)
+    headers = UserAgentRotator.get_headers(source="cepea")
+
+    logger.info(
+        "http_request",
+        source="cepea",
+        url=url,
+        method="GET",
+    )
+
+    last_error: str = ""
+
+    # Passo 1: Tenta httpx (a menos que force_browser)
+    if not force_browser:
+        try:
+            return await _fetch_with_httpx(url, headers)
+        except (httpx.HTTPError, httpx.HTTPStatusError, SourceUnavailableError) as e:
+            last_error = str(e)
+            logger.warning(
+                "httpx_failed",
+                source="cepea",
+                url=url,
+                error=last_error,
+            )
+
+    # Passo 2: Tenta browser (se habilitado)
+    if _use_browser:
+        try:
+            return await _fetch_with_browser(produto)
+        except (SourceUnavailableError, Exception) as e:
+            last_error = str(e)
+            logger.warning(
+                "browser_failed",
+                source="cepea",
+                url=url,
+                error=last_error,
+            )
+
+    # Passo 3: Tenta fonte alternativa (se habilitado)
+    if _use_alternative_source:
+        try:
+            return await _fetch_with_alternative_source(produto)
+        except (SourceUnavailableError, ValueError, Exception) as e:
+            last_error = str(e)
+            logger.warning(
+                "alternative_source_failed",
+                source="cepea",
+                alternative="noticias_agricolas",
+                error=last_error,
+            )
+
+    # Todos os métodos falharam
+    logger.error(
+        "all_methods_failed",
+        source="cepea",
+        url=url,
+        last_error=last_error,
+    )
+    raise SourceUnavailableError(
+        source="cepea",
+        url=url,
+        last_error=f"All fetch methods failed. Last error: {last_error}",
+    )
+
+
+async def fetch_series_historica(produto: str, anos: int = 5) -> str:
+    """
+    Busca série histórica do CEPEA.
+
+    Args:
+        produto: Nome do produto
+        anos: Quantidade de anos de histórico
+
+    Returns:
+        HTML da página de série histórica
+    """
+    constants.CEPEA_PRODUTOS.get(produto.lower(), produto.lower())
+    base = constants.URLS[constants.Fonte.CEPEA]["base"]
+    url = f"{base}/br/consultas-ao-banco-de-dados-do-site.aspx"
+
+    headers = UserAgentRotator.get_headers(source="cepea")
+
+    logger.info(
+        "http_request",
+        source="cepea",
+        url=url,
+        method="GET",
+        produto=produto,
+        anos=anos,
+    )
+
+    async def _fetch() -> httpx.Response:
+        async with (
+            RateLimiter.acquire(constants.Fonte.CEPEA),
+            httpx.AsyncClient(
+                timeout=_get_timeout(),
+                follow_redirects=True,
+            ) as client,
+        ):
+            response = await client.get(url, headers=headers)
+            response.raise_for_status()
+            return response
+
+    try:
+        response = await retry_async(_fetch)
+    except httpx.HTTPError as e:
+        logger.error(
+            "http_request_failed",
+            source="cepea",
+            url=url,
+            error=str(e),
+        )
+        raise SourceUnavailableError(
+            source="cepea",
+            url=url,
+            last_error=str(e),
+        ) from e
+
+    declared_encoding = response.charset_encoding
+    html, _ = decode_content(
+        response.content,
+        declared_encoding=declared_encoding,
+        source="cepea",
+    )
+
+    return html

agrobr/cepea/parsers/__init__.py

@@ -0,0 +1,37 @@
+"""Parsers CEPEA - Versionados para diferentes layouts."""
+
+from __future__ import annotations
+
+from agrobr.cepea.parsers.base import BaseParser
+from agrobr.cepea.parsers.consensus import (
+    ConsensusResult,
+    ConsensusValidator,
+    ParserDivergence,
+    analyze_consensus,
+    parse_with_consensus,
+    select_best_result,
+)
+from agrobr.cepea.parsers.detector import get_parser_with_fallback
+from agrobr.cepea.parsers.fingerprint import (
+    compare_fingerprints,
+    extract_fingerprint,
+    load_baseline_fingerprint,
+    save_baseline_fingerprint,
+)
+from agrobr.cepea.parsers.v1 import CepeaParserV1
+
+__all__ = [
+    "BaseParser",
+    "CepeaParserV1",
+    "compare_fingerprints",
+    "extract_fingerprint",
+    "get_parser_with_fallback",
+    "load_baseline_fingerprint",
+    "save_baseline_fingerprint",
+    "ConsensusResult",
+    "ConsensusValidator",
+    "ParserDivergence",
+    "parse_with_consensus",
+    "analyze_consensus",
+    "select_best_result",
+]

agrobr/cepea/parsers/base.py

@@ -0,0 +1,35 @@
+"""Interface base para parsers CEPEA."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from datetime import date
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agrobr import models
+
+
+class BaseParser(ABC):
+    """Interface base para todos os parsers."""
+
+    version: int
+    source: str
+    valid_from: date
+    valid_until: date | None = None
+    expected_fingerprint: dict[str, str] | None = None
+
+    @abstractmethod
+    def can_parse(self, html: str) -> tuple[bool, float]:
+        """Verifica se este parser consegue processar o HTML. Retorna (pode_parsear, confianca)."""
+        pass
+
+    @abstractmethod
+    def parse(self, html: str, produto: str) -> list[models.Indicador]:
+        """Parseia HTML e retorna lista de indicadores."""
+        pass
+
+    @abstractmethod
+    def extract_fingerprint(self, html: str) -> dict[str, str]:
+        """Extrai assinatura estrutural do HTML."""
+        pass