agroplan-ai-cli 1.0.15 → 1.0.18

package/backend-template/.env.example

@@ -24,3 +24,22 @@ PROVIDER_CACHE_TTL=3600
 # If set, /cache/limpar endpoint requires X-Cache-Token header
 # Leave empty to disable protection (not recommended for production)
 CACHE_ADMIN_TOKEN=your-secret-token-here
+
+# ZARC Configuration
+# Source: official (download from gov portal) or fallback (use local simplified data)
+ZARC_SOURCE=official
+
+# Safra padrão
+ZARC_SAFRA=2025/2026
+
+# Cache TTL em segundos (padrão: 86400 = 24 horas)
+ZARC_CACHE_TTL=86400
+
+# Fast Index: usa índice compacto pré-processado (recomendado: true)
+# O índice contém apenas regiões/culturas de interesse (~35KB vs 214MB)
+ZARC_FAST_INDEX_ENABLED=true
+
+# Allow Full Scan: permite varrer CSV completo se não encontrar no índice
+# Produção (Render): false - evita timeout e uso excessivo de CPU
+# Desenvolvimento local: true - permite consultar qualquer região
+ZARC_ALLOW_FULL_SCAN=false

package/backend-template/api.py

@@ -73,6 +73,9 @@ class OtimizarRequest(BaseModel):
     lat: Optional[float] = None
     lon: Optional[float] = None
     days: Optional[int] = 30
+    uf: Optional[str] = None
+    municipio: Optional[str] = None
+    safra: Optional[str] = "2025/2026"
 
 class ValidarRequest(BaseModel):
     objetivo: str = "equilibrado"
@@ -84,6 +87,9 @@ class RelatorioRequest(BaseModel):
     lat: Optional[float] = None
     lon: Optional[float] = None
     days: Optional[int] = 30
+    uf: Optional[str] = None
+    municipio: Optional[str] = None
+    safra: Optional[str] = "2025/2026"
 
 class RodadasRequest(BaseModel):
     objetivo: str = "equilibrado"
@@ -141,6 +147,10 @@ def health():
         culturas, talhoes, regras = get_dados()
         provider_cache_stats = get_cache_stats()
         
+        # Verificar status ZARC (memory safe - não carrega CSV)
+        from providers.zarc_provider import get_zarc_status
+        zarc_status = get_zarc_status()
+        
         return {
             "status": "healthy",
             "culturas": len(culturas),
@@ -149,7 +159,8 @@ def health():
             "cache_items": len(_resultados_cache),
             "data_mode": DATA_MODE,
             "providers": {
-                "weather": "available" if WEATHER_PROVIDER else "disabled"
+                "weather": "available" if WEATHER_PROVIDER else "disabled",
+                "zarc": zarc_status
             },
             "provider_cache": provider_cache_stats
         }
@@ -186,13 +197,71 @@ def get_clima(
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
+@app.get("/dados/zarc")
+def get_zarc(
+    cultura: Optional[str] = Query(None, description="Nome da cultura"),
+    uf: Optional[str] = Query(None, description="Unidade Federativa (ex: SP, PR)"),
+    municipio: Optional[str] = Query(None, description="Nome do município"),
+    solo: Optional[str] = Query(None, description="Tipo de solo"),
+    safra: str = Query("2025/2026", description="Safra (ex: 2025/2026)")
+):
+    """Obtém dados ZARC (Zoneamento Agrícola de Risco Climático)"""
+    try:
+        # Importar provider ZARC
+        from providers.zarc_provider import buscar_zarc
+        
+        # Se cultura não foi fornecida, retornar mensagem amigável
+        if not cultura:
+            return {
+                "message": "Informe a cultura para consultar dados ZARC.",
+                "exemplo_soja_sp": "/dados/zarc?cultura=soja&uf=SP&municipio=Sao%20Paulo&solo=argiloso",
+                "exemplo_milho_pr": "/dados/zarc?cultura=milho&uf=PR&municipio=Londrina&solo=argiloso",
+                "parametros": {
+                    "cultura": "Nome da cultura (obrigatório)",
+                    "uf": "Unidade Federativa (opcional)",
+                    "municipio": "Nome do município (opcional)",
+                    "solo": "Tipo de solo (opcional)",
+                    "safra": "Safra, padrão 2025/2026"
+                },
+                "culturas_disponiveis": ["soja", "milho", "feijao", "cafe", "cana", "trigo", "algodao"],
+                "safras_disponiveis": ["2025/2026", "2026/2027"]
+            }
+        
+        # Buscar dados ZARC
+        zarc_data = buscar_zarc(
+            cultura=cultura,
+            uf=uf,
+            municipio=municipio,
+            solo=solo,
+            safra=safra
+        )
+        
+        if zarc_data:
+            return zarc_data
+        else:
+            return {
+                "message": "Dados ZARC não encontrados para os parâmetros fornecidos.",
+                "cultura": cultura,
+                "uf": uf,
+                "municipio": municipio,
+                "solo": solo,
+                "safra": safra,
+                "sugestao": "Tente com parâmetros mais genéricos (apenas cultura e UF)"
+            }
+        
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
 @app.get("/dashboard")
 def get_dashboard(
     lat: Optional[float] = None,
     lon: Optional[float] = None,
-    days: int = Query(30, description="Número de dias para análise climática")
+    days: int = Query(30, description="Número de dias para análise climática"),
+    uf: Optional[str] = None,
+    municipio: Optional[str] = None,
+    safra: str = Query("2025/2026", description="Safra ZARC")
 ):
-    """Retorna resumo do dashboard com contexto climático opcional"""
+    """Retorna resumo do dashboard com contexto climático e ZARC opcional"""
     try:
         culturas, talhoes, regras = get_dados()
         
@@ -202,10 +271,12 @@ def get_dashboard(
             from core.climate_adapter import obter_contexto_climatico_por_coordenadas
             contexto_climatico = obter_contexto_climatico_por_coordenadas(lat, lon, days)
         
-        # Gerar chave de cache considerando clima
+        # Gerar chave de cache considerando clima e ZARC
         cache_params = {"objetivo": "equilibrado", "seed": 42}
         if lat is not None and lon is not None:
             cache_params.update({"lat": lat, "lon": lon, "days": days})
+        if uf:
+            cache_params.update({"uf": uf, "municipio": municipio or "", "safra": safra})
         
         cache_key = get_cache_key("dashboard", **cache_params)
         
@@ -301,6 +372,18 @@ def get_dashboard(
             else:
                 resultado_base["clima_real"] = {"ativo": False}
             
+            # Enriquecer com ZARC se UF foi fornecida
+            if uf:
+                from core.zarc_adapter import enriquecer_plano_com_zarc
+                resultado_base = enriquecer_plano_com_zarc(
+                    resultado_base,
+                    uf=uf,
+                    municipio=municipio,
+                    safra=safra
+                )
+            else:
+                resultado_base["zarc"] = {"ativo": False}
+            
             return resultado_base
         
         # Usa cache para dashboard com contexto climático
@@ -323,8 +406,12 @@ def get_talhoes():
         raise HTTPException(status_code=500, detail=str(e))
 
 @app.get("/recomendacoes")
-def get_recomendacoes():
-    """Retorna recomendações de culturas por talhão"""
+def get_recomendacoes(
+    uf: Optional[str] = None,
+    municipio: Optional[str] = None,
+    safra: str = Query("2025/2026", description="Safra ZARC")
+):
+    """Retorna recomendações de culturas por talhão com ZARC opcional"""
     try:
         culturas, talhoes, regras = get_dados()
         
@@ -347,9 +434,24 @@ def get_recomendacoes():
                 "agua": str(p['agua'])
             })
         
-        return {
-            "recomendacoes": recomendacoes
-        }
+        resultado = {"recomendacoes": recomendacoes}
+        
+        # Enriquecer com ZARC se UF foi fornecida
+        if uf:
+            from core.zarc_adapter import enriquecer_plano_com_zarc
+            resultado_temp = {"plano": recomendacoes}
+            resultado_temp = enriquecer_plano_com_zarc(
+                resultado_temp,
+                uf=uf,
+                municipio=municipio,
+                safra=safra
+            )
+            resultado["recomendacoes"] = resultado_temp["plano"]
+            resultado["zarc"] = resultado_temp.get("zarc", {"ativo": False})
+        else:
+            resultado["zarc"] = {"ativo": False}
+        
+        return resultado
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
@@ -590,6 +692,18 @@ def otimizar(request: OtimizarRequest):
         # Converte tipos numpy para Python nativos
         resultado_convertido = converter_tipos_python(resultado)
         
+        # Enriquecer com ZARC se UF foi fornecida
+        if request.uf:
+            from core.zarc_adapter import enriquecer_plano_com_zarc
+            resultado_convertido = enriquecer_plano_com_zarc(
+                resultado_convertido,
+                uf=request.uf,
+                municipio=request.municipio,
+                safra=request.safra
+            )
+        else:
+            resultado_convertido["zarc"] = {"ativo": False}
+        
         return resultado_convertido
     except HTTPException:
         raise
@@ -677,12 +791,15 @@ def relatorio(request: RelatorioRequest):
             from core.climate_adapter import obter_contexto_climatico_por_coordenadas
             contexto_climatico = obter_contexto_climatico_por_coordenadas(request.lat, request.lon, request.days)
         
-        # Gera relatório com contexto climático integrado
+        # Gera relatório com contexto climático e ZARC integrado
         caminho = gerar_relatorio_completo(
             culturas, talhoes, regras,
             objetivo=request.objetivo,
             formato=request.formato,
-            contexto_climatico=contexto_climatico
+            contexto_climatico=contexto_climatico,
+            uf=request.uf,
+            municipio=request.municipio,
+            safra=request.safra
         )
         
         # Lê conteúdo
@@ -747,57 +864,3 @@ def limpar_cache(request: Request):
 if __name__ == "__main__":
     import uvicorn
     uvicorn.run(app, host=HOST, port=PORT)
-
-@app.get("/dados/zarc")
-def get_zarc(
-    cultura: Optional[str] = Query(None, description="Nome da cultura"),
-    uf: Optional[str] = Query(None, description="Unidade Federativa (ex: SP, PR)"),
-    municipio: Optional[str] = Query(None, description="Nome do município"),
-    solo: Optional[str] = Query(None, description="Tipo de solo"),
-    safra: str = Query("2025/2026", description="Safra (ex: 2025/2026)")
-):
-    """Obtém dados ZARC (Zoneamento Agrícola de Risco Climático)"""
-    try:
-        # Importar provider ZARC
-        from providers.zarc_provider import buscar_zarc
-        
-        # Se cultura não foi fornecida, retornar mensagem amigável
-        if not cultura:
-            return {
-                "message": "Informe a cultura para consultar dados ZARC.",
-                "exemplo_soja_sp": "/dados/zarc?cultura=soja&uf=SP&municipio=Sao%20Paulo&solo=argiloso",
-                "exemplo_milho_pr": "/dados/zarc?cultura=milho&uf=PR&municipio=Londrina&solo=argiloso",
-                "parametros": {
-                    "cultura": "Nome da cultura (obrigatório)",
-                    "uf": "Unidade Federativa (opcional)",
-                    "municipio": "Nome do município (opcional)",
-                    "solo": "Tipo de solo (opcional)",
-                    "safra": "Safra, padrão 2025/2026"
-                },
-                "culturas_disponiveis": ["soja", "milho", "feijao", "cafe", "cana", "trigo", "algodao"],
-                "safras_disponiveis": ["2025/2026", "2026/2027"]
-            }
-        
-        # Buscar dados ZARC
-        zarc_data = buscar_zarc(
-            cultura=cultura,
-            uf=uf,
-            municipio=municipio,
-            solo=solo,
-            safra=safra
-        )
-        
-        if zarc_data:
-            return zarc_data
-        else:
-            return {
-                "message": "Dados ZARC não encontrados para os parâmetros fornecidos.",
-                "cultura": cultura,
-                "uf": uf,
-                "municipio": municipio,
-                "solo": solo,
-                "safra": safra,
-                "sugestao": "Tente com parâmetros mais genéricos (apenas cultura e UF)"
-            }
-    except Exception as e:
-        raise HTTPException(status_code=500, detail=str(e))

package/backend-template/core/zarc_adapter.py

@@ -0,0 +1,290 @@
+"""
+Adaptador ZARC - Integra dados do ZARC no planejamento
+"""
+from typing import Dict, Any, Optional, List
+from providers.zarc_provider import buscar_zarc
+
+def enriquecer_plano_com_zarc(
+    resultado: Dict[str, Any],
+    uf: Optional[str] = None,
+    municipio: Optional[str] = None,
+    safra: str = "2025/2026"
+) -> Dict[str, Any]:
+    """
+    Enriquece resultado do planejamento com dados ZARC
+    
+    Args:
+        resultado: Resultado do planejamento (AG ou cenário)
+        uf: Unidade Federativa
+        municipio: Nome do município
+        safra: Safra (padrão: 2025/2026)
+    
+    Returns:
+        Resultado enriquecido com dados ZARC
+    """
+    # Se não tiver UF, não adiciona ZARC
+    if not uf:
+        resultado["zarc"] = {"ativo": False}
+        return resultado
+    
+    # Cache local por requisição para evitar lookups repetidos
+    lookup_cache = {}
+    
+    # Processar cada item do plano
+    culturas_com_zarc = 0
+    total_culturas = 0
+    sources = set()
+    tem_fallback = False
+    
+    for item in resultado.get("plano", []):
+        total_culturas += 1
+        cultura = item.get("cultura")
+        solo = item.get("solo")
+        
+        # Chave de cache: cultura|uf|municipio|solo|safra
+        cache_key = f"{cultura}|{uf}|{municipio}|{solo}|{safra}"
+        
+        # Verificar cache local
+        if cache_key in lookup_cache:
+            zarc_data = lookup_cache[cache_key]
+        else:
+            # Buscar ZARC para esta cultura/solo
+            zarc_data = buscar_zarc(
+                cultura=cultura,
+                uf=uf,
+                municipio=municipio,
+                solo=solo,
+                safra=safra
+            )
+            # Cachear resultado
+            lookup_cache[cache_key] = zarc_data
+        
+        if zarc_data and zarc_data.get("encontrado"):
+            # ZARC encontrado
+            item["zarc"] = {
+                "ativo": True,
+                "source": zarc_data.get("source"),
+                "fallback": zarc_data.get("fallback", False),
+                "janela_plantio": zarc_data.get("janela_plantio"),
+                "risco": zarc_data.get("risco"),
+                "safra": zarc_data.get("safra"),
+                "observacao": zarc_data.get("observacao"),
+                "decendios_recomendados": zarc_data.get("decendios_recomendados"),
+                "municipio_zarc": zarc_data.get("municipio"),
+                "geocodigo": zarc_data.get("geocodigo")
+            }
+            culturas_com_zarc += 1
+            sources.add(zarc_data.get("source"))
+            if zarc_data.get("fallback"):
+                tem_fallback = True
+        else:
+            # ZARC não encontrado
+            item["zarc"] = {
+                "ativo": False,
+                "message": zarc_data.get("message") if zarc_data else "ZARC não consultado"
+            }
+    
+    # Determinar source geral
+    if len(sources) == 0:
+        source_geral = "unavailable"
+    elif len(sources) == 1:
+        source_geral = list(sources)[0]
+    else:
+        source_geral = "mixed"
+    
+    # Adicionar resumo ZARC no resultado
+    resultado["zarc"] = {
+        "ativo": True,
+        "uf": uf,
+        "municipio": municipio,
+        "safra": safra,
+        "source": source_geral,
+        "fallback": tem_fallback,
+        "culturas_com_zarc": culturas_com_zarc,
+        "total_culturas": total_culturas
+    }
+    
+    return resultado
+
+def aplicar_ajuste_zarc(
+    risco_base: float,
+    risco_zarc: str,
+    aplicar: bool = False
+) -> Dict[str, Any]:
+    """
+    Calcula ajuste de risco baseado no ZARC
+    
+    Args:
+        risco_base: Risco base em pontos percentuais
+        risco_zarc: Risco ZARC (baixo, medio, alto, indeterminado)
+        aplicar: Se deve aplicar o ajuste (padrão: False)
+    
+    Returns:
+        Dicionário com risco ajustado e informações do ajuste
+    """
+    # Mapeamento de ajustes ZARC (conservadores)
+    ajustes = {
+        "baixo": -2,      # Reduz 2 pontos percentuais
+        "medio": +4,      # Aumenta 4 pontos percentuais
+        "alto": +10,      # Aumenta 10 pontos percentuais
+        "indeterminado": 0
+    }
+    
+    ajuste = ajustes.get(risco_zarc, 0)
+    
+    if aplicar and ajuste != 0:
+        risco_ajustado = min(95, max(5, risco_base + ajuste))
+    else:
+        risco_ajustado = risco_base
+    
+    return {
+        "risco_original": risco_base,
+        "risco_ajustado": risco_ajustado,
+        "ajuste_zarc": ajuste,
+        "ajuste_aplicado": aplicar,
+        "risco_zarc": risco_zarc
+    }
+
+def gerar_secao_zarc_relatorio(
+    plano: List[Dict[str, Any]],
+    uf: Optional[str] = None,
+    municipio: Optional[str] = None,
+    safra: str = "2025/2026",
+    formato: str = "md"
+) -> str:
+    """
+    Gera seção ZARC para relatório
+    
+    Args:
+        plano: Lista de itens do plano
+        uf: Unidade Federativa
+        municipio: Nome do município
+        safra: Safra
+        formato: Formato do relatório (md ou txt)
+    
+    Returns:
+        Texto da seção ZARC
+    """
+    if not uf:
+        return ""
+    
+    if formato == "md":
+        secao = "\n## 🌾 Zoneamento Agrícola de Risco Climático (ZARC)\n\n"
+        secao += f"**Região:** {municipio or 'Não especificado'}/{uf}\n"
+        secao += f"**Safra:** {safra}\n\n"
+        
+        # Contar culturas com ZARC
+        com_zarc = sum(1 for item in plano if item.get("zarc", {}).get("ativo"))
+        total = len(plano)
+        
+        secao += f"**Cobertura:** {com_zarc}/{total} culturas com recomendação ZARC\n\n"
+        
+        # Tabela por talhão
+        secao += "| Talhão | Cultura | Solo | Janela de Plantio | Risco ZARC | Fonte |\n"
+        secao += "|--------|---------|------|-------------------|------------|-------|\n"
+        
+        for item in plano:
+            talhao = item.get("talhao")
+            cultura = item.get("cultura")
+            solo = item.get("solo")
+            zarc = item.get("zarc", {})
+            
+            if zarc.get("ativo"):
+                janela = zarc.get("janela_plantio", {})
+                inicio = janela.get("inicio", "N/A")
+                fim = janela.get("fim", "N/A")
+                risco = zarc.get("risco", "N/A")
+                source = zarc.get("source", "N/A")
+                
+                # Emoji por fonte
+                if source == "zarc-oficial":
+                    fonte_emoji = "✅ Oficial"
+                elif source == "zarc-cache":
+                    fonte_emoji = "💾 Cache"
+                elif source == "zarc-fallback":
+                    fonte_emoji = "⚠️ Fallback"
+                else:
+                    fonte_emoji = source
+                
+                secao += f"| {talhao} | {cultura} | {solo} | {inicio} a {fim} | {risco} | {fonte_emoji} |\n"
+            else:
+                message = zarc.get("message", "Não encontrado")
+                secao += f"| {talhao} | {cultura} | {solo} | - | - | ⚠️ {message} |\n"
+        
+        secao += "\n"
+        
+        # Observações
+        secao += "### Observações ZARC\n\n"
+        
+        observacoes_unicas = set()
+        for item in plano:
+            zarc = item.get("zarc", {})
+            if zarc.get("ativo") and zarc.get("observacao"):
+                observacoes_unicas.add(zarc.get("observacao"))
+        
+        if observacoes_unicas:
+            for obs in observacoes_unicas:
+                secao += f"- {obs}\n"
+        else:
+            secao += "- Nenhuma recomendação ZARC encontrada para os parâmetros informados.\n"
+        
+        secao += "\n"
+        
+    else:  # txt
+        secao = "\n" + "="*80 + "\n"
+        secao += "ZONEAMENTO AGRÍCOLA DE RISCO CLIMÁTICO (ZARC)\n"
+        secao += "="*80 + "\n\n"
+        secao += f"Região: {municipio or 'Não especificado'}/{uf}\n"
+        secao += f"Safra: {safra}\n\n"
+        
+        # Contar culturas com ZARC
+        com_zarc = sum(1 for item in plano if item.get("zarc", {}).get("ativo"))
+        total = len(plano)
+        
+        secao += f"Cobertura: {com_zarc}/{total} culturas com recomendação ZARC\n\n"
+        
+        # Lista por talhão
+        for item in plano:
+            talhao = item.get("talhao")
+            cultura = item.get("cultura")
+            solo = item.get("solo")
+            zarc = item.get("zarc", {})
+            
+            secao += f"Talhão {talhao} - {cultura} ({solo})\n"
+            
+            if zarc.get("ativo"):
+                janela = zarc.get("janela_plantio", {})
+                inicio = janela.get("inicio", "N/A")
+                fim = janela.get("fim", "N/A")
+                risco = zarc.get("risco", "N/A")
+                source = zarc.get("source", "N/A")
+                
+                secao += f"  Janela de Plantio: {inicio} a {fim}\n"
+                secao += f"  Risco ZARC: {risco}\n"
+                secao += f"  Fonte: {source}\n"
+            else:
+                message = zarc.get("message", "Não encontrado")
+                secao += f"  Status: {message}\n"
+            
+            secao += "\n"
+        
+        # Observações
+        secao += "-"*80 + "\n"
+        secao += "OBSERVAÇÕES ZARC\n"
+        secao += "-"*80 + "\n\n"
+        
+        observacoes_unicas = set()
+        for item in plano:
+            zarc = item.get("zarc", {})
+            if zarc.get("ativo") and zarc.get("observacao"):
+                observacoes_unicas.add(zarc.get("observacao"))
+        
+        if observacoes_unicas:
+            for obs in observacoes_unicas:
+                secao += f"- {obs}\n"
+        else:
+            secao += "- Nenhuma recomendação ZARC encontrada para os parâmetros informados.\n"
+        
+        secao += "\n"
+    
+    return secao