agrobr 0.1.2__tar.gz → 0.5.0__tar.gz

agrobr-0.5.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      
+      - name: Install dependencies
+        run: pip install mkdocs-material mkdocstrings mkdocstrings-python
+      
+      - name: Build docs
+        run: mkdocs build
+      
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

agrobr-0.5.0/.gitignore

@@ -0,0 +1,27 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.venv
+venv/
+
+# IDE
+.vscode/
+.idea/
+
+# Build
+dist/
+*.egg-info/
+
+# Cache
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Project
+.claude/
+agrobr_v3.txt
+agrobr_roadmap_v2.txt

agrobr-0.5.0/CHANGELOG.md

@@ -0,0 +1,180 @@
+# Changelog
+
+Todas as mudanças notáveis neste projeto serão documentadas neste arquivo.
+
+O formato é baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.0.0/),
+e este projeto adere ao [Versionamento Semântico](https://semver.org/lang/pt-BR/).
+
+## [Unreleased]
+
+## [0.5.0] - 2026-02-04
+
+### Added
+- **Plugin System** - Arquitetura extensível para fontes e validadores
+  - `SourcePlugin` - Interface para novas fontes de dados
+  - `ParserPlugin` - Interface para parsers customizados
+  - `ExporterPlugin` - Interface para exportadores customizados
+  - `ValidatorPlugin` - Interface para validadores customizados
+  - `register()`, `get_plugin()`, `list_plugins()` - Gerenciamento de plugins
+- **API Stability Decorators** - Marcadores de estabilidade de API
+  - `@stable(since="x.y.z")` - Marca API como estável
+  - `@experimental(since="x.y.z")` - Marca API como experimental
+  - `@deprecated(since, removed_in, replacement)` - Marca API como deprecated
+  - `@internal` - Marca API como interna (não pública)
+  - `list_stable_apis()`, `list_experimental_apis()`, `list_deprecated_apis()`
+- **SLA Documentado** - Contratos de nível de serviço por fonte
+  - `SourceSLA` - Definição de SLA com tier, freshness, latency, availability
+  - `CEPEA_SLA` - Tier CRITICAL, atualização diária 18h, 99% uptime
+  - `CONAB_SLA` - Tier STANDARD, atualização mensal, 98% uptime
+  - `IBGE_SLA` - Tier STANDARD, varia por pesquisa
+  - `get_sla()`, `list_slas()`, `get_sla_summary()`
+- **Certificação de Qualidade** - Sistema de certificação de dados
+  - `QualityLevel` - GOLD, SILVER, BRONZE, UNCERTIFIED
+  - `QualityCheck` - Check individual com status e detalhes
+  - `QualityCertificate` - Certificado completo com score e validade
+  - `certify(df)` - Executa checks (completeness, duplicates, schema, freshness, range)
+  - `quick_check(df)` - Retorna (level, score) rapidamente
+
+## [0.4.0] - 2026-02-04
+
+### Added
+- **Modo Determinístico** - Reprodutibilidade absoluta para backtests
+  - `agrobr.set_mode("deterministic", snapshot="2025-01-01")`
+  - `agrobr.configure()` para opções globais
+  - `agrobr.get_config()` para consultar configuração atual
+  - `agrobr.reset_config()` para resetar ao padrão
+- **Sistema de Snapshots** - Gerenciamento de versões de dados
+  - `create_snapshot()` - Cria snapshot dos dados atuais
+  - `load_from_snapshot()` - Carrega dados de um snapshot
+  - `list_snapshots()` / `delete_snapshot()` - Gerenciamento
+  - CLI: `agrobr snapshot create/list/delete/use`
+- **Export Auditável** - Formatos com metadados de proveniência
+  - `export_parquet()` - Parquet com metadata embutido
+  - `export_csv()` - CSV com arquivo sidecar .meta.json
+  - `export_json()` - JSON com metadados opcionais
+  - `verify_export()` - Verificação de integridade
+
+## [0.3.0] - 2026-02-04
+
+### Added
+- **Stability Contracts** - Garantias formais de schema para todas as fontes
+  - `CEPEA_INDICADOR_V1` - Contrato para indicadores de preço CEPEA
+  - `CONAB_SAFRA_V1` - Contrato para dados de safra CONAB
+  - `CONAB_BALANCO_V1` - Contrato para balanço oferta/demanda CONAB
+  - `IBGE_PAM_V1` - Contrato para dados PAM do IBGE
+  - `IBGE_LSPA_V1` - Contrato para dados LSPA do IBGE
+  - `contract.validate(df)` - Validação automática contra contrato
+  - `contract.to_markdown()` - Documentação automática
+- **Validação Semântica** - Verificações avançadas de qualidade
+  - Validação de preços positivos
+  - Validação de faixas de produtividade por cultura
+  - Detecção de anomalias em variação diária (>20%)
+  - Consistência de sequência de datas
+  - Consistência de áreas (colhida <= plantada)
+  - Validação de formato de safra
+  - `validate_semantic(df)` - Executa todas as regras
+  - `get_validation_summary(df)` - Resumo das violações
+- **Benchmark Suite** - Ferramentas para medição de performance
+  - `benchmark_async()` / `benchmark_sync()` - Benchmark de funções
+  - `run_api_benchmarks()` - Benchmark das APIs
+  - `run_contract_benchmarks()` - Benchmark de validação de contratos
+  - `run_semantic_benchmarks()` - Benchmark de validação semântica
+
+### Changed
+- Changelog reestruturado seguindo Keep a Changelog
+
+## [0.2.0] - 2026-02-04
+
+### Added
+- **`agrobr doctor`** - Comando CLI para diagnóstico do sistema
+  - Verificação de conectividade das fontes
+  - Estatísticas do cache (tamanho, registros, por fonte)
+  - Status de configuração
+  - Output JSON (`--json`) e formatado Rich
+- **Parâmetro `return_meta`** - Suporte a data lineage em todas as APIs
+  - `cepea.indicador(return_meta=True)` retorna `(DataFrame, MetaInfo)`
+  - `conab.safras(return_meta=True)` retorna `(DataFrame, MetaInfo)`
+  - `ibge.pam(return_meta=True)` retorna `(DataFrame, MetaInfo)`
+  - `ibge.lspa(return_meta=True)` retorna `(DataFrame, MetaInfo)`
+- **Classe `MetaInfo`** - Metadados de proveniência e rastreabilidade
+  - Informações da fonte (nome, URL, método)
+  - Timing (duração fetch, duração parse)
+  - Status do cache (from_cache, cache_key, expires_at)
+  - Integridade do conteúdo (hash SHA256, tamanho)
+  - Versões (agrobr, parser, schema, python)
+  - `to_dict()` / `to_json()` para serialização
+  - `verify_hash(df)` para verificação de integridade
+- **Documentação** - Guias de proveniência e resiliência
+  - `docs/sources/cepea.md` - Documentação da fonte CEPEA
+  - `docs/sources/conab.md` - Documentação da fonte CONAB
+  - `docs/sources/ibge.md` - Documentação da fonte IBGE
+  - `docs/advanced/resilience.md` - Documentação de resiliência
+
+### Changed
+- `MetaInfo` exportado do pacote principal
+
+## [0.1.2] - 2026-02-04
+
+### Changed
+- **Smart TTL** para cache CEPEA - expira às 18:00 (horário de atualização CEPEA)
+- Reduz requests desnecessários em ~90%
+
+## [0.1.1] - 2026-02-04
+
+### Fixed
+- Browser fallback desabilitado para CEPEA (Cloudflare bloqueia)
+- CEPEA agora vai direto para Notícias Agrícolas, evitando timeout
+
+## [0.1.0] - 2026-02-04
+
+### Added
+- **CEPEA**: Indicadores de preços agrícolas (soja, milho, boi, café, algodão, trigo)
+  - Fallback automático para Notícias Agrícolas quando CEPEA bloqueado
+  - Acumulação progressiva de histórico no DuckDB
+- **CONAB**: Dados de safras e balanço oferta/demanda
+  - Parser para planilhas XLSX do boletim de safras
+  - Suporte a todos os produtos principais (soja, milho, arroz, feijão, etc.)
+- **IBGE**: Integração com API SIDRA
+  - PAM (Produção Agrícola Municipal) - dados anuais
+  - LSPA (Levantamento Sistemático) - estimativas mensais
+- **Cache**: Sistema de cache com DuckDB
+  - Separação entre cache volátil e histórico permanente
+  - TTL configurável por fonte
+  - Acumulação progressiva de dados
+- **HTTP**: Cliente robusto com resiliência
+  - Retry com exponential backoff
+  - Rate limiting por fonte
+  - User-agent rotativo
+  - Fallback para Playwright quando necessário
+- **CLI**: Interface de linha de comando completa
+  - Comandos para CEPEA, CONAB e IBGE
+  - Exportação em CSV, JSON e Parquet
+- **Validação**: Sistema de validação multinível
+  - Pydantic v2 para validação de tipos
+  - Validação estatística (sanity checks)
+  - Fingerprinting de layout para detecção de mudanças
+- **Monitoramento**: Health checks e alertas
+  - Health check por fonte
+  - Alertas multi-canal (Slack, Discord, Email)
+  - Monitoramento de estrutura
+- **Suporte Polars**: Todas as APIs suportam `as_polars=True`
+- **Testes**: 96 testes passando (~80% cobertura)
+- **CI/CD**: GitHub Actions configurados
+  - Testes automatizados
+  - Health check diário
+  - Monitoramento de estrutura
+
+### Technical Details
+- Python 3.11+ required
+- Async-first design com sync wrapper
+- Type hints completos
+- Logging estruturado com structlog
+
+[Unreleased]: https://github.com/bruno-portfolio/agrobr/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/bruno-portfolio/agrobr/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/bruno-portfolio/agrobr/compare/v0.3.0...v0.4.0
+[0.3.0]: https://github.com/bruno-portfolio/agrobr/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/bruno-portfolio/agrobr/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/bruno-portfolio/agrobr/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/bruno-portfolio/agrobr/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/bruno-portfolio/agrobr/releases/tag/v0.1.0

{agrobr-0.1.2 → agrobr-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agrobr
-Version: 0.1.2
+Version: 0.5.0
 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
@@ -201,16 +201,16 @@ agrobr health --all
 
 ## 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
+-  **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
 
@@ -226,7 +226,7 @@ Consultas a períodos antigos são instantâneas (cache). Apenas dados recentes
 
 ## Documentação
 
-📚 [Documentação completa](https://bruno-portfolio.github.io/agrobr/)
+ [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/)

{agrobr-0.1.2 → agrobr-0.5.0}/README.md

@@ -132,16 +132,16 @@ agrobr health --all
 
 ## 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
+-  **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
 
@@ -157,7 +157,7 @@ Consultas a períodos antigos são instantâneas (cache). Apenas dados recentes
 
 ## Documentação
 
-📚 [Documentação completa](https://bruno-portfolio.github.io/agrobr/)
+ [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/)

{agrobr-0.1.2 → agrobr-0.5.0}/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-0.5.0/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",
+]