add: cache documentation

reports.py

@@ -39,6 +39,11 @@ def _gerar_pdf(html_content: str, pdf_file: Path) -> None:
 
 
 def _carregar_csv(csv_source: str | Path) -> pd.DataFrame:
+    """Load CSV into an in-memory cache (process lifetime only).
+
+    Stores parsed DataFrames keyed by file path to avoid repeated parsing.
+    Cache is lost on process restart.
+    """
     cache_key = str(csv_source)
     if cache_key in _CSV_CACHE:
         return _CSV_CACHE[cache_key].copy()

utils/docs.py

@@ -18,6 +18,11 @@ def _cache_path(doc_id: str) -> Path:
 
 
 def _carregar_do_cache(doc_id: str) -> str | None:
+    """Load document content from cache if still valid.
+
+    Checks ``output/docs_cache/{doc_id}.json`` and validates TTL (1 hour).
+    Returns None if cache miss or expired.
+    """
     cache_path = _cache_path(doc_id)
     if not cache_path.exists():
         return None
@@ -31,6 +36,10 @@ def _carregar_do_cache(doc_id: str) -> str | None:
 
 
 def _salvar_no_cache(doc_id: str, texto: str) -> None:
+    """Store document content in cache with current timestamp.
+
+    Writes to ``output/docs_cache/{doc_id}.json`` with timestamp for TTL tracking.
+    """
     try:
         DOCS_CACHE_DIR.mkdir(parents=True, exist_ok=True)
         dados = {"timestamp": time.time(), "texto": texto}

utils/maps.py

@@ -436,6 +436,11 @@ def gerar_mapa_regiao(nome_municipio: str, safe_report: str) -> str | None:
 
 
 def carregar_cache_geocoding() -> dict:
+    """Load geocoding cache from disk.
+
+    Returns cached city coordinates from ``output/geocoding_cache.json``.
+    Cache is permanent (no TTL) — persists until cache file is deleted.
+    """
     if not GEOCODING_CACHE_FILE.exists():
         return {}
 
@@ -446,6 +451,10 @@ def carregar_cache_geocoding() -> dict:
 
 
 def salvar_cache_geocoding(cache: dict) -> None:
+    """Write geocoding cache to disk.
+
+    Persists the entire cache dict to ``output/geocoding_cache.json``.
+    """
     OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
     GEOCODING_CACHE_FILE.write_text(
         json.dumps(cache, ensure_ascii=False, indent=2),