Add Docker Space: FastAPI backend IViagem

app/main.py

@@ -1,3 +1,20 @@
+"""
+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
@@ -15,37 +32,59 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.responses import HTMLResponse
 from pydantic import BaseModel, Field, field_validator
 
-# ==========================
-# App & Config
-# ==========================
-APP_VERSION = "2.3.0"
+# =============================================================================
+# App & Configuration
+# =============================================================================
+
+# 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=["*"],  # ajuste depois para as URLs do seu front
+    allow_origins=["*"],
     allow_credentials=True,
     allow_methods=["*"],
     allow_headers=["*"],
 )
 
-# ==========================
-# Gemini (google-generativeai)
-# ==========================
-GEMINI_MODEL_NAME = os.getenv("GEMINI_MODEL", "gemini-1.5-flash")
+# =============================================================================
+# 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()
 
-_genai_model = None
+# 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]:
-    """Valida a key chamando /v1/models. Não expõe a chave nos logs."""
+    """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"):
@@ -61,7 +100,10 @@ def _probe_gemini_key(api_key: str) -> tuple[bool, str]:
 
 
 def _list_models_v1(api_key: str) -> list[dict]:
-    """Lista modelos disponíveis via REST v1."""
+    """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}",
@@ -75,9 +117,11 @@ def _list_models_v1(api_key: str) -> list[dict]:
 
 
 def _pick_supported_model(api_key: str, preferred: str) -> str:
-    """
-    Escolhe um modelo disponível que suporte generateContent.
-    Se o preferred existir, usa-o; senão, pega o primeiro que tenha generateContent.
+    """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]
@@ -91,12 +135,17 @@ def _pick_supported_model(api_key: str, preferred: str) -> str:
         )
         if "generateContent" in methods:
             return m["name"]
-    # fallback: devolve preferred mesmo assim (o REST pode funcionar em alguns ambientes)
+    # Fallback: return preferred even if unknown; the REST API may still work.
     return preferred
 
 
 @app.on_event("startup")
-def _startup_check():
+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:
@@ -105,61 +154,95 @@ def _startup_check():
         log.warning("[startup] Gemini inválido: %s", msg)
 
 
-def _init_gemini():
-    """Inicializa o cliente do Gemini uma única vez, com escolha de modelo suportado."""
+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(_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 _rest_generate_content_v1(prompt: str, max_tokens: int, temperature: float) -> str:
-    """
-    Fallback REST v1 para contornar ambientes em que o SDK usa v1beta
-    e retorna 404 para alguns modelos.
+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.
     """
     model = _effective_model or GEMINI_MODEL_NAME
     if not GEMINI_API_KEY:
         return ""
-    url = f"https://generativelanguage.googleapis.com/v1/models/{model}:generateContent?key={GEMINI_API_KEY}"
+    # 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:
-        r = httpx.post(url, json=payload, timeout=25)
-        if r.status_code != 200:
-            print(f"[warn] REST v1 generateContent falhou: {r.status_code} {r.text[:200]}")
-            return ""
-        data = r.json()
-        for cand in data.get("candidates", []):
-            parts = cand.get("content", {}).get("parts", [])
+    # 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}"
+        )
+        try:
+            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:
+            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()
-    except Exception as e:
-        print(f"[warn] REST v1 generateContent exceção: {e}")
     return ""
 
 
 def generate_text_with_llm(prompt: str, max_tokens: int = 500, temperature: float = 0.7) -> str:
-    """
-    Gera texto com Gemini. Tenta SDK; se falhar, usa REST v1 como fallback.
-    Se ainda assim falhar, retorna string vazia.
+    """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.
     """
     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={
@@ -167,29 +250,37 @@ 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 para extrair texto de candidates/parts
+            # Fallback: iterate candidates/parts manually.
             parts_out: List[str] = []
             for c in getattr(resp, "candidates", []) or []:
-                for p in getattr(getattr(c, "content", {}), "parts", []) or []:
-                    if getattr(p, "text", ""):
-                        parts_out.append(p.text)
+                content = getattr(c, "content", {}) or {}
+                for p in getattr(content, "parts", []) or []:
+                    text = getattr(p, "text", "")
+                    if text:
+                        parts_out.append(text)
             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.
         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)
 
-    # fallback REST v1
-    return _rest_generate_content_v1(prompt, max_tokens, temperature)
 
+# =============================================================================
+# HTTP utilitários e página raiz
+# =============================================================================
 
-# ==========================
-# Home & utilitários HTTP
-# ==========================
 @app.get("/", response_class=HTMLResponse, include_in_schema=False)
-def home():
-    # aceita / e /?logs=container (query string não muda o match da rota)
+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">
@@ -221,18 +312,31 @@ def home():
 
 
 @app.get("/favicon.ico", include_in_schema=False)
-def favicon():
+def favicon() -> Response:
+    """Return an empty 204 response for the favicon request."""
     return Response(status_code=204)
 
 
-# (opcional) endpoint de debug da key
 @app.get("/debug/gemini")
-def 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}
+    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)
+            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:
@@ -241,7 +345,12 @@ def debug_gemini():
 
 
 @app.get("/debug/env")
-def 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 {
@@ -253,15 +362,24 @@ def debug_env():
     }
 
 
-# ==========================
-# Geocodificação (Nominatim/OSM) com cache e fallback
-# ==========================
+# =============================================================================
+# 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()
@@ -289,10 +407,11 @@ def geocode_city(query: str) -> tuple[float, float, str] | None:
         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"),
@@ -304,7 +423,8 @@ CITY_COORDS: Dict[str, tuple[float, float, str]] = {
     "porto alegre": (-30.0346, -51.2177, "Porto Alegre, RS"),
     "florianópolis": (-27.5949, -48.5482, "Florianópolis, SC"),
 }
-CITY_ALIASES = {
+
+CITY_ALIASES: Dict[str, str] = {
     "amazonia": "manaus",
     "amazônia": "manaus",
     "belem": "belém",
@@ -314,17 +434,25 @@ CITY_ALIASES = {
 
 
 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
@@ -336,7 +464,12 @@ def get_coords_and_label(raw: str) -> tuple[float, float, str]:
     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)
@@ -347,6 +480,7 @@ def haversine_km(a: Tuple[float, float], b: Tuple[float, float]) -> float:
 
 
 def daterange(d0: date, d1: date):
+    """Yield dates between two endpoints inclusive."""
     d = d0
     while d <= d1:
         yield d
@@ -354,16 +488,19 @@ def daterange(d0: date, d1: date):
 
 
 def is_weekend(d: date) -> bool:
+    """Return True if the given date is a weekend (Saturday or Sunday)."""
     return d.weekday() >= 5
 
 
-# ==========================
-# Modelos (Pydantic)
-# ==========================
+# =============================================================================
+# 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
@@ -377,11 +514,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
@@ -391,6 +530,7 @@ class Leg(BaseModel):
 
 
 class ItemCusto(BaseModel):
+    """Represents an itemised cost component."""
     categoria: str
     descricao: str
     quantidade: int
@@ -399,6 +539,7 @@ class ItemCusto(BaseModel):
 
 
 class DiaRoteiro(BaseModel):
+    """Represents one day's itinerary with activities and costs."""
     data: str
     manha: str
     tarde: str
@@ -408,6 +549,7 @@ class DiaRoteiro(BaseModel):
 
 
 class PlanResponse(BaseModel):
+    """Schema for the response returned by /plan."""
     orcamento_estimado_total: float
     legs: List[Leg]
     custos_itens: List[ItemCusto]
@@ -422,11 +564,12 @@ class PlanResponse(BaseModel):
     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},
@@ -434,7 +577,9 @@ BASES = {
     "rod_preco_km": 0.15,
 }
 
-POIS_MANAUS = [
+# 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},
@@ -449,38 +594,52 @@ POIS_MANAUS = [
     {"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 = [
+
+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 = [
+
+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 = [
+
+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 = [
+
+# 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 = {"manaus": POIS_MANAUS, "belém": POIS_BELEM, "rio de janeiro": POIS_RIO, "são paulo": POIS_SAO_PAULO}
+
+# 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]
@@ -490,10 +649,16 @@ def get_pois_for_city(raw_city: str) -> List[Dict[str, Any]]:
     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
@@ -503,18 +668,22 @@ def filter_pois(pois: List[Dict[str, Any]], tags: List[str], slot: str, indoor:
     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
-# ==========================
+# =============================================================================
+# Planning logic
+# =============================================================================
+
 def recompute_plan(
-    req: "PlanRequest",
+    req: PlanRequest,
     d0: date,
     d1: date,
     perfil: PerfilType,
@@ -523,18 +692,27 @@ def recompute_plan(
     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
@@ -559,6 +737,7 @@ def recompute_plan(
         )
     )
 
+    # 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"]
@@ -595,6 +774,8 @@ def recompute_plan(
         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
@@ -609,6 +790,8 @@ def recompute_plan(
                 )
             )
 
+        # 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(
@@ -621,8 +804,14 @@ def recompute_plan(
             )
         )
 
+        # 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)
+            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"])
@@ -637,6 +826,7 @@ def recompute_plan(
                 )
             )
 
+        # 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],
@@ -654,6 +844,7 @@ def recompute_plan(
                 )
             )
 
+        # 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],
@@ -685,7 +876,26 @@ def recompute_plan(
     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
@@ -698,9 +908,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)
@@ -710,12 +922,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)
@@ -725,6 +939,7 @@ 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(
@@ -736,16 +951,18 @@ 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
 
+    # 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
     )
     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
@@ -756,6 +973,7 @@ 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
 
+    # 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)
@@ -766,7 +984,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.",
@@ -778,22 +999,26 @@ def fit_to_budget(req: PlanRequest, d0: date, d1: date):
 
 
 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"
 
 
-# ==========================
+# =============================================================================
 # 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():
+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,
@@ -803,7 +1028,12 @@ def info():
 
 
 @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()
@@ -817,11 +1047,11 @@ def plan(req: PlanRequest):
     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)
 
@@ -829,7 +1059,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)
@@ -847,6 +1079,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}. "
@@ -857,6 +1090,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}), "
@@ -890,10 +1125,11 @@ def plan(req: PlanRequest):
 
 
 @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}}

requirements.txt

@@ -3,4 +3,4 @@ uvicorn[standard]==0.30.6
 httpx==0.27.2
 python-dateutil==2.9.0.post0
 pydantic==2.9.2
-google-generativeai==0.7.2
+google-generativeai==0.7.2