Add Docker Space: FastAPI backend IViagem

app.py

@@ -1,86 +1,389 @@
+"""
+IViagem Backend (Smart + Budget + Geocode + Gemini)
+===================================================
+
+This module defines a FastAPI application providing endpoints for generating travel
+plans with cost estimates, activity suggestions, and budget adjustments.  It
+integrates with Google's Gemini models via the ``google-generativeai``
+package.  Where possible it attempts to select an appropriate model and
+generate text using the native SDK; when that fails (e.g. due to 404 errors
+for certain model/API combinations) it gracefully falls back to the REST API
+using both ``v1`` and ``v1beta`` endpoints.
+
+The code is heavily commented to aid maintenance and clarity.  Environment
+variables control model selection and API keys.  See the README or the
+``requirements.txt`` file for further details.
+"""
 
 from __future__ import annotations
 
 import os
 import math
 import random
+import logging
 from functools import lru_cache
 from datetime import date, datetime, timedelta
 from typing import List, Optional, Literal, Dict, Any, Tuple
 
 import httpx
 from dateutil.parser import isoparse
-from fastapi import FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException, Response
 from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import HTMLResponse
 from pydantic import BaseModel, Field, field_validator
 
-# ==========================
-# Gemini (google-generativeai)
-# ==========================
-GEMINI_MODEL_NAME = os.getenv("GEMINI_MODEL", "gemini-2.0-flash-exp")
-GEMINI_API_KEY = os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY")
+# =============================================================================
+# App & Configuration
+# =============================================================================
 
-_genai_model = None
-def _init_gemini():
-    global _genai_model
+# Semantic version of this backend.  Bump when behaviour changes.
+APP_VERSION = "2.3.1"
+
+# Configure the logger to integrate with uvicorn.
+log = logging.getLogger("uvicorn.error")
+
+# Initialise FastAPI app with a descriptive title and version.
+app = FastAPI(
+    title="IViagem Backend (Smart + Budget + Geocode + Gemini)",
+    version=APP_VERSION,
+)
+
+# Add CORS support.  In production you should restrict ``allow_origins``
+# to the domains of your frontend application to prevent unwanted access.
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# =============================================================================
+# Gemini (google-generativeai) integration
+# =============================================================================
+
+# Default Gemini model name.  ``gemini-flash-latest`` automatically aliases to
+# the most recent flash model supported by the API.  You can override this via
+# the GEMINI_MODEL environment variable.
+GEMINI_MODEL_NAME = os.getenv("GEMINI_MODEL", "gemini-flash-latest")
+
+# API key used to authenticate with Google's generative language API.  You can
+# supply either ``GOOGLE_API_KEY`` or ``GEMINI_API_KEY``.  Keys must start
+# with ``AIza`` for the REST API to accept them.
+GEMINI_API_KEY = (os.getenv("GOOGLE_API_KEY") or os.getenv("GEMINI_API_KEY") or "").strip()
+
+# Module‑level caches to hold the instantiated model and the effective
+# model name chosen based on API capabilities.
+_genai_model: Optional[Any] = None
+_effective_model: Optional[str] = None
+
+
+def _probe_gemini_key(api_key: str) -> tuple[bool, str]:
+    """Validate the API key by querying the models endpoint.
+
+    This helper does not log the key itself.  It returns a tuple ``(ok,
+    message)`` where ``ok`` indicates whether the key could list models
+    successfully and ``message`` provides diagnostic information.
+    """
+    if not api_key:
+        return False, "GOOGLE_API_KEY/GEMINI_API_KEY ausente."
+    if not api_key.startswith("AIza"):
+        return False, "Formato inesperado (não começa com AIza)."
+    url = f"https://generativelanguage.googleapis.com/v1/models?key={api_key}"
+    try:
+        r = httpx.get(url, timeout=10)
+        if r.status_code == 200:
+            return True, "OK"
+        return False, f"{r.status_code} {r.text[:300]}"
+    except Exception as e:
+        return False, f"Falha HTTP: {e!r}"
+
+
+def _list_models_v1(api_key: str) -> list[dict]:
+    """List models available via the REST v1 endpoint.
+
+    Returns an empty list on failure or if no models could be retrieved.
+    """
+    try:
+        r = httpx.get(
+            f"https://generativelanguage.googleapis.com/v1/models?key={api_key}",
+            timeout=10,
+        )
+        if r.status_code == 200:
+            return r.json().get("models", [])
+    except Exception:
+        pass
+    return []
+
+
+def _pick_supported_model(api_key: str, preferred: str) -> str:
+    """Select a model that supports ``generateContent``.
+
+    If the preferred model is found in the listing returned by the REST API it
+    is used.  Otherwise the first model supporting ``generateContent`` is
+    returned.  As a last resort it returns ``preferred`` unchanged.
+    """
+    models = _list_models_v1(api_key)
+    names = [m.get("name", "") for m in models]
+    if preferred in names:
+        return preferred
+    for m in models:
+        methods = (
+            m.get("supportedGenerationMethods")
+            or m.get("supported_generation_methods")
+            or []
+        )
+        if "generateContent" in methods:
+            return m["name"]
+    # Fallback: return preferred even if unknown; the REST API may still work.
+    return preferred
+
+
+@app.on_event("startup")
+def _startup_check() -> None:
+    """Log the status of the Gemini key on startup.
+
+    The startup hook runs when FastAPI starts.  It checks the API key and
+    writes a diagnostic message to the uvicorn logger.
+    """
+    key = GEMINI_API_KEY or ""
+    ok, msg = _probe_gemini_key(key)
+    if ok:
+        log.info("[startup] Gemini OK (models endpoint respondeu 200).")
+    else:
+        log.warning("[startup] Gemini inválido: %s", msg)
+
+
+def _init_gemini() -> Optional[Any]:
+    """Initialise the Gemini client once, choosing a supported model if possible.
+
+    Attempts to import ``google.generativeai`` and configure it with the API key.
+    If the module import or configuration fails, it logs a warning and
+    returns ``None``.  The effective model name is stored in the module
+    variable ``_effective_model``.
+    """
+    global _genai_model, _effective_model
     if _genai_model is not None:
         return _genai_model
     try:
-        import google.generativeai as genai
+        import google.generativeai as genai  # type: ignore
+        # If no API key is provided, do not attempt to configure the client.
         if not GEMINI_API_KEY:
             return None
+        # Choose a supported model based on the listing of available models.
+        _effective_model = _pick_supported_model(GEMINI_API_KEY, GEMINI_MODEL_NAME)
         genai.configure(api_key=GEMINI_API_KEY)
-        _genai_model = genai.GenerativeModel(GEMINI_MODEL_NAME)
+        _genai_model = genai.GenerativeModel(_effective_model)
     except Exception as e:
+        # Fall back to REST only; suppress import/config errors for clarity.
         print(f"[warn] Gemini init falhou: {e}")
         _genai_model = None
     return _genai_model
 
-def generate_text_with_llm(prompt: str, max_tokens: int = 500, temperature: float = 0.7) -> str:
-    """
-    Gera texto com Gemini. Se der erro ou não tiver API key, retorna string vazia.
+
+def _rest_generate_content(prompt: str, max_tokens: int, temperature: float) -> str:
+    """Fallback generator using the REST API.
+
+    This helper tries the ``v1`` endpoint first; if it receives a 404 it
+    automatically retries with ``v1beta``.  It returns the first non-empty
+    response it can extract or an empty string on failure.
     """
-    try:
-        model = _init_gemini()
-        if model is None:
-            return ""
-        resp = model.generate_content(
-            prompt,
-            generation_config={
-                "temperature": temperature,
-                "max_output_tokens": max_tokens,
-            },
+    model = _effective_model or GEMINI_MODEL_NAME
+    if not GEMINI_API_KEY:
+        return ""
+    # Prepare the payload in the format expected by the REST API.
+    payload = {
+        "contents": [{"role": "user", "parts": [{"text": prompt}]}],
+        "generationConfig": {"temperature": temperature, "maxOutputTokens": max_tokens},
+    }
+    # Try both API versions: first v1, then v1beta if necessary.
+    for api_ver in ("v1", "v1beta"):
+        url = (
+            f"https://generativelanguage.googleapis.com/"
+            f"{api_ver}/models/{model}:generateContent?key={GEMINI_API_KEY}"
         )
-        if hasattr(resp, "text") and resp.text:
-            return resp.text.strip()
-        parts = []
         try:
-            for c in resp.candidates or []:
-                for p in getattr(c, "content", {}).parts or []:
-                    if getattr(p, "text", ""):
-                        parts.append(p.text)
-            return "\n".join(parts).strip()
+            resp = httpx.post(url, json=payload, timeout=25)
+        except Exception as exc:
+            print(f"[warn] REST {api_ver} generateContent exceção: {exc}")
+            continue
+        if resp.status_code == 404 and api_ver == "v1":
+            # Some models (e.g. gemini-1.5-*) require the v1beta endpoint.
+            continue
+        if resp.status_code != 200:
+            print(
+                f"[warn] REST {api_ver} generateContent falhou: {resp.status_code} "
+                f"{resp.text[:200]}"
+            )
+            continue
+        try:
+            data = resp.json()
         except Exception:
-            return ""
+            continue
+        # Extract text from the returned candidates/parts structure.
+        for cand in data.get("candidates", []) or []:
+            parts = cand.get("content", {}).get("parts", []) or []
+            texts = [p.get("text", "") for p in parts if p.get("text")]
+            if texts:
+                return "\n".join(texts).strip()
+    return ""
+
+
+def generate_text_with_llm(prompt: str, max_tokens: int = 500, temperature: float = 0.7) -> str:
+    """Generate text using the Gemini SDK with safe extraction and REST fallback.
+
+    The SDK sometimes raises ``Invalid operation`` when the quick accessor
+    ``response.text`` is used and the response has no valid parts due to safety
+    filtering.  To avoid this, we never access ``resp.text`` directly; we
+    iterate over the returned candidates and extract the ``text`` from each
+    part manually.  If the SDK fails or yields no parts, we fall back to the
+    REST API.
+    """
+    try:
+        model = _init_gemini()
+        if model is not None:
+            resp = model.generate_content(
+                prompt,
+                generation_config={
+                    "temperature": temperature,
+                    "max_output_tokens": max_tokens,
+                },
+            )
+            # Always extract text by iterating through candidates and parts.  Do
+            # not call ``resp.text`` as it may raise when no valid parts exist.
+            parts_out: List[str] = []
+            for cand in getattr(resp, "candidates", []) or []:
+                content = getattr(cand, "content", {}) or {}
+                for part in getattr(content, "parts", []) or []:
+                    txt = getattr(part, "text", "")
+                    if txt:
+                        parts_out.append(txt)
+            if parts_out:
+                return "\n".join(parts_out).strip()
     except Exception as e:
-        print(f"[warn] Erro Gemini: {e}")
-        return ""
+        # Log SDK failures and proceed to REST fallback.
+        print(f"[warn] Erro Gemini (SDK): {e}")
+    # Use REST fallback if SDK generation fails or returns no text.
+    return _rest_generate_content(prompt, max_tokens, temperature)
 
-# ==========================
-# Geocodificação (Nominatim/OSM) com cache e fallback
-# ==========================
+
+# =============================================================================
+# HTTP utilitários e página raiz
+# =============================================================================
+
+@app.get("/", response_class=HTMLResponse, include_in_schema=False)
+def home() -> str:
+    """Serve uma página HTML simples na raiz da API.
+
+    A query string ``?logs=container`` é ignorada para compatibilidade com
+    a interface do Hugging Face Spaces.
+    """
+    return f"""
+    <!doctype html>
+    <html lang="pt-BR">
+    <head>
+      <meta charset="utf-8" />
+      <meta name="viewport" content="width=device-width,initial-scale=1" />
+      <title>IViagem API</title>
+      <style>
+        body {{ font-family: system-ui, -apple-system, Segoe UI, Roboto, Arial; padding: 24px; line-height:1.6; }}
+        code {{ background:#f4f4f5; padding:2px 6px; border-radius:6px; }}
+        a {{ color:#0ea5e9; text-decoration:none; }}
+        .tag {{ display:inline-block; padding:2px 6px; border-radius:999px; background:#ecfeff; color:#0e7490; font-weight:600; font-size:12px; }}
+      </style>
+    </head>
+    <body>
+      <h1>IViagem Backend</h1>
+      <p class="tag">v{APP_VERSION}</p>
+      <p>API ativa. Endpoints úteis:</p>
+      <ul>
+        <li><a href="/info">/info</a></li>
+        <li><a href="/health">/health</a></li>
+        <li><a href="/docs">/docs</a> (Swagger)</li>
+        <li><a href="/redoc">/redoc</a></li>
+      </ul>
+      <p>Exemplo <code>POST /plan</code> está em <a href="/docs">/docs</a>.</p>
+    </body>
+    </html>
+    """
+
+
+@app.get("/favicon.ico", include_in_schema=False)
+def favicon() -> Response:
+    """Return an empty 204 response for the favicon request."""
+    return Response(status_code=204)
+
+
+@app.get("/debug/gemini")
+def debug_gemini() -> Dict[str, Any]:
+    """Provide diagnostic information about the Gemini configuration.
+
+    Returns whether the key probes successfully, a masked key preview, and
+    the first few models returned by the models endpoint.  Useful for
+    debugging misconfiguration.
+    """
+    ok, msg = _probe_gemini_key(GEMINI_API_KEY or "")
+    out: Dict[str, Any] = {
+        "ok": ok,
+        "probe": msg,
+        "effective_model": _effective_model or GEMINI_MODEL_NAME,
+    }
+    if ok:
+        try:
+            r = httpx.get(
+                f"https://generativelanguage.googleapis.com/v1/models?key={GEMINI_API_KEY}",
+                timeout=10,
+            )
+            j = r.json()
+            out["first_models"] = [m["name"] for m in j.get("models", [])[:5]]
+        except Exception as e:
+            out["models_error"] = repr(e)
+    return out
+
+
+@app.get("/debug/env")
+def debug_env() -> Dict[str, Any]:
+    """Expose basic information about the configured API key.
+
+    The key itself is masked to avoid leaking secrets.  This endpoint can
+    help verify that the key is loaded and correctly formatted.
+    """
+    k = GEMINI_API_KEY or ""
+    masked = (k[:4] + "*" * max(0, len(k) - 8) + k[-4:]) if k else ""
+    return {
+        "has_key": bool(k),
+        "prefix_is_AIZa": k.startswith("AIza"),
+        "length": len(k),
+        "masked_sample": masked,
+        "effective_model": _effective_model or GEMINI_MODEL_NAME,
+    }
+
+
+# =============================================================================
+# Geocoding (Nominatim/OSM) with cache and fallback
+# =============================================================================
+
+# Toggle online geocoding via environment variable.  Set ``USE_ONLINE_GEOCODING=0``
+# to disable network calls and rely solely on built‑in city coordinates.
 USE_ONLINE_GEOCODING = os.getenv("USE_ONLINE_GEOCODING", "1") != "0"
+
 NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
 
+
 @lru_cache(maxsize=256)
-def geocode_city(query: str) -> tuple[float, float, str] | None:
+def geocode_city(query: str) -> Tuple[float, float, str] | None:
+    """Look up a city name via OpenStreetMap's Nominatim service.
+
+    Returns a tuple ``(lat, lon, display_name)`` or ``None`` if not found or
+    if online geocoding is disabled.  Results are cached for efficiency.
+    """
     if not USE_ONLINE_GEOCODING:
         return None
     q = (query or "").strip()
     if not q:
         return None
     headers = {
-        "User-Agent": "IViagem/2.3.0 (contato: suporte@ivg.local)",
+        "User-Agent": f"IViagem/{APP_VERSION} (contato: suporte@ivg.local)",
         "Accept-Language": "pt-BR",
     }
     params = {"q": q, "format": "jsonv2", "limit": 1, "addressdetails": 0}
@@ -100,10 +403,12 @@ def geocode_city(query: str) -> tuple[float, float, str] | None:
     except Exception:
         return None
 
-# ==========================
-# Geografia / cidades (catálogo local + aliases)
-# ==========================
-CITY_COORDS: Dict[str, tuple[float, float, str]] = {
+
+# =============================================================================
+# Geography / city catalogue and aliases
+# =============================================================================
+
+CITY_COORDS: Dict[str, Tuple[float, float, str]] = {
     "são paulo": (-23.5505, -46.6333, "São Paulo, SP"),
     "rio de janeiro": (-22.9068, -43.1729, "Rio de Janeiro, RJ"),
     "manaus": (-3.1190, -60.0217, "Manaus, AM"),
@@ -116,7 +421,7 @@ CITY_COORDS: Dict[str, tuple[float, float, str]] = {
     "florianópolis": (-27.5949, -48.5482, "Florianópolis, SC"),
 }
 
-CITY_ALIASES = {
+CITY_ALIASES: Dict[str, str] = {
     "amazonia": "manaus",
     "amazônia": "manaus",
     "belem": "belém",
@@ -124,16 +429,27 @@ CITY_ALIASES = {
     "sp": "são paulo",
 }
 
+
 def norm(s: str) -> str:
+    """Normalise a string to lower case and strip whitespace."""
     return (s or "").strip().lower()
 
+
 def resolve_city_key(raw: str) -> str:
+    """Map a raw city string to a canonical key using aliases."""
     k = norm(raw)
     if k in CITY_COORDS:
         return k
     return CITY_ALIASES.get(k, k)
 
-def get_coords_and_label(raw: str) -> tuple[float, float, str]:
+
+def get_coords_and_label(raw: str) -> Tuple[float, float, str]:
+    """Retrieve latitude, longitude and display label for a city.
+
+    Uses online geocoding if enabled; otherwise falls back to a predefined
+    catalogue or defaults to São Paulo when the city is unknown.  The
+    original string is used as a label when no other information is available.
+    """
     gc = geocode_city(raw)
     if gc is not None:
         return gc
@@ -144,30 +460,44 @@ def get_coords_and_label(raw: str) -> tuple[float, float, str]:
     label = raw.strip() if raw.strip() else "Destino"
     return (lat, lon, label)
 
+
+# =============================================================================
+# Utility functions
+# =============================================================================
+
 def haversine_km(a: Tuple[float, float], b: Tuple[float, float]) -> float:
+    """Compute the great-circle distance between two coordinates in km."""
     (lat1, lon1), (lat2, lon2) = a, b
     R = 6371.0
     p1, p2 = math.radians(lat1), math.radians(lat2)
     dp = math.radians(lat2 - lat1)
     dl = math.radians(lon2 - lon1)
-    x = math.sin(dp/2)**2 + math.cos(p1)*math.cos(p2)*math.sin(dl/2)**2
-    return R * 2 * math.atan2(math.sqrt(x), math.sqrt(1-x))
+    x = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return R * 2 * math.atan2(math.sqrt(x), math.sqrt(1 - x))
+
 
 def daterange(d0: date, d1: date):
+    """Yield dates between two endpoints inclusive."""
     d = d0
     while d <= d1:
         yield d
         d += timedelta(days=1)
 
+
 def is_weekend(d: date) -> bool:
+    """Return True if the given date is a weekend (Saturday or Sunday)."""
     return d.weekday() >= 5
 
-# ==========================
-# Modelos
-# ==========================
+
+# =============================================================================
+# Pydantic models
+# =============================================================================
+
 PerfilType = Literal["econômico", "equilibrado", "premium"]
 
+
 class PlanRequest(BaseModel):
+    """Schema for the /plan request body."""
     cidade_origem: str
     destino: str
     data_inicio: str
@@ -181,10 +511,13 @@ class PlanRequest(BaseModel):
     @field_validator("data_inicio", "data_fim")
     @classmethod
     def _valida_data(cls, v: str) -> str:
+        # Validate ISO date strings; raise if invalid.
         _ = isoparse(v).date()
         return v
 
+
 class Leg(BaseModel):
+    """Represents a transport leg (e.g. flight or road trip)."""
     modo: Literal["voo", "rodoviário", "fluvial", "misto"]
     origem: str
     destino: str
@@ -192,14 +525,18 @@ class Leg(BaseModel):
     duracao_h: float
     preco_estimado: float
 
+
 class ItemCusto(BaseModel):
+    """Represents an itemised cost component."""
     categoria: str
     descricao: str
     quantidade: int
     preco_unitario: float
     custo_total: float
 
+
 class DiaRoteiro(BaseModel):
+    """Represents one day's itinerary with activities and costs."""
     data: str
     manha: str
     tarde: str
@@ -207,7 +544,9 @@ class DiaRoteiro(BaseModel):
     custo_estimado_dia: float
     narrativa: Optional[str] = ""
 
+
 class PlanResponse(BaseModel):
+    """Schema for the response returned by /plan."""
     orcamento_estimado_total: float
     legs: List[Leg]
     custos_itens: List[ItemCusto]
@@ -221,76 +560,83 @@ class PlanResponse(BaseModel):
     teto_orcamento_utilizado: Optional[float] = None
     sugestoes: Optional[List[str]] = None
 
-# ==========================
-# Parâmetros de custo
-# ==========================
-PROFILE_FACTORS = {"econômico": 0.8, "equilibrado": 1.0, "premium": 1.6}
-BASES = {
+
+# =============================================================================
+# Cost parameters and points of interest (POIs)
+# =============================================================================
+
+PROFILE_FACTORS: Dict[str, float] = {"econômico": 0.8, "equilibrado": 1.0, "premium": 1.6}
+BASES: Dict[str, Any] = {
     "refeicoes": 120.0,
     "atividades": 80.0,
-    "hospedagem": {
-        "econômico": 220.0, "equilibrado": 350.0, "premium": 800.0
-    },
+    "hospedagem": {"econômico": 220.0, "equilibrado": 350.0, "premium": 800.0},
     "voo_preco_km": 0.35,
     "rod_preco_km": 0.15,
 }
 
-POIS_MANAUS = [
-    {"nome":"Teatro Amazonas","bairro":"Centro","slot":"tarde","tags":{"cultura"},"custo":60.0,"indoor":True},
-    {"nome":"Palácio Rio Negro","bairro":"Centro","slot":"manha","tags":{"cultura"},"custo":0.0,"indoor":True},
-    {"nome":"Museu da Cidade","bairro":"Centro","slot":"manha","tags":{"cultura"},"custo":20.0,"indoor":True},
-    {"nome":"Mercado Adolpho Lisboa","bairro":"Centro","slot":"manha","tags":{"gastronomia","cultura"},"custo":0.0,"indoor":False},
-    {"nome":"Café Regional no Centro","bairro":"Centro","slot":"manha","tags":{"gastronomia"},"custo":35.0,"indoor":True},
-    {"nome":"Encontro das Águas (barco)","bairro":"Marina","slot":"manha","tags":{"natureza"},"custo":220.0,"indoor":False},
-    {"nome":"MUSA – Museu da Amazônia","bairro":"Zona Norte","slot":"tarde","tags":{"natureza","cultura"},"custo":50.0,"indoor":False},
-    {"nome":"Praia da Ponta Negra (pôr do sol)","bairro":"Ponta Negra","slot":"tarde","tags":{"natureza"},"custo":0.0,"indoor":False},
-    {"nome":"Anavilhanas (day-trip)","bairro":"Marina","slot":"manha","tags":{"natureza"},"custo":480.0,"indoor":False},
-    {"nome":"Praia da Lua","bairro":"Zona Oeste","slot":"tarde","tags":{"natureza"},"custo":0.0,"indoor":False},
-    {"nome":"Jantar – Tacacá/Tambaqui","bairro":"Centro","slot":"noite","tags":{"gastronomia"},"custo":70.0,"indoor":True},
-    {"nome":"Restaurante na Ponta Negra","bairro":"Ponta Negra","slot":"noite","tags":{"gastronomia"},"custo":95.0,"indoor":True},
-    {"nome":"Bar com música regional","bairro":"Centro","slot":"noite","tags":{"cultura"},"custo":50.0,"indoor":True},
+# Define points of interest for specific cities.  Each entry includes a name,
+# neighbourhood, timeslot, tags, cost, and whether it is indoors.
+POIS_MANAUS: List[Dict[str, Any]] = [
+    {"nome": "Teatro Amazonas", "bairro": "Centro", "slot": "tarde", "tags": {"cultura"}, "custo": 60.0, "indoor": True},
+    {"nome": "Palácio Rio Negro", "bairro": "Centro", "slot": "manha", "tags": {"cultura"}, "custo": 0.0, "indoor": True},
+    {"nome": "Museu da Cidade", "bairro": "Centro", "slot": "manha", "tags": {"cultura"}, "custo": 20.0, "indoor": True},
+    {"nome": "Mercado Adolpho Lisboa", "bairro": "Centro", "slot": "manha", "tags": {"gastronomia", "cultura"}, "custo": 0.0, "indoor": False},
+    {"nome": "Café Regional no Centro", "bairro": "Centro", "slot": "manha", "tags": {"gastronomia"}, "custo": 35.0, "indoor": True},
+    {"nome": "Encontro das Águas (barco)", "bairro": "Marina", "slot": "manha", "tags": {"natureza"}, "custo": 220.0, "indoor": False},
+    {"nome": "MUSA – Museu da Amazônia", "bairro": "Zona Norte", "slot": "tarde", "tags": {"natureza", "cultura"}, "custo": 50.0, "indoor": False},
+    {"nome": "Praia da Ponta Negra (pôr do sol)", "bairro": "Ponta Negra", "slot": "tarde", "tags": {"natureza"}, "custo": 0.0, "indoor": False},
+    {"nome": "Anavilhanas (day-trip)", "bairro": "Marina", "slot": "manha", "tags": {"natureza"}, "custo": 480.0, "indoor": False},
+    {"nome": "Praia da Lua", "bairro": "Zona Oeste", "slot": "tarde", "tags": {"natureza"}, "custo": 0.0, "indoor": False},
+    {"nome": "Jantar – Tacacá/Tambaqui", "bairro": "Centro", "slot": "noite", "tags": {"gastronomia"}, "custo": 70.0, "indoor": True},
+    {"nome": "Restaurante na Ponta Negra", "bairro": "Ponta Negra", "slot": "noite", "tags": {"gastronomia"}, "custo": 95.0, "indoor": True},
+    {"nome": "Bar com música regional", "bairro": "Centro", "slot": "noite", "tags": {"cultura"}, "custo": 50.0, "indoor": True},
 ]
 
-POIS_BELEM = [
-    {"nome":"Ver-o-Peso","bairro":"Centro","slot":"manha","tags":{"gastronomia","cultura"},"custo":0.0,"indoor":False},
-    {"nome":"Mangal das Garças","bairro":"Cidade Velha","slot":"tarde","tags":{"natureza"},"custo":20.0,"indoor":False},
-    {"nome":"Basílica de Nazaré","bairro":"Nazaré","slot":"manha","tags":{"cultura"},"custo":0.0,"indoor":True},
-    {"nome":"Estação das Docas","bairro":"Campina","slot":"noite","tags":{"gastronomia","cultura"},"custo":90.0,"indoor":True},
-    {"nome":"Ilha do Combu (day-trip)","bairro":"Ribeirinha","slot":"manha","tags":{"natureza"},"custo":250.0,"indoor":False},
+POIS_BELEM: List[Dict[str, Any]] = [
+    {"nome": "Ver-o-Peso", "bairro": "Centro", "slot": "manha", "tags": {"gastronomia", "cultura"}, "custo": 0.0, "indoor": False},
+    {"nome": "Mangal das Garças", "bairro": "Cidade Velha", "slot": "tarde", "tags": {"natureza"}, "custo": 20.0, "indoor": False},
+    {"nome": "Basílica de Nazaré", "bairro": "Nazaré", "slot": "manha", "tags": {"cultura"}, "custo": 0.0, "indoor": True},
+    {"nome": "Estação das Docas", "bairro": "Campina", "slot": "noite", "tags": {"gastronomia", "cultura"}, "custo": 90.0, "indoor": True},
+    {"nome": "Ilha do Combu (day-trip)", "bairro": "Ribeirinha", "slot": "manha", "tags": {"natureza"}, "custo": 250.0, "indoor": False},
 ]
 
-POIS_RIO = [
-    {"nome":"Cristo Redentor","bairro":"Cosme Velho","slot":"manha","tags":{"cultura","natureza"},"custo":89.0,"indoor":False},
-    {"nome":"Pão de Açúcar","bairro":"Urca","slot":"tarde","tags":{"natureza"},"custo":140.0,"indoor":False},
-    {"nome":"Museu do Amanhã","bairro":"Centro","slot":"tarde","tags":{"cultura","tecnologia"},"custo":30.0,"indoor":True},
-    {"nome":"Praia de Copacabana","bairro":"Zona Sul","slot":"manha","tags":{"natureza"},"custo":0.0,"indoor":False},
-    {"nome":"Lapa à noite","bairro":"Lapa","slot":"noite","tags":{"cultura","gastronomia"},"custo":70.0,"indoor":True},
+POIS_RIO: List[Dict[str, Any]] = [
+    {"nome": "Cristo Redentor", "bairro": "Cosme Velho", "slot": "manha", "tags": {"cultura", "natureza"}, "custo": 89.0, "indoor": False},
+    {"nome": "Pão de Açúcar", "bairro": "Urca", "slot": "tarde", "tags": {"natureza"}, "custo": 140.0, "indoor": False},
+    {"nome": "Museu do Amanhã", "bairro": "Centro", "slot": "tarde", "tags": {"cultura", "tecnologia"}, "custo": 30.0, "indoor": True},
+    {"nome": "Praia de Copacabana", "bairro": "Zona Sul", "slot": "manha", "tags": {"natureza"}, "custo": 0.0, "indoor": False},
+    {"nome": "Lapa à noite", "bairro": "Lapa", "slot": "noite", "tags": {"cultura", "gastronomia"}, "custo": 70.0, "indoor": True},
 ]
 
-POIS_SAO_PAULO = [
-    {"nome":"Avenida Paulista + MASP","bairro":"Paulista","slot":"tarde","tags":{"cultura"},"custo":50.0,"indoor":True},
-    {"nome":"Beco do Batman","bairro":"Vila Madalena","slot":"manha","tags":{"cultura"},"custo":0.0,"indoor":False},
-    {"nome":"Mercadão Municipal","bairro":"Centro","slot":"manha","tags":{"gastronomia"},"custo":40.0,"indoor":True},
-    {"nome":"Ibirapuera","bairro":"Ibirapuera","slot":"tarde","tags":{"natureza"},"custo":0.0,"indoor":False},
-    {"nome":"Rooftop/Bar (noite)","bairro":"Centro/Zona Sul","slot":"noite","tags":{"gastronomia"},"custo":80.0,"indoor":True},
+POIS_SAO_PAULO: List[Dict[str, Any]] = [
+    {"nome": "Avenida Paulista + MASP", "bairro": "Paulista", "slot": "tarde", "tags": {"cultura"}, "custo": 50.0, "indoor": True},
+    {"nome": "Beco do Batman", "bairro": "Vila Madalena", "slot": "manha", "tags": {"cultura"}, "custo": 0.0, "indoor": False},
+    {"nome": "Mercadão Municipal", "bairro": "Centro", "slot": "manha", "tags": {"gastronomia"}, "custo": 40.0, "indoor": True},
+    {"nome": "Ibirapuera", "bairro": "Ibirapuera", "slot": "tarde", "tags": {"natureza"}, "custo": 0.0, "indoor": False},
+    {"nome": "Rooftop/Bar (noite)", "bairro": "Centro/Zona Sul", "slot": "noite", "tags": {"gastronomia"}, "custo": 80.0, "indoor": True},
 ]
 
-POIS_GENERIC = [
-    {"nome":"Centro histórico / praça principal","bairro":"Centro","slot":"manha","tags":{"cultura"},"custo":0.0,"indoor":False},
-    {"nome":"Museu/galeria mais bem avaliado","bairro":"Centro","slot":"tarde","tags":{"cultura"},"custo":30.0,"indoor":True},
-    {"nome":"Parque urbano / mirante","bairro":"Região central","slot":"tarde","tags":{"natureza"},"custo":0.0,"indoor":False},
-    {"nome":"Mercado público / feira gastronômica","bairro":"Centro","slot":"manha","tags":{"gastronomia"},"custo":35.0,"indoor":True},
-    {"nome":"Restaurante típico (noite)","bairro":"Centro","slot":"noite","tags":{"gastronomia"},"custo":80.0,"indoor":True},
+# Generic POIs used when a city has no specific listing.  These provide a
+# reasonable default selection of activities across different times of day.
+POIS_GENERIC: List[Dict[str, Any]] = [
+    {"nome": "Centro histórico / praça principal", "bairro": "Centro", "slot": "manha", "tags": {"cultura"}, "custo": 0.0, "indoor": False},
+    {"nome": "Museu/galeria mais bem avaliado", "bairro": "Centro", "slot": "tarde", "tags": {"cultura"}, "custo": 30.0, "indoor": True},
+    {"nome": "Parque urbano / mirante", "bairro": "Região central", "slot": "tarde", "tags": {"natureza"}, "custo": 0.0, "indoor": False},
+    {"nome": "Mercado público / feira gastronômica", "bairro": "Centro", "slot": "manha", "tags": {"gastronomia"}, "custo": 35.0, "indoor": True},
+    {"nome": "Restaurante típico (noite)", "bairro": "Centro", "slot": "noite", "tags": {"gastronomia"}, "custo": 80.0, "indoor": True},
 ]
 
-CITY_POIS = {
+# Map city keys to their specific POI lists.
+CITY_POIS: Dict[str, List[Dict[str, Any]]] = {
     "manaus": POIS_MANAUS,
     "belém": POIS_BELEM,
     "rio de janeiro": POIS_RIO,
     "são paulo": POIS_SAO_PAULO,
 }
 
+
 def get_pois_for_city(raw_city: str) -> List[Dict[str, Any]]:
+    """Return a list of POIs for the given city or a generic list if none are defined."""
     key = resolve_city_key(raw_city)
     if key in CITY_POIS:
         return CITY_POIS[key]
@@ -299,10 +645,17 @@ def get_pois_for_city(raw_city: str) -> List[Dict[str, Any]]:
         return CITY_POIS[alias]
     return POIS_GENERIC
 
-def filter_pois(pois: List[Dict[str, Any]], tags: List[str], slot: str, indoor: Optional[bool] = None) -> List[Dict[str, Any]]:
-    filtered = []
+
+def filter_pois(
+    pois: List[Dict[str, Any]],
+    tags: List[str],
+    slot: str,
+    indoor: Optional[bool] = None,
+) -> List[Dict[str, Any]]:
+    """Filter POIs by tags, time slot and indoor/outdoor criteria."""
+    filtered: List[Dict[str, Any]] = []
     for poi in pois:
-        if slot != "" and poi["slot"] != slot:
+        if slot and poi["slot"] != slot:
             continue
         if indoor is not None and poi["indoor"] != indoor:
             continue
@@ -311,44 +664,101 @@ def filter_pois(pois: List[Dict[str, Any]], tags: List[str], slot: str, indoor:
         filtered.append(poi)
     return filtered
 
-def get_random_poi(pois: List[Dict[str, Any]], exclude: List[str] = []) -> Optional[Dict[str, Any]]:
+
+def get_random_poi(pois: List[Dict[str, Any]], exclude: List[str] | None = None) -> Optional[Dict[str, Any]]:
+    """Select a random POI from the list, excluding any by name."""
+    if exclude is None:
+        exclude = []
     available = [p for p in pois if p["nome"] not in exclude]
     if not available:
         return None
     return random.choice(available)
 
-# ==========================
-# Lógica de planejamento principal
-# ==========================
-def recompute_plan(req: 'PlanRequest', d0: date, d1: date, perfil: PerfilType,
-                   force_transport: Optional[str] = None, meals_factor: float = 1.0,
-                   cap_paid: Optional[float] = None, budget_mode: bool = False,
-                   allow_daytrips: bool = True):
+
+# =============================================================================
+# Planning logic
+# =============================================================================
+
+def recompute_plan(
+    req: PlanRequest,
+    d0: date,
+    d1: date,
+    perfil: PerfilType,
+    force_transport: Optional[str] = None,
+    meals_factor: float = 1.0,
+    cap_paid: Optional[float] = None,
+    budget_mode: bool = False,
+    allow_daytrips: bool = True,
+) -> Tuple[float, List[Leg], List[ItemCusto], List[DiaRoteiro]]:
+    """Compute a detailed travel plan for the given input parameters.
+
+    Returns the total estimated budget, the list of transport legs, itemised
+    costs, and daily itinerary.  This function does not apply any budget
+    adjustments; see ``fit_to_budget`` for that.
+    """
     total_orcamento = 0.0
     legs: List[Leg] = []
     custos_itens: List[ItemCusto] = []
     roteiro: List[DiaRoteiro] = []
 
+    # Determine coordinates and labels for origin and destination.
     lat_o, lon_o, origem_label = get_coords_and_label(req.cidade_origem)
     lat_d, lon_d, destino_label = get_coords_and_label(req.destino)
     origem_coords = (lat_o, lon_o)
     destino_coords = (lat_d, lon_d)
     distancia_total_km = haversine_km(origem_coords, destino_coords)
 
+    # Compute the first leg (outbound).  Choose flight for long distances (>500 km)
+    # unless a specific transport mode is forced.
     modo_ida = force_transport if force_transport else ("voo" if distancia_total_km > 500 else "rodoviário")
     preco_ida = distancia_total_km * BASES["voo_preco_km"] if modo_ida == "voo" else distancia_total_km * BASES["rod_preco_km"]
     duracao_ida = distancia_total_km / 700 if modo_ida == "voo" else distancia_total_km / 80
-    legs.append(Leg(modo=modo_ida, origem=origem_label, destino=destino_label, distancia_km=distancia_total_km, duracao_h=duracao_ida, preco_estimado=preco_ida * req.numero_viajantes))
+    legs.append(
+        Leg(
+            modo=modo_ida,
+            origem=origem_label,
+            destino=destino_label,
+            distancia_km=distancia_total_km,
+            duracao_h=duracao_ida,
+            preco_estimado=preco_ida * req.numero_viajantes,
+        )
+    )
     total_orcamento += preco_ida * req.numero_viajantes
-    custos_itens.append(ItemCusto(categoria="Transporte", descricao=f"{modo_ida} - Ida", quantidade=req.numero_viajantes, preco_unitario=preco_ida, custo_total=preco_ida * req.numero_viajantes))
+    custos_itens.append(
+        ItemCusto(
+            categoria="Transporte",
+            descricao=f"{modo_ida} - Ida",
+            quantidade=req.numero_viajantes,
+            preco_unitario=preco_ida,
+            custo_total=preco_ida * req.numero_viajantes,
+        )
+    )
 
+    # Return leg (if travel spans at least one night).  Distances and modes mirror the outbound.
     if d0 != d1:
         modo_volta = force_transport if force_transport else ("voo" if distancia_total_km > 500 else "rodoviário")
         preco_volta = distancia_total_km * BASES["voo_preco_km"] if modo_volta == "voo" else distancia_total_km * BASES["rod_preco_km"]
         duracao_volta = distancia_total_km / 700 if modo_volta == "voo" else distancia_total_km / 80
-        legs.append(Leg(modo=modo_volta, origem=destino_label, destino=origem_label, distancia_km=distancia_total_km, duracao_h=duracao_volta, preco_estimado=preco_volta * req.numero_viajantes))
+        legs.append(
+            Leg(
+                modo=modo_volta,
+                origem=destino_label,
+                destino=origem_label,
+                distancia_km=distancia_total_km,
+                duracao_h=duracao_volta,
+                preco_estimado=preco_volta * req.numero_viajantes,
+            )
+        )
         total_orcamento += preco_volta * req.numero_viajantes
-        custos_itens.append(ItemCusto(categoria="Transporte", descricao=f"{modo_volta} - Volta", quantidade=req.numero_viajantes, preco_unitario=preco_volta, custo_total=preco_volta * req.numero_viajantes))
+        custos_itens.append(
+            ItemCusto(
+                categoria="Transporte",
+                descricao=f"{modo_volta} - Volta",
+                quantidade=req.numero_viajantes,
+                preco_unitario=preco_volta,
+                custo_total=preco_volta * req.numero_viajantes,
+            )
+        )
 
     num_dias = (d1 - d0).days + 1
     fator_perfil = PROFILE_FACTORS[perfil]
@@ -361,46 +771,128 @@ def recompute_plan(req: 'PlanRequest', d0: date, d1: date, perfil: PerfilType,
         atividades_tarde: List[str] = []
         atividades_noite: List[str] = []
 
+        # Allocate lodging cost across each day; divide by number of days to
+        # spread the cost evenly when multiple nights.
         if num_dias > 1:
             preco_hospedagem_noite = BASES["hospedagem"][perfil]
             custo_hospedagem_dia = preco_hospedagem_noite * req.numero_viajantes / num_dias
             custo_dia += custo_hospedagem_dia
-            custos_itens.append(ItemCusto(categoria="Hospedagem", descricao=f"Diária ({perfil})", quantidade=req.numero_viajantes, preco_unitario=preco_hospedagem_noite / num_dias, custo_total=custo_hospedagem_dia))
-
+            custos_itens.append(
+                ItemCusto(
+                    categoria="Hospedagem",
+                    descricao=f"Diária ({perfil})",
+                    quantidade=req.numero_viajantes,
+                    preco_unitario=preco_hospedagem_noite / num_dias,
+                    custo_total=custo_hospedagem_dia,
+                )
+            )
+
+        # Meal cost: based on profile factor, number of travellers and optional
+        # meals_factor to reduce costs when adjusting to budgets.
         custo_refeicoes_dia = BASES["refeicoes"] * req.numero_viajantes * fator_perfil * meals_factor
         custo_dia += custo_refeicoes_dia
-        custos_itens.append(ItemCusto(categoria="Alimentação", descricao=f"Refeições ({perfil})", quantidade=req.numero_viajantes, preco_unitario=BASES["refeicoes"] * fator_perfil * meals_factor, custo_total=custo_refeicoes_dia))
+        custos_itens.append(
+            ItemCusto(
+                categoria="Alimentação",
+                descricao=f"Refeições ({perfil})",
+                quantidade=req.numero_viajantes,
+                preco_unitario=BASES["refeicoes"] * fator_perfil * meals_factor,
+                custo_total=custo_refeicoes_dia,
+            )
+        )
 
-        poi_manha = get_random_poi(filter_pois(pois_destino, req.temas, "manha", indoor=False if not is_weekend(current_date) else None))
+        # Select morning activity: avoid paid indoor activities on weekdays if not weekend and not budget mode.
+        poi_manha = get_random_poi(
+            filter_pois(
+                pois_destino,
+                req.temas,
+                "manha",
+                indoor=False if not is_weekend(current_date) else None,
+            )
+        )
         if poi_manha and (not budget_mode or (cap_paid is not None and poi_manha["custo"] <= cap_paid)):
             atividades_manha.append(poi_manha["nome"])
             custo_dia += poi_manha["custo"] * req.numero_viajantes
-            custos_itens.append(ItemCusto(categoria="Atividade", descricao=poi_manha["nome"], quantidade=req.numero_viajantes, preco_unitario=poi_manha["custo"], custo_total=poi_manha["custo"] * req.numero_viajantes))
-
-        poi_tarde = get_random_poi(filter_pois(pois_destino, req.temas, "tarde"), exclude=[p["nome"] for p in [poi_manha] if p])
+            custos_itens.append(
+                ItemCusto(
+                    categoria="Atividade",
+                    descricao=poi_manha["nome"],
+                    quantidade=req.numero_viajantes,
+                    preco_unitario=poi_manha["custo"],
+                    custo_total=poi_manha["custo"] * req.numero_viajantes,
+                )
+            )
+
+        # Afternoon activity: ensure not to repeat morning activity.
+        poi_tarde = get_random_poi(
+            filter_pois(pois_destino, req.temas, "tarde"),
+            exclude=[p["nome"] for p in [poi_manha] if p],
+        )
         if poi_tarde and (not budget_mode or (cap_paid is not None and poi_tarde["custo"] <= cap_paid)):
             atividades_tarde.append(poi_tarde["nome"])
             custo_dia += poi_tarde["custo"] * req.numero_viajantes
-            custos_itens.append(ItemCusto(categoria="Atividade", descricao=poi_tarde["nome"], quantidade=req.numero_viajantes, preco_unitario=poi_tarde["custo"], custo_total=poi_tarde["custo"] * req.numero_viajantes))
-
-        poi_noite = get_random_poi(filter_pois(pois_destino, req.temas, "noite"), exclude=[p["nome"] for p in [poi_manha, poi_tarde] if p])
+            custos_itens.append(
+                ItemCusto(
+                    categoria="Atividade",
+                    descricao=poi_tarde["nome"],
+                    quantidade=req.numero_viajantes,
+                    preco_unitario=poi_tarde["custo"],
+                    custo_total=poi_tarde["custo"] * req.numero_viajantes,
+                )
+            )
+
+        # Evening activity: avoid repeating earlier activities.
+        poi_noite = get_random_poi(
+            filter_pois(pois_destino, req.temas, "noite"),
+            exclude=[p["nome"] for p in [poi_manha, poi_tarde] if p],
+        )
         if poi_noite and (not budget_mode or (cap_paid is not None and poi_noite["custo"] <= cap_paid)):
             atividades_noite.append(poi_noite["nome"])
             custo_dia += poi_noite["custo"] * req.numero_viajantes
-            custos_itens.append(ItemCusto(categoria="Atividade", descricao=poi_noite["nome"], quantidade=req.numero_viajantes, preco_unitario=poi_noite["custo"], custo_total=poi_noite["custo"] * req.numero_viajantes))
-
-        roteiro.append(DiaRoteiro(
-            data=dia_str,
-            manha=", ".join(atividades_manha) or "Atividade livre",
-            tarde=", ".join(atividades_tarde) or "Atividade livre",
-            noite=", ".join(atividades_noite) or "Atividade livre",
-            custo_estimado_dia=custo_dia
-        ))
+            custos_itens.append(
+                ItemCusto(
+                    categoria="Atividade",
+                    descricao=poi_noite["nome"],
+                    quantidade=req.numero_viajantes,
+                    preco_unitario=poi_noite["custo"],
+                    custo_total=poi_noite["custo"] * req.numero_viajantes,
+                )
+            )
+
+        roteiro.append(
+            DiaRoteiro(
+                data=dia_str,
+                manha=", ".join(atividades_manha) or "Atividade livre",
+                tarde=", ".join(atividades_tarde) or "Atividade livre",
+                noite=", ".join(atividades_noite) or "Atividade livre",
+                custo_estimado_dia=custo_dia,
+            )
+        )
         total_orcamento += custo_dia
 
     return total_orcamento, legs, custos_itens, roteiro
 
-def fit_to_budget(req: PlanRequest, d0: date, d1: date):
+
+def fit_to_budget(
+    req: PlanRequest,
+    d0: date,
+    d1: date,
+) -> Tuple[
+    float,
+    Dict[str, Any],
+    List[str],
+    Optional[Dict[str, str]],
+    Optional[List[str]],
+]:
+    """Adjust the travel plan to fit within the provided budget.
+
+    This function repeatedly recalculates the plan with different cost
+    reductions (transport mode, accommodation profile, free activities, meal
+    reductions, shorter duration) until the total is below the budget or no
+    further adjustments reduce the cost.  It returns the total cost, a
+    dictionary with legs/costs/route, a list of applied adjustments, an
+    optional adjusted period, and optional suggestions for the user.
+    """
     ajustes: List[str] = []
     periodo_ajustado: Optional[Dict[str, str]] = None
     sugestoes: Optional[List[str]] = None
@@ -413,9 +905,11 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
     allow_daytrips = True
 
     total, legs, custos, roteiro = recompute_plan(req, d0, d1, perfil)
+    # If no budget constraint or already within budget, return immediately.
     if req.teto_orcamento <= 0 or total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 1. Try switching from flights to road if flights are present.
     if any(l.modo == "voo" for l in legs):
         force_transport = "rodoviário"
         total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport=force_transport)
@@ -425,12 +919,14 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
     if total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 2. Downgrade accommodation profile if premium.
     if perfil == "premium":
         perfil = "equilibrado"
         total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport)
         if total2 < total:
             total, legs, custos, roteiro = total2, legs2, custos2, roteiro2
             ajustes.append("Hospedagem ajustada para perfil 'equilibrado'.")
+    # 3. Further downgrade to econômico if still over budget.
     if total > req.teto_orcamento and perfil in ("equilibrado", "premium"):
         perfil = "econômico"
         total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport)
@@ -440,31 +936,41 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
     if total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 4. Prioritise free or low‑cost activities.
     budget_mode = True
     cap_paid = 60.0
-    total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport, cap_paid=cap_paid, budget_mode=budget_mode)
+    total2, legs2, custos2, roteiro2 = recompute_plan(
+        req, d0, d1, perfil, force_transport, cap_paid=cap_paid, budget_mode=budget_mode
+    )
     if total2 < total:
         total, legs, custos, roteiro = total2, legs2, custos2, roteiro2
         ajustes.append("Atividades priorizadas para opções gratuitas/baixas (teto por pessoa/dia).")
     if total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 5. Remove day‑trips (long excursions) if still above budget.
     allow_daytrips = False
-    total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport, cap_paid=cap_paid, budget_mode=budget_mode, allow_daytrips=allow_daytrips)
+    total2, legs2, custos2, roteiro2 = recompute_plan(
+        req, d0, d1, perfil, force_transport, cap_paid=cap_paid, budget_mode=budget_mode, allow_daytrips=allow_daytrips
+    )
     if total2 < total:
         total, legs, custos, roteiro = total2, legs2, custos2, roteiro2
-        ajustes.append("Day-trips removidas.")
+        ajustes.append("Day‑trips removidas.")
     if total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 6. Reduce meal cost by 15%.
     meals_factor = 0.85
-    total2, legs2, custos2, roteiro2 = recompute_plan(req, d0, d1, perfil, force_transport, meals_factor=meals_factor, cap_paid=cap_paid, budget_mode=budget_mode, allow_daytrips=allow_daytrips)
+    total2, legs2, custos2, roteiro2 = recompute_plan(
+        req, d0, d1, perfil, force_transport, meals_factor=meals_factor, cap_paid=cap_paid, budget_mode=budget_mode, allow_daytrips=allow_daytrips
+    )
     if total2 < total:
         total, legs, custos, roteiro = total2, legs2, custos2, roteiro2
         ajustes.append("Alimentação otimizada (~15% mais em conta).")
     if total <= req.teto_orcamento:
         return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+    # 7. Shorten the trip by reducing days at the end.
     cur_d1 = d1
     while total > req.teto_orcamento and (cur_d1 - d0).days + 1 > 2:
         cur_d1 = cur_d1 - timedelta(days=1)
@@ -475,7 +981,10 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
             total, legs, custos, roteiro = total2, legs2, custos2, roteiro2
             periodo_ajustado = {"data_inicio": d0.isoformat(), "data_fim": cur_d1.isoformat()}
             ajustes.append("Viagem encurtada ao final para adequar ao orçamento.")
+        if total <= req.teto_orcamento:
+            break
 
+    # If still above budget, provide suggestions.
     if total > req.teto_orcamento:
         sugestoes = [
             "Considere reduzir o número de viajantes ou dividir quartos.",
@@ -485,30 +994,43 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
 
     return total, {"legs": legs, "custos": custos, "roteiro": roteiro}, ajustes, periodo_ajustado, sugestoes
 
+
 def risk_tag(raw_dest: str) -> str:
+    """Return a simple climate risk tag for a destination."""
     k = resolve_city_key(raw_dest)
     if k in ("manaus", "belém"):
         return "Médio (chuvas tropicais / calor úmido)"
     return "Baixo"
 
-APP_VERSION = "2.3.0"
-app = FastAPI(title="IViagem Backend (Smart + Budget + Geocode + Gemini)", version=APP_VERSION)
-app.add_middleware(
-    CORSMiddleware, allow_origins=["*"], allow_credentials=True,
-    allow_methods=["*"], allow_headers=["*"],
-)
+
+# =============================================================================
+# Endpoints
+# =============================================================================
 
 @app.get("/health")
-def health():
+def health() -> Dict[str, str]:
+    """Health check endpoint; returns current UTC timestamp."""
     return {"status": "ok", "ts": datetime.utcnow().isoformat()}
 
+
 @app.get("/info")
-def info():
-    return {"name": "IViagem Planner (smart + budget + geocode + gemini)",
-            "version": APP_VERSION, "endpoints": ["/health", "/info", "/plan"]}
+def info() -> Dict[str, Any]:
+    """Return basic information about the API and its endpoints."""
+    return {
+        "name": "IViagem Planner (smart + budget + geocode + gemini)",
+        "version": APP_VERSION,
+        "effective_model": _effective_model or GEMINI_MODEL_NAME,
+        "endpoints": ["/health", "/info", "/plan", "/debug/gemini", "/debug/env", "/geocode"],
+    }
+
 
 @app.post("/plan", response_model=PlanResponse)
-def plan(req: PlanRequest):
+def plan(req: PlanRequest) -> PlanResponse:
+    """Compute and return a detailed travel plan based on the request.
+
+    Validates input dates, adjusts the plan to respect the provided budget,
+    computes risk tags and generates narrative observations using the LLM.
+    """
     try:
         d0 = isoparse(req.data_inicio).date()
         d1 = isoparse(req.data_fim).date()
@@ -518,16 +1040,15 @@ def plan(req: PlanRequest):
         raise HTTPException(status_code=400, detail="data_fim não pode ser anterior a data_inicio.")
 
     total, parts, ajustes, periodo_ajustado, sugestoes = fit_to_budget(req, d0, d1)
-
     legs = parts["legs"]
     custos_itens = parts["custos"]
     roteiro = parts["roteiro"]
 
-    tempo_voo_total = None
+    tempo_voo_total: Optional[str] = None
     if any(l.modo == "voo" for l in legs):
         tempo_voo_total = f"{round(sum(l.duracao_h for l in legs), 1)} h"
 
-    economia_vs_base = None
+    economia_vs_base: Optional[float] = None
     if req.teto_orcamento and req.teto_orcamento > 0:
         economia_vs_base = round(req.teto_orcamento - total, 2)
 
@@ -535,7 +1056,9 @@ def plan(req: PlanRequest):
     risco = risk_tag(req.destino)
 
     periodo_txt = ""
-    if periodo_ajustado and (periodo_ajustado['data_inicio'] != req.data_inicio or periodo_ajustado['data_fim'] != req.data_fim):
+    if periodo_ajustado and (
+        periodo_ajustado["data_inicio"] != req.data_inicio or periodo_ajustado["data_fim"] != req.data_fim
+    ):
         periodo_txt = f" Período ajustado: {periodo_ajustado['data_inicio']} a {periodo_ajustado['data_fim']}."
 
     temas_txt = ", ".join(req.temas)
@@ -553,6 +1076,7 @@ def plan(req: PlanRequest):
             f" Período solicitado: {req.data_inicio} a {req.data_fim}.{periodo_txt} Moeda: {req.moeda}."
         )
 
+    # Generate a narrative for each day using the LLM.
     for dia in roteiro:
         dia_prompt = (
             f"Crie uma narrativa curta para o dia {dia.data} em {destino_label}. "
@@ -563,6 +1087,8 @@ def plan(req: PlanRequest):
         narrativa = generate_text_with_llm(dia_prompt, max_tokens=150, temperature=0.9)
         dia.narrativa = narrativa or ""
 
+    # Suggestion generation: if no suggestions were generated during budget fitting,
+    # use the LLM to propose tips; otherwise return the existing suggestions.
     if sugestoes is None:
         sugestao_prompt = (
             f"Com base no planejamento {req.cidade_origem} → {destino_label} ({req.data_inicio} a {req.data_fim}), "
@@ -594,11 +1120,13 @@ def plan(req: PlanRequest):
         sugestoes=sugestoes or None,
     )
 
+
 @app.get("/geocode")
-def geocode(q: str):
+def geocode(q: str) -> Dict[str, Any]:
+    """Geocode a location name, returning online and fallback coordinates."""
     gc = geocode_city(q)
     if gc is None:
         lat, lon, label = get_coords_and_label(q)
         return {"online": None, "fallback": {"lat": lat, "lon": lon, "label": label}}
     lat, lon, label = gc
-    return {"online": {"lat": lat, "lon": lon, "label": label}}
+    return {"online": {"lat": lat, "lon": lon, "label": label}}

app/main.py

@@ -230,19 +230,18 @@ def _rest_generate_content(prompt: str, max_tokens: int, temperature: float) ->
 
 
 def generate_text_with_llm(prompt: str, max_tokens: int = 500, temperature: float = 0.7) -> str:
-    """Generate text using Gemini with a fallback to the REST API.
-
-    Tries to call the SDK's ``generate_content`` method; if that fails or
-    produces no text, it falls back to ``_rest_generate_content``.  Returns
-    an empty string if all attempts fail.
+    """Generate text using the Gemini SDK with safe extraction and REST fallback.
+
+    The SDK sometimes raises ``Invalid operation`` when the quick accessor
+    ``response.text`` is used and the response has no valid parts due to safety
+    filtering.  To avoid this, we never access ``resp.text`` directly; we
+    iterate over the returned candidates and extract the ``text`` from each
+    part manually.  If the SDK fails or yields no parts, we fall back to the
+    REST API.
     """
     try:
         model = _init_gemini()
         if model is not None:
-            # Use the SDK to generate content.  Note: older versions of the
-            # SDK return an object where ``text`` may be empty if the content
-            # was blocked or truncated; in that case we iterate over
-            # candidates/parts.
             resp = model.generate_content(
                 prompt,
                 generation_config={
@@ -250,21 +249,19 @@ def generate_text_with_llm(prompt: str, max_tokens: int = 500, temperature: floa
                     "max_output_tokens": max_tokens,
                 },
             )
-            # ``text`` is a quick accessor for the full text when available.
-            if hasattr(resp, "text") and resp.text:
-                return resp.text.strip()
-            # Fallback: iterate candidates/parts manually.
+            # Always extract text by iterating through candidates and parts.  Do
+            # not call ``resp.text`` as it may raise when no valid parts exist.
             parts_out: List[str] = []
-            for c in getattr(resp, "candidates", []) or []:
-                content = getattr(c, "content", {}) or {}
-                for p in getattr(content, "parts", []) or []:
-                    text = getattr(p, "text", "")
-                    if text:
-                        parts_out.append(text)
+            for cand in getattr(resp, "candidates", []) or []:
+                content = getattr(cand, "content", {}) or {}
+                for part in getattr(content, "parts", []) or []:
+                    txt = getattr(part, "text", "")
+                    if txt:
+                        parts_out.append(txt)
             if parts_out:
                 return "\n".join(parts_out).strip()
     except Exception as e:
-        # In case of any exception with the SDK, log and fall back.
+        # Log SDK failures and proceed to REST fallback.
         print(f"[warn] Erro Gemini (SDK): {e}")
     # Use REST fallback if SDK generation fails or returns no text.
     return _rest_generate_content(prompt, max_tokens, temperature)