agroplan-ai-cli 1.0.21 → 1.0.23

package/backend-template/VERSION.json

@@ -1,13 +1,14 @@
 {
-  "cli_version": "1.0.21",
-  "backend_template_version": "1.0.21",
+  "cli_version": "1.0.23",
+  "backend_template_version": "1.0.23",
   "zarc_index_version": "2025-2026-fast-index-v2",
   "features": [
     "zarc_fast_index",
     "zarc_fallback_sorgo_mandioca",
     "soil_normalization_misto_siltoso",
     "climate_real_data",
-    "hybrid_mode"
+    "hybrid_mode",
+    "report_generator_zarc_support"
   ],
-  "generated_at": "2026-05-09T18:30:00Z"
+  "generated_at": "2026-05-09T19:00:00Z"
 }

package/backend-template/api.py

@@ -151,7 +151,15 @@ def health():
         from providers.zarc_provider import get_zarc_status
         zarc_status = get_zarc_status()
         
-        return {
+        # Carregar VERSION.json se existir
+        version_info = {}
+        version_path = os.path.join(os.path.dirname(__file__), "VERSION.json")
+        if os.path.exists(version_path):
+            import json
+            with open(version_path, 'r') as f:
+                version_info = json.load(f)
+        
+        response = {
             "status": "healthy",
             "culturas": len(culturas),
             "talhoes": len(talhoes),
@@ -164,9 +172,169 @@ def health():
             },
             "provider_cache": provider_cache_stats
         }
+        
+        # Adicionar info de versão se disponível
+        if version_info:
+            response["backend_template_version"] = version_info.get("backend_template_version")
+            response["zarc_index_version"] = version_info.get("zarc_index_version")
+        
+        return response
     except Exception as e:
         raise HTTPException(status_code=500, detail=str(e))
 
+@app.get("/debug/version")
+def debug_version():
+    """Retorna informações detalhadas de versão e configuração do backend"""
+    try:
+        import json
+        from providers.zarc_provider import (
+            ZARC_FAST_INDEX_ENABLED,
+            ZARC_ALLOW_FULL_SCAN,
+            load_zarc_index,
+            get_zarc_fallback
+        )
+        
+        # Carregar VERSION.json
+        version_info = {}
+        version_path = os.path.join(os.path.dirname(__file__), "VERSION.json")
+        if os.path.exists(version_path):
+            with open(version_path, 'r') as f:
+                version_info = json.load(f)
+        
+        # Verificar índice ZARC
+        zarc_index = load_zarc_index()
+        zarc_index_info = {}
+        zarc_index_keys_sample = []
+        
+        if zarc_index:
+            records = zarc_index.get("records", {})
+            zarc_index_info = {
+                "exists": True,
+                "total_records": len(records),
+                "generated_at": zarc_index.get("generated_at"),
+                "source": zarc_index.get("source")
+            }
+            # Sample de 10 primeiras chaves
+            zarc_index_keys_sample = list(records.keys())[:10]
+        else:
+            zarc_index_info = {"exists": False}
+        
+        # Verificar fallbacks
+        fallback_data = get_zarc_fallback()
+        culturas_fallback = set(item.get("cultura") for item in fallback_data)
+        
+        return {
+            "api_version": "5.0.0",
+            "backend_file": __file__,
+            "backend_template_version": version_info.get("backend_template_version", "unknown"),
+            "cli_version": version_info.get("cli_version", "unknown"),
+            "zarc_index_version": version_info.get("zarc_index_version", "unknown"),
+            "features": version_info.get("features", []),
+            "generated_at": version_info.get("generated_at"),
+            "zarc_config": {
+                "fast_index_enabled": ZARC_FAST_INDEX_ENABLED,
+                "allow_full_scan": ZARC_ALLOW_FULL_SCAN,
+                "index": zarc_index_info,
+                "index_keys_sample": zarc_index_keys_sample
+            },
+            "zarc_fallback": {
+                "total_records": len(fallback_data),
+                "culturas": sorted(list(culturas_fallback)),
+                "has_sorgo": "sorgo" in culturas_fallback,
+                "has_mandioca": "mandioca" in culturas_fallback
+            },
+            "data_mode": DATA_MODE,
+            "weather_provider": WEATHER_PROVIDER
+        }
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/debug/zarc-coverage")
+def debug_zarc_coverage(
+    uf: Optional[str] = Query(None, description="UF"),
+    municipio: Optional[str] = Query(None, description="Município"),
+    safra: str = Query("2025/2026", description="Safra")
+):
+    """Retorna diagnóstico detalhado de cobertura ZARC"""
+    try:
+        import json
+        from core.zarc_adapter import enriquecer_plano_com_zarc
+        
+        # Usar o mesmo plano do dashboard
+        resultado_ag = get_ag_cacheado(objetivo="equilibrado")
+        
+        # Enriquecer com ZARC
+        resultado_enriquecido = enriquecer_plano_com_zarc(
+            resultado_ag,
+            uf=uf,
+            municipio=municipio,
+            safra=safra
+        )
+        
+        # Analisar cobertura
+        detalhes = []
+        culturas_com_zarc = 0
+        culturas_fallback = 0
+        culturas_unavailable = 0
+        
+        for item in resultado_enriquecido["plano"]:
+            zarc = item.get("zarc", {})
+            
+            detalhes.append({
+                "talhao": item.get("talhao"),
+                "cultura": item.get("cultura"),
+                "solo_original": item.get("solo"),
+                "zarc_ativo": zarc.get("ativo", False),
+                "zarc_source": zarc.get("source"),
+                "zarc_fallback": zarc.get("fallback", False),
+                "zarc_message": zarc.get("message"),
+                "zarc_janela": zarc.get("janela_plantio")
+            })
+            
+            if zarc.get("ativo"):
+                culturas_com_zarc += 1
+                if zarc.get("fallback"):
+                    culturas_fallback += 1
+            else:
+                culturas_unavailable += 1
+        
+        total_culturas = len(resultado_enriquecido["plano"])
+        coverage_percent = (culturas_com_zarc / total_culturas * 100) if total_culturas > 0 else 0
+        
+        # Carregar VERSION.json
+        version_info = {}
+        version_path = os.path.join(os.path.dirname(__file__), "VERSION.json")
+        if os.path.exists(version_path):
+            with open(version_path, 'r') as f:
+                version_info = json.load(f)
+        
+        # Verificar índice ZARC
+        from providers.zarc_provider import load_zarc_index
+        zarc_index = load_zarc_index()
+        zarc_index_total = len(zarc_index.get("records", {})) if zarc_index else 0
+        
+        return {
+            "uf": uf,
+            "municipio": municipio,
+            "safra": safra,
+            "summary": {
+                "culturas_com_zarc": culturas_com_zarc,
+                "culturas_fallback": culturas_fallback,
+                "culturas_unavailable": culturas_unavailable,
+                "total_culturas": total_culturas,
+                "coverage_percent": round(coverage_percent, 1)
+            },
+            "backend_info": {
+                "backend_template_version": version_info.get("backend_template_version", "unknown"),
+                "zarc_index_version": version_info.get("zarc_index_version", "unknown"),
+                "zarc_index_total_records": zarc_index_total
+            },
+            "details": detalhes
+        }
+    except Exception as e:
+        import traceback
+        raise HTTPException(status_code=500, detail=f"{str(e)}\n{traceback.format_exc()}")
+
 @app.get("/dados/clima")
 def get_clima(
     lat: Optional[float] = Query(None, description="Latitude"),
@@ -850,14 +1018,37 @@ def limpar_cache(request: Request):
                 detail="Token de administração inválido ou ausente. Use header X-Cache-Token."
             )
     
-    # Limpa cache
+    # Limpa cache de resultados
     global _resultados_cache
     items_removidos = len(_resultados_cache)
     _resultados_cache.clear()
     
+    # Limpa cache de provedores (weather, etc)
+    provider_items_removidos = 0
+    try:
+        from providers.cache import clear_provider_cache
+        provider_items_removidos = clear_provider_cache()
+    except Exception:
+        pass
+    
+    # Limpa cache do índice ZARC em memória
+    zarc_cache_cleared = False
+    try:
+        from providers import zarc_provider
+        if hasattr(zarc_provider, '_zarc_index_cache'):
+            zarc_provider._zarc_index_cache.clear()
+            zarc_cache_cleared = True
+    except Exception:
+        pass
+    
     return {
         "status": "ok",
-        "message": f"Cache limpo. {items_removidos} itens removidos.",
+        "message": f"Cache limpo completamente.",
+        "details": {
+            "resultados_cache": items_removidos,
+            "provider_cache": provider_items_removidos,
+            "zarc_index_cache": "cleared" if zarc_cache_cleared else "not_found"
+        },
         "protected": bool(cache_admin_token)
     }
 

package/backend-template/core/report_generator.py

@@ -98,7 +98,7 @@ def get_objetivo_description(objetivo):
     return descriptions.get(objetivo, "otimizou múltiplos critérios")
 
 
-def gerar_relatorio_completo(culturas, talhoes, regras, objetivo='equilibrado', formato='md', contexto_climatico=None):
+def gerar_relatorio_completo(culturas, talhoes, regras, objetivo='equilibrado', formato='md', contexto_climatico=None, uf=None, municipio=None, safra="2025/2026"):
     """
     Gera relatório completo do sistema
     
@@ -109,6 +109,9 @@ def gerar_relatorio_completo(culturas, talhoes, regras, objetivo='equilibrado',
         objetivo: objetivo do AG
         formato: 'md' ou 'txt'
         contexto_climatico: Dicionário com dados climáticos reais (opcional)
+        uf: Unidade Federativa para ZARC (opcional)
+        municipio: Município para ZARC (opcional)
+        safra: Safra ZARC (padrão: 2025/2026)
     
     Returns:
         Caminho do arquivo gerado
@@ -151,6 +154,14 @@ def gerar_relatorio_completo(culturas, talhoes, regras, objetivo='equilibrado',
         secao_clima = gerar_secao_climatica(contexto_climatico, formato)
         conteudo += "\n\n" + secao_clima
     
+    # Adicionar seção ZARC se disponível
+    if uf:
+        from core.zarc_adapter import enriquecer_plano_com_zarc, gerar_secao_zarc_relatorio
+        resultado_temp = {"plano": resultado_ag["plano"]}
+        resultado_temp = enriquecer_plano_com_zarc(resultado_temp, uf, municipio, safra)
+        secao_zarc = gerar_secao_zarc_relatorio(resultado_temp["plano"], uf, municipio, safra, formato)
+        conteudo += "\n\n" + secao_zarc
+    
     # Salva arquivo
     os.makedirs('reports', exist_ok=True)
     timestamp = datetime.now().strftime('%Y%m%d_%H%M%S')

package/backend-template/core/zarc_adapter.py

@@ -78,10 +78,10 @@ def enriquecer_plano_com_zarc(
             if zarc_data.get("fallback"):
                 tem_fallback = True
         else:
-            # ZARC não encontrado
+            # ZARC não encontrado - usar mensagem honesta
             item["zarc"] = {
                 "ativo": False,
-                "message": zarc_data.get("message") if zarc_data else "ZARC não consultado"
+                "message": zarc_data.get("message", "ZARC consultado, mas sem recomendação disponível para esta cultura/região.")
             }
     
     # Determinar source geral

package/backend-template/providers/zarc_provider.py

@@ -304,6 +304,36 @@ def normalizar_solo(solo: str) -> str:
     """Normaliza tipo de solo"""
     return normalizar_texto(solo)
 
+def normalizar_solo_zarc(solo: str) -> str:
+    """
+    Normaliza tipo de solo para busca ZARC
+    
+    Mapeia variações de solo para os tipos reconhecidos pelo ZARC:
+    - misto -> medio
+    - siltoso -> medio
+    
+    Args:
+        solo: Tipo de solo original
+    
+    Returns:
+        Tipo de solo normalizado para ZARC
+    """
+    if not solo:
+        return ""
+    
+    solo_norm = normalizar_solo(solo)
+    
+    # Mapeamento de solos para ZARC
+    mapa_zarc = {
+        "arenoso": "arenoso",
+        "medio": "medio",
+        "misto": "medio",      # misto -> medio
+        "siltoso": "medio",    # siltoso -> medio
+        "argiloso": "argiloso"
+    }
+    
+    return mapa_zarc.get(solo_norm, solo_norm)
+
 def get_cache_path(safra: str) -> str:
     """Retorna caminho do arquivo de cache para a safra"""
     os.makedirs(ZARC_CACHE_DIR, exist_ok=True)
@@ -427,15 +457,15 @@ def buscar_zarc_indexado(
     # Tentar diferentes combinações de solo
     solos_tentar = []
     if solo:
-        solo_norm = normalizar_solo(solo)
+        solo_norm = normalizar_solo_zarc(solo)  # Usa normalização ZARC (misto->medio, siltoso->medio)
         # Tentar o solo especificado primeiro, depois outros como fallback
-        solos_tentar = [solo_norm, "medio", "arenoso", "argiloso", "misto"]
+        solos_tentar = [solo_norm, "medio", "arenoso", "argiloso"]
         # Remover duplicatas mantendo ordem
         seen = set()
         solos_tentar = [s for s in solos_tentar if not (s in seen or seen.add(s))]
     else:
         # Se não especificou solo, tentar todos (preferir medio/argiloso)
-        solos_tentar = ["medio", "argiloso", "arenoso", "misto"]
+        solos_tentar = ["medio", "argiloso", "arenoso"]
     
     # Buscar no índice
     for solo_test in solos_tentar:
@@ -680,6 +710,48 @@ def get_zarc_fallback() -> List[Dict[str, Any]]:
             "janela_fim": "31/03",
             "risco": "baixo",
             "safra": "2025/2026"
+        },
+        # Sorgo
+        {
+            "cultura": "sorgo",
+            "uf": "SP",
+            "municipio": "ribeirao preto",
+            "solo": "medio",
+            "janela_inicio": "15/10",
+            "janela_fim": "15/12",
+            "risco": "medio",
+            "safra": "2025/2026"
+        },
+        {
+            "cultura": "sorgo",
+            "uf": "MG",
+            "municipio": "uberlandia",
+            "solo": "medio",
+            "janela_inicio": "01/10",
+            "janela_fim": "30/11",
+            "risco": "medio",
+            "safra": "2025/2026"
+        },
+        # Mandioca
+        {
+            "cultura": "mandioca",
+            "uf": "SP",
+            "municipio": "sao paulo",
+            "solo": "medio",
+            "janela_inicio": "01/09",
+            "janela_fim": "31/03",
+            "risco": "baixo",
+            "safra": "2025/2026"
+        },
+        {
+            "cultura": "mandioca",
+            "uf": "PR",
+            "municipio": "londrina",
+            "solo": "medio",
+            "janela_inicio": "15/08",
+            "janela_fim": "31/03",
+            "risco": "baixo",
+            "safra": "2025/2026"
         }
     ]
 
@@ -689,12 +761,14 @@ def buscar_zarc(
     municipio: Optional[str] = None,
     solo: Optional[str] = None,
     safra: str = ZARC_SAFRA_DEFAULT
-) -> Optional[Dict[str, Any]]:
+) -> Dict[str, Any]:
     """
     Busca dados ZARC para cultura/região específica
     
     PERFORMANCE: Tenta índice primeiro (rápido), depois streaming (lento)
     
+    SEMPRE retorna um dicionário, nunca None
+    
     Args:
         cultura: Nome da cultura
         uf: Unidade Federativa (opcional)
@@ -703,7 +777,7 @@ def buscar_zarc(
         safra: Safra (padrão: 2025/2026)
     
     Returns:
-        Dicionário com dados ZARC ou None se não encontrar
+        Dicionário com dados ZARC (sempre retorna, nunca None)
     """
     # FAST PATH: Tentar índice primeiro (O(1) lookup)
     if ZARC_FAST_INDEX_ENABLED:
@@ -718,7 +792,14 @@ def buscar_zarc(
         return buscar_zarc_fallback(cultura, uf, municipio, solo, safra)
     
     # Full scan permitido (desenvolvimento local)
-    return buscar_zarc_streaming(cultura, uf, municipio, solo, safra)
+    resultado_streaming = buscar_zarc_streaming(cultura, uf, municipio, solo, safra)
+    
+    # buscar_zarc_streaming pode retornar None se arquivo não disponível
+    # Nesse caso, usar fallback
+    if resultado_streaming is None:
+        return buscar_zarc_fallback(cultura, uf, municipio, solo, safra)
+    
+    return resultado_streaming
 
 def buscar_zarc_streaming(
     cultura: str,
@@ -737,7 +818,7 @@ def buscar_zarc_streaming(
     cultura_norm = normalizar_cultura(cultura)
     uf_norm = normalizar_uf(uf) if uf else None
     municipio_norm = normalizar_municipio(municipio) if municipio else None
-    solo_norm = normalizar_solo(solo) if solo else None
+    solo_norm = normalizar_solo_zarc(solo) if solo else None  # Usa normalização ZARC
     
     # Tentar obter arquivo ZARC
     file_info = ensure_zarc_file(safra)
@@ -768,7 +849,7 @@ def buscar_zarc_streaming(
             # Solo (se fornecido)
             if solo_norm:
                 solo_registro = mapear_codigo_solo(registro.get("Cod_Solo", ""))
-                if normalizar_solo(solo_registro) == solo_norm:
+                if normalizar_solo_zarc(solo_registro) == solo_norm:  # Usa normalização ZARC
                     score += 2
             
             # Manter apenas o melhor match (não acumula lista)
@@ -837,15 +918,17 @@ def buscar_zarc_fallback(
     municipio: Optional[str] = None,
     solo: Optional[str] = None,
     safra: str = ZARC_SAFRA_DEFAULT
-) -> Optional[Dict[str, Any]]:
+) -> Dict[str, Any]:
     """
     Busca ZARC em dados simplificados (fallback)
+    
+    SEMPRE retorna um dicionário, nunca None
     """
     # Normalizar parâmetros
     cultura_norm = normalizar_cultura(cultura)
     uf_norm = normalizar_uf(uf) if uf else None
     municipio_norm = normalizar_municipio(municipio) if municipio else None
-    solo_norm = normalizar_solo(solo) if solo else None
+    solo_norm = normalizar_solo_zarc(solo) if solo else None  # Usa normalização ZARC
     
     # Fallback: usar dados simplificados (lista pequena em memória)
     fallback_data = get_zarc_fallback()
@@ -869,7 +952,7 @@ def buscar_zarc_fallback(
             score += 3
         
         # Solo (se fornecido)
-        if solo_norm and normalizar_solo(registro.get("solo", "")) == solo_norm:
+        if solo_norm and normalizar_solo_zarc(registro.get("solo", "")) == solo_norm:  # Usa normalização ZARC
             score += 2
         
         if score > melhor_score:
@@ -894,4 +977,11 @@ def buscar_zarc_fallback(
             "observacao": "Dados simplificados locais usados porque o CSV oficial não estava disponível."
         }
     
-    return None
+    # Nenhum match encontrado - retornar estado "unavailable" em vez de None
+    return {
+        "encontrado": False,
+        "source": "zarc-unavailable",
+        "fallback": False,
+        "message": "ZARC consultado, mas nenhuma recomendação foi encontrada para esta cultura, solo e região.",
+        "observacao": "A cultura pode não estar disponível no índice ZARC compacto para a região selecionada."
+    }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agroplan-ai-cli",
-  "version": "1.0.21",
+  "version": "1.0.23",
   "description": "CLI global para AgroPlan AI - modo local acelerado",
   "type": "module",
   "bin": {