Sync from GitHub 2026-04-30 19:20:11 UTC

.gitignore

@@ -0,0 +1,26 @@
+# Ambiente Python
+venv/
+.env
+*.pyc
+__pycache__/
+
+
+# Configurações e credenciais sensíveis
+config/*.json
+!configs/config.json
+
+
+# Ignorar archivos del índice generado
+data/index/
+data/embeddings/
+data/chunks/
+
+/Docs/
+/Docs/**
+
+# Arquivos temporários / editor
+*.log
+*.tmp
+.DS_Store
+.vscode/
+.idea/

Dockerfile

@@ -0,0 +1,58 @@
+# ── Stage 1: Build Vue frontend ──────────────────────────────────────────────
+FROM node:20-alpine AS frontend-build
+WORKDIR /frontend
+RUN apk add --no-cache git
+RUN git clone https://github.com/ICA-PUC/chatbot-norm-frontend.git .
+RUN npm ci && npm run build
+
+# ── Stage 2: Python backend ───────────────────────────────────────────────────
+FROM python:3.11-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+
+WORKDIR /app
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r requirements.txt && \
+    pip install --no-cache-dir huggingface_hub
+
+COPY . .
+
+# Descargar el índice FAISS desde HF Dataset
+# El token HF_TOKEN se inyecta como build-arg para repos privados.
+# Si el dataset es público, omitir --build-arg HF_TOKEN.
+ARG HF_TOKEN
+RUN mkdir -p data/index/intfloat/multilingual-e5-large && \
+    python - <<'EOF'
+import os
+from huggingface_hub import hf_hub_download
+
+token = os.getenv("HF_TOKEN") or None
+repo = "ICA-PUC/norm-index"
+dest = "data/index/intfloat/multilingual-e5-large"
+
+for filename in ["faiss.index", "metadata.jsonl"]:
+    path = hf_hub_download(
+        repo_id=repo,
+        filename=filename,
+        repo_type="dataset",
+        token=token,
+        local_dir=dest,
+    )
+    print(f"Downloaded: {path}")
+EOF
+
+# Copiar el build del frontend
+COPY --from=frontend-build /frontend/dist /app/static
+
+# Puerto requerido por Hugging Face Spaces
+ENV PORT=7860
+EXPOSE 7860
+
+CMD uvicorn app.main:app --host 0.0.0.0 --port ${PORT}

README.md

@@ -0,0 +1,323 @@
+---
+title: beta-NORM
+emoji: 🧪
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+# NORM Chatbot – Backend (RAG API)
+
+A **Retrieval-Augmented Generation (RAG)** system specialized in
+technical documents about **Naturally Occurring Radioactive Materials
+(NORM)** and related chemistry (barium, ²²⁶Ra/²²⁸Ra, marine sediments,
+etc.). This repository contains **only the backend**; the Vue 3 frontend
+lives in [`chatbot-norm-frontend`](https://github.com/ICA-PUC/chatbot-norm-frontend).
+
+Users ask questions in natural language and the system answers in
+Portuguese, always citing the passages used with numbered references
+in `[n]` format.
+
+---
+
+## Table of contents
+
+- [Architecture](#architecture)
+- [Stack](#stack)
+- [Setup](#setup)
+- [Data pipeline](#data-pipeline)
+- [Run the API](#run-the-api)
+- [Endpoints](#endpoints)
+- [Configuration (`configs/config.json`)](#configuration-configsconfigjson)
+- [Repository layout](#repository-layout)
+- [Frontend](#frontend)
+
+---
+
+## Architecture
+
+1. **Corpus**: `.md` files with YAML frontmatter (`title`, `authors`,
+   `publication_year`, `topic`…) stored in `Docs/`.
+2. **Indexing**: token-based chunking → E5 embeddings → FAISS
+   (`IndexFlatIP`, cosine) locally, or optional vector Elasticsearch.
+3. **RAG API (FastAPI)**: retrieves the `top_k` chunks, builds the
+   prompt with numbered references and calls the LLM (OpenAI).
+4. **Frontend**: a Vue 3 SPA (separate repo) that consumes this API.
+
+### Selective index sampling
+
+`build_faiss_from_md` supports:
+
+- `require_frontmatter`: skips documents without valid YAML frontmatter.
+- `priority_keywords` + `priority_max`: guarantees that key topics
+  (barium, NORM, ²²⁶/²²⁸Ra, marine sediment, TENORM) always make it
+  into the sample, and reserves a quota for random variety.
+- `shuffle_sample` + `random_seed`: reproducible random sampling for
+  the rest.
+
+### Embedding model
+
+Default: `intfloat/multilingual-e5-large`. This model requires
+prefixes:
+
+- chunks → `passage: {text}`
+- queries → `query: {question}`
+
+Both prefixes are applied automatically by the `_model_needs_e5_prefix`
+helper. **If you change the embedding model you must reindex.**
+
+---
+
+## Stack
+
+- Python ≥ 3.9
+- FastAPI + uvicorn
+- sentence-transformers (multilingual E5)
+- FAISS (local) / Elasticsearch (optional)
+- LangChain text-splitters + tiktoken
+- OpenAI (`gpt-4o-mini` by default)
+
+See `requirements.txt` for pinned versions.
+
+---
+
+## Setup
+
+```bash
+# 1. Clone and create a virtual environment
+git clone https://github.com/ICA-PUC/chatbot-Norm.git
+cd chatbot-Norm
+python3 -m venv venv
+source venv/bin/activate
+
+# 2. Install dependencies
+pip install --upgrade pip
+pip install -r requirements.txt
+
+# 3. OpenAI key
+export OPENAI_API_KEY="sk-..."
+```
+
+---
+
+## Data pipeline
+
+Run all commands from the repository root with the virtual environment
+activated.
+
+### 1. (Optional) Normalize `.md` titles
+
+```bash
+python -m scripts.normalize_md_titles
+```
+
+Ensures every file under `Docs/` has a clean `# heading`. Useful only
+if the corpus comes from heterogeneous sources without frontmatter.
+
+### 2. Build the FAISS index
+
+The consolidated script reads the config and generates embeddings +
+index in a single step:
+
+```bash
+python -m scripts.embd_index
+```
+
+It uses the parameters in the `embeddings` block of
+`configs/config.json`:
+
+- `max_files_for_debug`: total number of documents to index (e.g. 900).
+- `shuffle_sample` + `random_seed`: reproducible randomization.
+- `require_frontmatter`: filters out documents without metadata.
+- `priority_keywords` + `priority_max`: guaranteed quota for key
+  topics.
+
+Outputs:
+
+```
+data/index/<model_name>/faiss.index
+data/index/<model_name>/metadata.jsonl
+data/index/<model_name>/index_info.json
+```
+
+### 2b. (Legacy alternative) Generate embeddings and build the index separately
+
+```bash
+python -m scripts.generate_embeddings
+python -m scripts.build_index
+```
+
+Generates `data/embeddings/embeddings.npy` + `metadata.jsonl` and then
+builds the flat FAISS index.
+
+### 3. (Optional) Index in Elasticsearch
+
+```bash
+export ELASTIC_API_KEY="..."
+python -m scripts.index_to_elasticsearch
+```
+
+Then change `index.type` to `"elasticsearch"` in
+`configs/config.json`.
+
+### 4. (Dev) CLI smoke test
+
+```bash
+python -m scripts.test_retrieval_cli "what is the 226Ra activity in marine sediments?"
+```
+
+---
+
+## Run the API
+
+```bash
+export OPENAI_API_KEY="sk-..."
+uvicorn app.main:app --reload --port 8000
+```
+
+The API is served at `http://127.0.0.1:8000`. Interactive docs at
+`http://127.0.0.1:8000/docs`.
+
+### CORS
+
+Allowed origins are configured via the `ALLOWED_ORIGINS` environment
+variable (comma-separated). By default `localhost`/`127.0.0.1` on any
+port are accepted for development.
+
+### Docker
+
+```bash
+docker build -t chatbot-norm .
+docker run -p 8000:8000 -e OPENAI_API_KEY=sk-... chatbot-norm
+```
+
+---
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET`  | `/health` | Health check. |
+| `GET`  | `/list_documents` | Lists all indexed documents (`id`, `title`). |
+| `POST` | `/query` | RAG question; returns the answer and the chunks used. |
+| `POST` | `/precheck_document` | Checks if a file is thematically aligned before indexing. |
+| `POST` | `/upload_document` | Indexes a new file (`.md`, `.txt`, `.pdf`, `.docx`). |
+| `POST` | `/generate_presentation` | Builds a `.pptx` from a list of ideas. |
+
+### `POST /query`
+
+```json
+{
+  "question": "Qual a concentração de 226Ra em sedimentos marinhos?",
+  "mode": "chatbot",
+  "top_k": 12,
+  "temperature": 0.1
+}
+```
+
+Available modes: `chatbot`, `summary`, `summary_multi`,
+`summary_sections`, `summary_sections_multi`, `table`, `table_multi`.
+
+Response:
+
+```json
+{
+  "answer": "A concentração de 226Ra em sedimentos marinhos varia [1][2]…",
+  "retrieved": [
+    {
+      "document_id": "226Ra_...",
+      "document_title": "...",
+      "fragment_id": "...",
+      "content": "...",
+      "citation_id": 1
+    }
+  ]
+}
+```
+
+### `POST /upload_document`
+
+`multipart/form-data` with `file`. Max 10 MB. Only available when
+`index.type = "faiss"`. Performs hot reindexing without restarting the
+server.
+
+---
+
+## Configuration (`configs/config.json`)
+
+Main blocks:
+
+- **`embeddings`**: model, quotas, priority keywords.
+- **`splitter`**: chunking type (`tokens`), `chunk_size`, `overlap`.
+  For E5-large, `chunk_size ≤ 450` is recommended (the model caps at
+  512 tokens).
+- **`retrieve`**: `top_k` (default) and `chatbot_top_k`.
+- **`paths`**: input/output paths.
+- **`index`**: `faiss` or `elasticsearch`.
+- **`llm`**: provider, model and `system_prompt`.
+- **`ui.api_url`**: used by the frontend.
+
+`configs/prompts.json` holds the per-mode prompts, trigger word lists
+(greetings/smalltalk) and fallback messages.
+
+---
+
+## Repository layout
+
+```
+app/
+├── main.py                # FastAPI entry point (uvicorn app.main:app)
+├── core/
+│   └── state.py           # Global state + embed_query / embed_chunks helpers
+├── models/
+│   ├── requests.py        # Pydantic: QueryRequest, PresentationRequest…
+│   └── responses.py       # Pydantic: QueryResponse, PrecheckResponse…
+├── routers/
+│   ├── query.py           # POST /query
+│   ├── documents.py       # /list_documents, /precheck_document, /upload_document
+│   └── presentations.py   # POST /generate_presentation
+└── services/
+    ├── rag.py             # Orchestration of a RAG query
+    ├── indexing.py        # Precheck + upload + hot reindexing
+    ├── helpers.py         # Text utilities, topic catalog, parsing
+    └── llm.py             # LLM calls + PPTX generation
+
+utils/
+├── base_utils.py          # Config/prompts loader, I/O helpers
+├── retrieval_utils.py     # Embedding batches + splitter + E5 prefixes
+├── retrievers.py          # FaissRetriever + ElasticRetriever
+├── md_to_faiss.py         # Incremental indexing with priority_keywords
+└── pdf_md.py              # .pdf / .docx → Markdown conversion
+
+scripts/
+├── embd_index.py              # Consolidated pipeline (recommended)
+├── generate_embeddings.py     # Legacy: embeddings only
+├── build_index.py             # Legacy: build FAISS from .npy
+├── index_to_elasticsearch.py  # Push to Elastic Cloud
+├── normalize_md_titles.py
+└── test_retrieval_cli.py
+
+configs/
+├── config.json            # Single source of parameters
+└── prompts.json           # Per-mode prompts + triggers
+
+Docs/                      # .md corpus with YAML frontmatter
+data/
+├── embeddings/            # embeddings.npy + metadata.jsonl (legacy)
+└── index/<model>/         # faiss.index + metadata.jsonl + index_info.json
+```
+
+---
+
+## Frontend
+
+The Vue 3 + Vite client lives in the sibling repository:
+
+- Repo: <https://github.com/ICA-PUC/chatbot-norm-frontend>
+- Dev: `npm run dev` → `http://localhost:5173`
+- Configurable via `VITE_API_URL` (default `http://localhost:8000`).
+
+---
+
+**Authors:** Breinner Espinosa, Andrés Cotrino.

app/core/state.py

@@ -0,0 +1,97 @@
+"""
+Estado global de la aplicación: configuración, retriever,
+modelo de embeddings y metadata.  Todos los módulos que
+necesiten acceder o mutar el estado deben importar este módulo
+como `import app.core.state as state` y acceder a sus atributos.
+"""
+
+from threading import Lock
+from typing import Any, Dict, List
+
+import faiss
+import numpy as np
+
+from utils import base_utils as bu
+from utils import retrieval_utils as ru
+from utils.retrievers import get_retriever
+
+
+# ---------------------------------------------------------------------------
+# Funciones de inicialización (no dependen de estado global)
+# ---------------------------------------------------------------------------
+
+def load_embedding_model(config: dict):
+    model_name = config["embeddings"]["model_name"]
+    return ru.load_model(model_name)
+
+
+def _needs_e5_prefix() -> bool:
+    """Los modelos intfloat/e5-* requieren los prefijos `query:` / `passage:`."""
+    name = str(CONFIG.get("embeddings", {}).get("model_name", "")).lower()
+    return "e5" in name
+
+
+def embed_query(model, text: str, normalize: bool = True) -> np.ndarray:
+    if _needs_e5_prefix() and not text.lstrip().lower().startswith("query:"):
+        text = f"query: {text}"
+    vec = model.encode(text)
+    vec = np.asarray(vec, dtype="float32")[None, :]
+    if normalize:
+        faiss.normalize_L2(vec)
+    return vec
+
+
+# ---------------------------------------------------------------------------
+# Estado global (inicializado al importar el módulo, igual que antes)
+# ---------------------------------------------------------------------------
+
+CONFIG: Dict[str, Any] = bu.load_config("configs/config.json")
+RETRIEVER = get_retriever(CONFIG)
+EMBED_MODEL = load_embedding_model(CONFIG)
+PROMPTS: Dict[str, Any] = bu.load_prompts()
+
+META_PROMPTS: Dict[str, Any] = (
+    PROMPTS.get("meta", {}) if isinstance(PROMPTS, dict) else {}
+)
+TRIGGERS: Dict[str, Any] = (
+    META_PROMPTS.get("triggers", {}) if isinstance(META_PROMPTS, dict) else {}
+)
+
+NO_INFO_PREFIX: str = META_PROMPTS.get(
+    "no_information_prefix",
+    "Não há informações suficientes na base.",
+)
+ABOUT_BOT_TEXT: str = META_PROMPTS.get(
+    "about_bot",
+    (
+        "Sou o Chatbot NORM, um assistente especializado em química e materiais "
+        "radioativos de ocorrência natural (NORM). Respondo com base nos documentos "
+        "técnicos indexados na base de conhecimento deste sistema."
+    ),
+)
+GREETING_TEXT: str = META_PROMPTS.get(
+    "greeting",
+    (
+        "Olá! Sou o Chatbot NORM, um assistente treinado para responder perguntas "
+        "sobre química e NORM usando os documentos técnicos indexados. Você pode, "
+        "por exemplo, pedir um resumo de um documento específico ou perguntar sobre "
+        "um isótopo radioativo."
+    ),
+)
+HELP_SCOPE_TEXT: str = META_PROMPTS.get(
+    "help_scope",
+    (
+        "Posso ajudar respondendo perguntas sobre química, radioatividade natural "
+        "(NORM), isótopos específicos e documentos técnicos indexados neste sistema. "
+        "Faça perguntas objetivas e, se possível, mencione o tema ou documento de "
+        "interesse para eu recuperar os trechos mais relevantes."
+    ),
+)
+
+METADATA: List[Dict[str, Any]] = getattr(RETRIEVER, "metadata", [])
+
+# Lista de documentos mostrados na última listagem (persistida por sessão do servidor)
+LAST_LISTED_DOCS: List[Dict[str, Any]] = []
+
+# Lock para evitar condições de corrida ao reindexar documentos
+INDEX_UPDATE_LOCK = Lock()

app/main.py

@@ -0,0 +1,58 @@
+"""
+Punto de entrada de la API.  Ejecutar con:
+  uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+"""
+
+import os
+import pathlib
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+
+from app.routers import documents, presentations, query
+
+app = FastAPI(
+    title="chatbot-Norm API",
+    version="0.2.0",
+    description="RAG API para consultas sobre NORM y química.",
+)
+
+# ---------------------------------------------------------------------------
+# CORS — ajustar ALLOWED_ORIGINS en producción vía variable de entorno
+# ---------------------------------------------------------------------------
+_raw_origins = os.getenv(
+    "ALLOWED_ORIGINS",
+    "http://localhost:3000,http://localhost:5173,"
+    "http://127.0.0.1:3000,http://127.0.0.1:5173",
+)
+allowed_origins = [o.strip() for o in _raw_origins.split(",") if o.strip()]
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=allowed_origins,
+    allow_origin_regex=r"https?://(localhost|127\.0\.0\.1)(:\d+)?",
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# ---------------------------------------------------------------------------
+# Routers
+# ---------------------------------------------------------------------------
+app.include_router(query.router)
+app.include_router(documents.router)
+app.include_router(presentations.router)
+
+
+@app.get("/health")
+async def health_check():
+    return {"status": "ok"}
+
+
+# ---------------------------------------------------------------------------
+# SPA — debe ir al final para no solapar las rutas de la API
+# ---------------------------------------------------------------------------
+_static_dir = pathlib.Path(__file__).parent / "static"
+if _static_dir.exists():
+    app.mount("/", StaticFiles(directory=_static_dir, html=True), name="spa")

app/models/requests.py

@@ -0,0 +1,18 @@
+from typing import List
+
+from pydantic import BaseModel
+
+
+class QueryRequest(BaseModel):
+    question: str
+    mode: str
+    top_k: int | None = None
+    temperature: float | None = None
+
+
+class PresentationRequest(BaseModel):
+    ideas: List[str]
+    title: str | None = None
+    audience: str | None = None
+    language: str | None = None
+    num_slides: int | None = None

app/models/responses.py

@@ -0,0 +1,22 @@
+from typing import Any, Dict, List
+
+from pydantic import BaseModel
+
+
+class QueryResponse(BaseModel):
+    answer: str
+    retrieved: List[Dict[str, Any]]
+
+
+class UploadResponse(BaseModel):
+    ok: bool
+    message: str
+    filename: str
+    document_id: str
+
+
+class PrecheckResponse(BaseModel):
+    score: float
+    recommendation: str
+    rationale: str
+    matched_topics: List[str]

app/routers/documents.py

@@ -0,0 +1,57 @@
+from pathlib import Path
+from typing import Any, Dict
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+
+import app.core.state as state
+from app.models.responses import PrecheckResponse, UploadResponse
+from app.services.helpers import (
+    get_topics_catalog_from_metadata,
+    list_documents_from_metadata,
+    resolve_topic_from_question,
+    safe_basename,
+    contains_any_trigger,
+    content_from_upload,
+)
+from app.services.indexing import precheck_content, upload_and_index
+
+router = APIRouter()
+
+
+@router.post("/precheck_document", response_model=PrecheckResponse)
+async def precheck_document(file: UploadFile = File(...)) -> PrecheckResponse:
+    """Evalúa si un archivo parece alineado al scope antes de indexar."""
+    safe_name = safe_basename(file.filename or "")
+    if not safe_name:
+        raise HTTPException(status_code=400, detail="Nome de arquivo inválido.")
+
+    ext = Path(safe_name).suffix.lower()
+    if ext not in {".md", ".txt", ".pdf", ".docx"}:
+        raise HTTPException(
+            status_code=400,
+            detail="Formato não suportado. Use .md, .txt, .pdf ou .docx.",
+        )
+
+    file_bytes = await file.read()
+    if not file_bytes:
+        raise HTTPException(status_code=400, detail="Arquivo vazio.")
+
+    content = content_from_upload(file_bytes, ext)
+    return precheck_content(safe_name, content)
+
+
+@router.post("/upload_document", response_model=UploadResponse)
+async def upload_document(file: UploadFile = File(...)) -> UploadResponse:
+    """Recibe un archivo, lo indexa en FAISS y recarga el retriever en memoria."""
+    file_bytes = await file.read()
+    return upload_and_index(file_bytes, file.filename or "")
+
+
+@router.get("/list_documents")
+async def list_documents() -> Dict[str, Any]:
+    """Retorna la lista de documentos presentes en la metadata, incluyendo topic."""
+    # Siempre usamos la metadata local para exponer también el campo `topic`,
+    # que el método del retriever puede no incluir.
+    documentos_ordenados = list_documents_from_metadata()
+    state.LAST_LISTED_DOCS = documentos_ordenados
+    return {"documents": documentos_ordenados}

app/routers/presentations.py

@@ -0,0 +1,38 @@
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+
+from app.models.requests import PresentationRequest
+from app.services.helpers import safe_basename
+from app.services.llm import build_pptx_from_structure, call_llm_for_slides
+
+router = APIRouter()
+
+
+@router.post("/generate_presentation")
+async def generate_presentation(payload: PresentationRequest):
+    """Genera un archivo PPTX a partir de una lista de ideas."""
+    if not payload.ideas:
+        raise HTTPException(status_code=400, detail="Lista de ideias vazia.")
+
+    try:
+        structure = call_llm_for_slides(
+            ideas=payload.ideas,
+            title=payload.title,
+            audience=payload.audience,
+            language=payload.language,
+            num_slides=payload.num_slides,
+        )
+        pptx_path = build_pptx_from_structure(structure)
+    except RuntimeError as exc:
+        raise HTTPException(status_code=500, detail=str(exc)) from exc
+
+    filename = structure.get("title") or "apresentacao_chatbot_norm"
+    safe_name = safe_basename(str(filename)) or "apresentacao_chatbot_norm"
+    if not safe_name.lower().endswith(".pptx"):
+        safe_name += ".pptx"
+
+    return FileResponse(
+        pptx_path,
+        media_type="application/vnd.openxmlformats-officedocument.presentationml.presentation",
+        filename=safe_name,
+    )

app/routers/query.py

@@ -0,0 +1,12 @@
+from fastapi import APIRouter
+
+from app.models.requests import QueryRequest
+from app.models.responses import QueryResponse
+from app.services.rag import process_query
+
+router = APIRouter()
+
+
+@router.post("/query", response_model=QueryResponse)
+async def query_endpoint(payload: QueryRequest) -> QueryResponse:
+    return process_query(payload)

app/services/helpers.py

@@ -0,0 +1,463 @@
+"""
+Funciones auxiliares puras y semi-puras usadas por los servicios RAG e indexación.
+Las funciones que acceden al estado global importan `app.core.state` como módulo
+para evitar capturas de valores obsoletos.
+"""
+
+import os
+import re
+import tempfile
+import unicodedata
+from pathlib import Path
+from typing import Any, Dict, List, Set
+
+from fastapi import HTTPException
+
+import app.core.state as state
+from utils.pdf_md import convert_document_to_markdown
+
+
+# ---------------------------------------------------------------------------
+# Normalización de texto
+# ---------------------------------------------------------------------------
+
+def normalizar_texto(texto: str) -> str:
+    """Limpia saltos de línea y espacios raros en los fragmentos."""
+    if not texto:
+        return ""
+    texto = texto.replace("\r", " ").replace("\n", " ")
+    texto = re.sub(r"\s+", " ", texto)
+    return texto.strip()
+
+
+def normalize_match_text(text: str) -> str:
+    if not text:
+        return ""
+    value = unicodedata.normalize("NFKD", str(text))
+    value = "".join(ch for ch in value if not unicodedata.combining(ch))
+    value = value.lower().strip()
+    value = re.sub(r"[^\w\s]", " ", value)
+    value = re.sub(r"\s+", " ", value)
+    return value
+
+
+# ---------------------------------------------------------------------------
+# Extracción de títulos y secciones desde la pregunta
+# ---------------------------------------------------------------------------
+
+def extract_quoted_titles(question: str) -> List[str]:
+    if not question:
+        return []
+    matches = re.findall(r'["""]([^"""]{5,})["""]', question)
+    cleaned = [m.strip() for m in matches if m and m.strip()]
+    return list(dict.fromkeys(cleaned))
+
+
+def detect_target_sections(question_lower: str) -> List[str]:
+    """Detecta una o más secciones objetivo para resumen por sección."""
+    section_aliases: Dict[str, List[str]] = {
+        "Introdução": ["introdução", "introducao", "introduccion", "introduction"],
+        "Metodologia": ["metodologia", "metodología", "methodology"],
+        "Resultados": ["resultados", "results"],
+    }
+    found: List[tuple] = []
+    for section_name, aliases in section_aliases.items():
+        positions = [
+            question_lower.find(alias)
+            for alias in aliases
+            if alias in question_lower
+        ]
+        if positions:
+            found.append((min(positions), section_name))
+    found.sort(key=lambda item: item[0])
+    return [section_name for _, section_name in found]
+
+
+# ---------------------------------------------------------------------------
+# Triggers
+# ---------------------------------------------------------------------------
+
+def contains_trigger(text: str, trigger: str) -> bool:
+    """Verifica trigger como palabra/frase completa (evita falsos positivos)."""
+    if not text or not trigger:
+        return False
+    trigger_clean = trigger.strip().lower()
+    if not trigger_clean:
+        return False
+    pattern = re.escape(trigger_clean).replace(r"\ ", r"\s+")
+    return re.search(rf"(?<!\w){pattern}(?!\w)", text.lower()) is not None
+
+
+def contains_any_trigger(text: str, triggers: List[str]) -> bool:
+    return any(contains_trigger(text, trigger) for trigger in triggers)
+
+
+# ---------------------------------------------------------------------------
+# Catálogos de documentos y tópicos (acceden al estado global)
+# ---------------------------------------------------------------------------
+
+def get_documents_catalog() -> List[Dict[str, str]]:
+    """Obtiene catálogo (id + title) desde el retriever o la metadata."""
+    if hasattr(state.RETRIEVER, "list_documents"):
+        docs = state.RETRIEVER.list_documents()
+        return [
+            {
+                "id": str(d.get("id", "")),
+                "title": str(d.get("title") or d.get("id") or ""),
+            }
+            for d in docs
+            if d.get("id")
+        ]
+
+    docs_map: Dict[str, str] = {}
+    for m in state.METADATA:
+        doc_id = m.get("document_id")
+        if not doc_id:
+            continue
+        title = m.get("document_title") or doc_id
+        if doc_id not in docs_map:
+            docs_map[str(doc_id)] = str(title)
+    return [{"id": doc_id, "title": title} for doc_id, title in docs_map.items()]
+
+
+def get_topics_catalog_from_metadata() -> List[str]:
+    """Lista de tópicos distintos existentes en la metadata."""
+    seen: Dict[str, str] = {}
+    for m in state.METADATA:
+        raw_topic = m.get("topic")
+        if not raw_topic:
+            continue
+        topic = str(raw_topic).strip()
+        if not topic:
+            continue
+        norm = normalize_match_text(topic)
+        if norm and norm not in seen:
+            seen[norm] = topic
+    return sorted(seen.values(), key=lambda t: t.lower())
+
+
+# ---------------------------------------------------------------------------
+# Resolución de tópicos y documentos
+# ---------------------------------------------------------------------------
+
+def topic_match_score(doc_topic: str, target_topic: str) -> int:
+    doc_norm = normalize_match_text(doc_topic)
+    target_norm = normalize_match_text(target_topic)
+    if not doc_norm or not target_norm:
+        return 0
+    if doc_norm == target_norm:
+        return 3
+    if target_norm in doc_norm:
+        return 2
+    if doc_norm in target_norm and len(doc_norm) >= 8:
+        return 1
+    return 0
+
+
+def resolve_topic_from_question(question: str, topics_catalog: List[str]) -> str | None:
+    if not question:
+        return None
+    quoted = re.findall(
+        r'(?:topic|topico|tópico|tema)\s*(?::|=|eh|é|is|del|de|do|da)?\s*["""]([^"""]{3,})["""]',
+        question,
+        flags=re.IGNORECASE,
+    )
+    if quoted:
+        return quoted[0].strip()
+
+    question_norm = normalize_match_text(question)
+    if not question_norm:
+        return None
+
+    matched = [
+        topic for topic in topics_catalog
+        if normalize_match_text(topic) in question_norm
+    ]
+    if len(matched) == 1:
+        return matched[0]
+
+    free_text = re.findall(
+        r'(?:topic|topico|tópico|tema)\s*(?::|=|eh|é|is|del|de|do|da)?\s*([^,.!?\n]{3,})',
+        question,
+        flags=re.IGNORECASE,
+    )
+    if free_text:
+        candidate = free_text[0].strip()
+        return candidate if candidate else None
+    return None
+
+
+def list_documents_from_metadata(topic: str | None = None) -> List[Dict[str, str]]:
+    """Lista documentos desde la metadata, opcionalmente filtrados por tópico."""
+    resolved_topic = (topic or "").strip()
+    docs_map: Dict[str, Dict[str, str]] = {}
+    for m in state.METADATA:
+        doc_id_raw = m.get("document_id")
+        if not doc_id_raw:
+            continue
+        doc_id = str(doc_id_raw)
+        title = str(m.get("document_title") or doc_id)
+        doc_topic = str(m.get("topic") or "").strip()
+        if resolved_topic and topic_match_score(doc_topic, resolved_topic) == 0:
+            continue
+        if doc_id not in docs_map:
+            docs_map[doc_id] = {"id": doc_id, "title": title, "topic": doc_topic}
+    return sorted(docs_map.values(), key=lambda d: d["title"].lower())
+
+
+def resolve_doc_ids_from_titles(
+    titles: List[str], catalog: List[Dict[str, str]]
+) -> Set[str]:
+    resolved: Set[str] = set()
+    if not titles or not catalog:
+        return resolved
+
+    normalized_catalog = [
+        {
+            "id": str(doc.get("id", "")),
+            "title": str(doc.get("title", "")),
+            "id_norm": normalize_match_text(doc.get("id", "")),
+            "norm": normalize_match_text(doc.get("title", "")),
+        }
+        for doc in catalog
+        if doc.get("id")
+    ]
+
+    for raw_title in titles:
+        target_norm = normalize_match_text(raw_title)
+        if not target_norm:
+            continue
+
+        exact = [
+            doc for doc in normalized_catalog
+            if doc["norm"] == target_norm or doc["id_norm"] == target_norm
+        ]
+        if len(exact) == 1:
+            resolved.add(exact[0]["id"])
+            continue
+
+        contains = [
+            doc for doc in normalized_catalog
+            if (
+                target_norm in doc["norm"]
+                or (doc["norm"] in target_norm and len(doc["norm"]) >= 20)
+                or target_norm in doc["id_norm"]
+                or (doc["id_norm"] in target_norm and len(doc["id_norm"]) >= 8)
+            )
+        ]
+        if len(contains) == 1:
+            resolved.add(contains[0]["id"])
+    return resolved
+
+
+def extract_explicit_target_doc_ids(
+    question: str, catalog: List[Dict[str, str]]
+) -> Set[str]:
+    if not question:
+        return set()
+
+    explicit_titles: List[str] = []
+
+    # Forma singular: `documento alvo principal "X"`
+    explicit_titles.extend(
+        m.strip()
+        for m in re.findall(
+            r'documento\s+alvo\s+principal\s+["“”]([^"“”]+)["“”]',
+            question,
+            flags=re.IGNORECASE,
+        )
+        if m and m.strip()
+    )
+
+    # Forma plural: `documentos alvo ... "A", "B", "C"` (encabezado opcional)
+    plural_match = re.search(
+        r'documentos\s+alvo[^:"“”]*[:]?\s*((?:["“”][^"“”]+["“”][\s,;e]*)+)',
+        question,
+        flags=re.IGNORECASE,
+    )
+    if plural_match:
+        explicit_titles.extend(
+            m.strip()
+            for m in re.findall(r'["“”]([^"“”]+)["“”]', plural_match.group(1))
+            if m and m.strip()
+        )
+
+    return resolve_doc_ids_from_titles(explicit_titles, catalog) if explicit_titles else set()
+
+
+# ---------------------------------------------------------------------------
+# Suplemento y colección de chunks
+# ---------------------------------------------------------------------------
+
+def supplement_retrieval_for_target_docs(
+    retrieved: List[Dict[str, Any]],
+    target_doc_ids: Set[str],
+    metadata: List[Dict[str, Any]],
+    chunks_per_doc: int = 2,
+) -> List[Dict[str, Any]]:
+    if not target_doc_ids:
+        return retrieved
+
+    def _key(item: Dict[str, Any]) -> str:
+        idx = item.get("idx")
+        if idx is not None:
+            return f"idx:{idx}"
+        doc_id = str(item.get("document_id", ""))
+        fragment_id = item.get("fragment_id")
+        if fragment_id is not None:
+            return f"doc:{doc_id}|frag:{fragment_id}"
+        return f"doc:{doc_id}|content:{str(item.get('content', ''))[:120]}"
+
+    dedup: Dict[str, Dict[str, Any]] = {_key(item): item for item in retrieved}
+
+    if not metadata:
+        return list(dedup.values())
+
+    counts: Dict[str, int] = {doc_id: 0 for doc_id in target_doc_ids}
+    for item in dedup.values():
+        doc_id = str(item.get("document_id", ""))
+        if doc_id in counts:
+            counts[doc_id] += 1
+
+    for doc_id in target_doc_ids:
+        needed = max(0, chunks_per_doc - counts.get(doc_id, 0))
+        if needed == 0:
+            continue
+        chunks = [m for m in metadata if str(m.get("document_id", "")) == doc_id]
+        chunks = sorted(
+            chunks,
+            key=lambda m: (
+                m.get("fragment_id") is None,
+                m.get("fragment_id") or 0,
+                m.get("idx") or 0,
+            ),
+        )
+        for chunk in chunks:
+            key = _key(chunk)
+            if key in dedup:
+                continue
+            dedup[key] = dict(chunk)
+            needed -= 1
+            if needed == 0:
+                break
+
+    return list(dedup.values())
+
+
+def collect_metadata_chunks_for_docs(
+    metadata: List[Dict[str, Any]],
+    target_doc_ids: Set[str],
+    max_chunks_per_doc: int | None = None,
+) -> List[Dict[str, Any]]:
+    if not metadata or not target_doc_ids:
+        return []
+    collected: List[Dict[str, Any]] = []
+    for doc_id in target_doc_ids:
+        chunks = [m for m in metadata if str(m.get("document_id", "")) == doc_id]
+        chunks = sorted(
+            chunks,
+            key=lambda m: (
+                m.get("fragment_id") is None,
+                m.get("fragment_id") or 0,
+                m.get("idx") or 0,
+            ),
+        )
+        if max_chunks_per_doc is not None:
+            chunks = chunks[:max_chunks_per_doc]
+        collected.extend(dict(chunk) for chunk in chunks)
+    return collected
+
+
+# ---------------------------------------------------------------------------
+# Respuesta de fallback
+# ---------------------------------------------------------------------------
+
+def build_chatbot_fallback_answer(
+    retrieved: List[Dict[str, Any]], max_points: int = 3
+) -> str:
+    if not retrieved:
+        return state.NO_INFO_PREFIX
+
+    points: List[str] = []
+    seen_keys: Set[str] = set()
+
+    for item in retrieved:
+        text = normalizar_texto(item.get("content", ""))
+        if len(text) < 40:
+            continue
+        doc_id = str(item.get("document_id", ""))
+        frag = str(item.get("fragment_id") or item.get("idx") or "")
+        key = f"{doc_id}:{frag}:{text[:80]}"
+        if key in seen_keys:
+            continue
+        seen_keys.add(key)
+        excerpt = text[:260] + ("..." if len(text) > 260 else "")
+        cit_id = item.get("citation_id")
+        citation = f" [{cit_id}]" if cit_id else ""
+        points.append(f"- {excerpt}{citation}")
+        if len(points) >= max_points:
+            break
+
+    if not points:
+        return state.NO_INFO_PREFIX
+
+    return (
+        "Com base nos trechos recuperados, há informações relacionadas ao tema:\n"
+        + "\n".join(points)
+        + "\n\nSe quiser, posso aprofundar em um tópico específico "
+        "(por exemplo, isótopos, matriz ambiental ou metodologia)."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Utilidades de archivos / upload
+# ---------------------------------------------------------------------------
+
+def resolve_docs_dir_from_config(config: Dict[str, Any]) -> str:
+    input_path = str(config.get("paths", {}).get("input_path", "Docs/*.md"))
+    if "*" in input_path:
+        return os.path.dirname(input_path) or "Docs"
+    return input_path if os.path.isdir(input_path) else os.path.dirname(input_path) or "Docs"
+
+
+def safe_basename(filename: str) -> str:
+    clean = os.path.basename(filename or "").strip().replace("\\", "")
+    clean = re.sub(r"\s+", "_", clean)
+    clean = re.sub(r"[^A-Za-z0-9._-]", "", clean)
+    return clean
+
+
+def content_from_upload(file_bytes: bytes, ext: str) -> str:
+    """Convierte el contenido enviado a markdown/texto utilizable."""
+    ext = (ext or "").lower()
+
+    if ext in {".md", ".txt"}:
+        for encoding in ("utf-8", "latin-1"):
+            try:
+                return file_bytes.decode(encoding)
+            except UnicodeDecodeError:
+                continue
+        raise HTTPException(
+            status_code=400,
+            detail="Não foi possível decodificar o arquivo de texto enviado.",
+        )
+
+    if ext in {".pdf", ".docx"}:
+        with tempfile.NamedTemporaryFile(delete=False, suffix=ext) as tmp_file:
+            tmp_file.write(file_bytes)
+            tmp_path = tmp_file.name
+        try:
+            return convert_document_to_markdown(tmp_path, return_text=True) or ""
+        except Exception as exc:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Não foi possível converter o arquivo enviado: {exc}",
+            ) from exc
+        finally:
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+
+    raise HTTPException(
+        status_code=400,
+        detail="Formato não suportado. Use .md, .txt, .pdf ou .docx.",
+    )

app/services/indexing.py

@@ -0,0 +1,154 @@
+"""
+Lógica de indexación dinámica de documentos y validación previa (precheck).
+"""
+
+import os
+from pathlib import Path
+
+from fastapi import HTTPException
+
+import app.core.state as state
+from app.models.responses import PrecheckResponse, UploadResponse
+from app.services.helpers import (
+    content_from_upload,
+    get_topics_catalog_from_metadata,
+    resolve_docs_dir_from_config,
+    safe_basename,
+    topic_match_score,
+)
+from utils import md_to_faiss
+from utils.retrievers import get_retriever
+
+
+# ---------------------------------------------------------------------------
+# Precheck temático
+# ---------------------------------------------------------------------------
+
+def precheck_content(filename: str, content: str) -> PrecheckResponse:
+    """Evalúa alineación temática del contenido antes de la indexación."""
+    sample_text = f"{filename}\n\n{content[:20000]}" if content else filename
+    inferred_topic = md_to_faiss._infer_topic_from_text(sample_text)
+    topics_catalog = get_topics_catalog_from_metadata()
+
+    matched_topics = []
+    if inferred_topic:
+        matched_topics = [
+            topic for topic in topics_catalog
+            if topic_match_score(topic, inferred_topic) > 0
+        ]
+
+    if inferred_topic and matched_topics:
+        return PrecheckResponse(
+            score=0.95,
+            recommendation="allow",
+            rationale=(
+                f"Tema detectado como '{inferred_topic}', "
+                "com correspondência no catálogo já indexado."
+            ),
+            matched_topics=matched_topics,
+        )
+
+    if inferred_topic:
+        return PrecheckResponse(
+            score=0.55,
+            recommendation="confirm",
+            rationale=(
+                f"Tema provável detectado: '{inferred_topic}', "
+                "mas sem correspondência exata com os tópicos já indexados."
+            ),
+            matched_topics=matched_topics or [inferred_topic],
+        )
+
+    return PrecheckResponse(
+        score=0.10,
+        recommendation="block",
+        rationale=(
+            "Não foi possível identificar um tema alinhado ao escopo com confiança suficiente."
+        ),
+        matched_topics=[],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Upload e indexação
+# ---------------------------------------------------------------------------
+
+def upload_and_index(file_bytes: bytes, original_filename: str) -> UploadResponse:
+    """Recibe bytes de un archivo, lo convierte, guarda e indexa en FAISS."""
+    if state.CONFIG.get("index", {}).get("type", "faiss").lower() != "faiss":
+        raise HTTPException(
+            status_code=400,
+            detail="Upload direto está habilitado apenas quando index.type = 'faiss'.",
+        )
+
+    safe_name = safe_basename(original_filename)
+    if not safe_name:
+        raise HTTPException(status_code=400, detail="Nome de arquivo inválido.")
+
+    ext = Path(safe_name).suffix.lower()
+    if ext not in {".md", ".txt", ".pdf", ".docx"}:
+        raise HTTPException(
+            status_code=400,
+            detail="Formato não suportado. Use .md, .txt, .pdf ou .docx.",
+        )
+
+    if not file_bytes:
+        raise HTTPException(status_code=400, detail="Arquivo vazio.")
+
+    max_size_bytes = 10 * 1024 * 1024
+    if len(file_bytes) > max_size_bytes:
+        raise HTTPException(status_code=400, detail="Arquivo excede o limite de 10MB.")
+
+    content = content_from_upload(file_bytes, ext)
+
+    docs_dir = resolve_docs_dir_from_config(state.CONFIG)
+    os.makedirs(docs_dir, exist_ok=True)
+
+    stem = Path(safe_name).stem
+    target_name = f"{stem}.md"
+    target_path = os.path.join(docs_dir, target_name)
+    document_id = stem
+
+    existing_doc_ids = {
+        str(m.get("document_id")) for m in state.METADATA if m.get("document_id")
+    }
+    if document_id in existing_doc_ids:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                "Já existe um documento com esse nome/document_id. "
+                "Renomeie o arquivo antes de enviar."
+            ),
+        )
+
+    with open(target_path, "w", encoding="utf-8") as f:
+        f.write(content)
+
+    with state.INDEX_UPDATE_LOCK:
+        try:
+            md_to_faiss.build_faiss_from_md(
+                input_path=target_path,
+                index_dir=state.CONFIG["paths"]["index_dir"],
+                model_name=state.CONFIG["embeddings"]["model_name"],
+                splitter=state.CONFIG["splitter"]["type"],
+                chunk_size=int(state.CONFIG["splitter"]["chunk_size"]),
+                chunk_overlap=int(state.CONFIG["splitter"]["overlap"]),
+                retrieval_model=state.EMBED_MODEL,
+                max_documents=1,
+            )
+            state.RETRIEVER = get_retriever(state.CONFIG)
+            state.METADATA = getattr(state.RETRIEVER, "metadata", [])
+        except Exception as exc:
+            if os.path.exists(target_path):
+                os.remove(target_path)
+            raise HTTPException(
+                status_code=500,
+                detail=f"Falha ao indexar arquivo: {exc}",
+            ) from exc
+
+    return UploadResponse(
+        ok=True,
+        message="Documento enviado e indexado com sucesso.",
+        filename=target_name,
+        document_id=document_id,
+    )

app/services/llm.py

@@ -0,0 +1,258 @@
+"""
+Llamadas al LLM (OpenAI) y generación de presentaciones PPTX.
+"""
+
+import json
+import os
+import tempfile
+from typing import Any, Dict, List
+
+import app.core.state as state
+from app.services.helpers import normalizar_texto
+
+
+# ---------------------------------------------------------------------------
+# RAG query → LLM
+# ---------------------------------------------------------------------------
+
+def call_llm(
+    question: str,
+    context_fragments: List[Dict[str, Any]],
+    temperature: float | None = None,
+    mode: str = "chatbot",
+) -> str:
+    if not context_fragments:
+        return "Não há informação suficiente na base. (nenhum trecho recuperado)"
+
+    config = state.CONFIG
+    provider = config.get("llm", {}).get("provider", "openai")
+    model_name = config.get("llm", {}).get("model", "gpt-4o-mini")
+
+    # Mapa de citação numérica por documento
+    citation_ids: Dict[str, int] = {}
+    next_id = 1
+    for m in context_fragments:
+        doc_id = m.get("document_id")
+        if not doc_id:
+            continue
+        if doc_id not in citation_ids:
+            citation_ids[doc_id] = next_id
+            next_id += 1
+
+    context_lines: List[str] = []
+    for m in context_fragments:
+        doc_id = m.get("document_id")
+        if not doc_id:
+            continue
+        cit_num = citation_ids.get(doc_id)
+        tag = f"[{cit_num}]" if cit_num is not None else ""
+        texto = normalizar_texto(m.get("content", ""))
+        context_lines.append(f"{tag} {texto}" if tag else texto)
+    context_text = "\n".join(context_lines)
+
+    referencias_lines: List[str] = []
+    for doc_id, cit_num in sorted(citation_ids.items(), key=lambda x: x[1]):
+        titulo = None
+        for m in context_fragments:
+            if m.get("document_id") == doc_id:
+                titulo = m.get("document_title") or doc_id
+                break
+        referencias_lines.append(f"[{cit_num}] {titulo}")
+    referencias_text = "\n".join(referencias_lines)
+
+    system_prompts: Dict[str, Any] = (
+        state.PROMPTS.get("system_prompts", {}) if isinstance(state.PROMPTS, dict) else {}
+    )
+    system_prompt = system_prompts.get(mode)
+    if not system_prompt:
+        system_prompt = (
+            "Você é um assistente especializado em química e NORM. "
+            "Use SOMENTE os trechos de contexto fornecidos e nunca invente dados. "
+            "Se a pergunta mencionar anos posteriores a 2025 (por exemplo 2026 em diante), "
+            "responda explicitamente que não há informações disponíveis para esses anos na base "
+            "e não tente extrapolar. "
+            "Quando citar fontes, use o formato [n], onde n corresponde ao número da referência "
+            "na tabela de referências fornecida. "
+        )
+
+    if provider == "openai":
+        try:
+            from openai import OpenAI
+        except ImportError:
+            return (
+                "Não há informação suficiente na base. "
+                "(biblioteca openai não instalada no ambiente)"
+            )
+
+        api_key = os.getenv("OPENAI_API_KEY")
+        if not api_key:
+            return (
+                "Não há informação suficiente na base. "
+                "(variável de ambiente OPENAI_API_KEY não configurada)"
+            )
+
+        client = OpenAI(api_key=api_key)
+        messages = [
+            {"role": "system", "content": system_prompt},
+            {
+                "role": "user",
+                "content": (
+                    "Contexto:\n" + context_text + "\n\n"
+                    + "Referências (por número):\n" + referencias_text + "\n\n"
+                    + f"Pergunta: {question}"
+                ),
+            },
+        ]
+        temperature_value = 0.5 if temperature is None else float(temperature)
+        resp = client.chat.completions.create(
+            model=model_name,
+            messages=messages,
+            temperature=temperature_value,
+        )
+        return resp.choices[0].message.content.strip()
+
+    # Fallback para provider não suportado
+    resumen = []
+    for line in context_lines:
+        if len(line) > 300:
+            line = line[:300] + "..."
+        resumen.append(line)
+    return "Provvedor de LLM não suportado; mostrando trechos brutos:\n" + "\n".join(resumen)
+
+
+# ---------------------------------------------------------------------------
+# Slides → LLM
+# ---------------------------------------------------------------------------
+
+def call_llm_for_slides(
+    ideas: List[str],
+    title: str | None = None,
+    audience: str | None = None,
+    language: str | None = None,
+    num_slides: int | None = None,
+    temperature: float | None = 0.4,
+) -> dict:
+    config = state.CONFIG
+    provider = config.get("llm", {}).get("provider", "openai")
+    model_name = config.get("llm", {}).get("model", "gpt-4o-mini")
+
+    system_prompts: Dict[str, Any] = (
+        state.PROMPTS.get("system_prompts", {}) if isinstance(state.PROMPTS, dict) else {}
+    )
+    system_prompt = system_prompts.get("gerar_slides")
+    if not system_prompt:
+        raise RuntimeError("Prompt 'gerar_slides' não configurado em prompts.json")
+
+    user_payload = {
+        "ideas": ideas,
+        "title_hint": title,
+        "audience": audience,
+        "language": language or "pt",
+        "num_slides": num_slides,
+    }
+
+    if provider != "openai":
+        raise RuntimeError("Somente provider 'openai' é suportado para geração de slides.")
+
+    try:
+        from openai import OpenAI
+    except ImportError as exc:
+        raise RuntimeError("Biblioteca openai não instalada para geração de slides.") from exc
+
+    api_key = os.getenv("OPENAI_API_KEY")
+    if not api_key:
+        raise RuntimeError("Variável de ambiente OPENAI_API_KEY não configurada.")
+
+    client = OpenAI(api_key=api_key)
+    messages = [
+        {"role": "system", "content": system_prompt},
+        {
+            "role": "user",
+            "content": (
+                "Gere uma apresentação em JSON seguindo o formato especificado. "
+                "Aqui estão as ideias base e metadados em JSON:\n"
+                + json.dumps(user_payload, ensure_ascii=False)
+            ),
+        },
+    ]
+    temperature_value = 0.4 if temperature is None else float(temperature)
+    resp = client.chat.completions.create(
+        model=model_name,
+        messages=messages,
+        temperature=temperature_value,
+    )
+    raw = resp.choices[0].message.content.strip()
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise RuntimeError(
+            f"Resposta do modelo não é JSON válido: {exc}. Conteúdo: {raw[:400]}"
+        ) from exc
+
+    if not isinstance(data, dict) or "slides" not in data:
+        raise RuntimeError("JSON retornado não contém chave 'slides'.")
+
+    return data
+
+
+# ---------------------------------------------------------------------------
+# PPTX builder
+# ---------------------------------------------------------------------------
+
+def build_pptx_from_structure(structure: Dict[str, Any]) -> str:
+    """Construye un archivo PPTX temporal y devuelve su ruta."""
+    try:
+        from pptx import Presentation
+    except ImportError as exc:
+        raise RuntimeError("Biblioteca python-pptx não instalada no ambiente.") from exc
+
+    pres = Presentation()
+    title = str(structure.get("title") or "Apresentação gerada pelo Chatbot NORM")
+
+    title_layout = pres.slide_layouts[0]
+    slide = pres.slides.add_slide(title_layout)
+    slide.shapes.title.text = title
+    if len(slide.placeholders) > 1:
+        slide.placeholders[1].text = (
+            "Gerado automaticamente a partir de ideias do Chatbot NORM"
+        )
+
+    slides_data = structure.get("slides") or []
+    if not isinstance(slides_data, list):
+        slides_data = []
+
+    for slide_data in slides_data:
+        layout = pres.slide_layouts[1]
+        s = pres.slides.add_slide(layout)
+        s.shapes.title.text = str(slide_data.get("title") or "")
+
+        body_placeholder = s.placeholders[1]
+        tf = body_placeholder.text_frame
+        while tf.paragraphs:
+            p = tf.paragraphs[0]
+            p.text = ""
+            if len(tf.paragraphs) == 1:
+                break
+            tf._element.remove(p._p)
+
+        bullets = slide_data.get("bullets") or []
+        if isinstance(bullets, list):
+            first = True
+            for bullet in bullets:
+                text = str(bullet)
+                if first:
+                    tf.paragraphs[0].text = text
+                    first = False
+                else:
+                    p = tf.add_paragraph()
+                    p.text = text
+                    p.level = 0
+
+        notes = slide_data.get("notes")
+        if notes:
+            s.notes_slide.notes_text_frame.text = str(notes)
+
+    with tempfile.NamedTemporaryFile(delete=False, suffix=".pptx") as tmp:
+        pres.save(tmp.name)
+        return tmp.name

app/services/rag.py

@@ -0,0 +1,430 @@
+"""
+Lógica principal del pipeline RAG:
+  - process_query(payload) → QueryResponse
+"""
+
+import re
+from typing import Any, Dict, List, Set
+
+import app.core.state as state
+from app.core.state import embed_query
+from app.models.requests import QueryRequest
+from app.models.responses import QueryResponse
+from app.services.helpers import (
+    build_chatbot_fallback_answer,
+    collect_metadata_chunks_for_docs,
+    contains_any_trigger,
+    detect_target_sections,
+    extract_explicit_target_doc_ids,
+    extract_quoted_titles,
+    get_documents_catalog,
+    get_topics_catalog_from_metadata,
+    list_documents_from_metadata,
+    normalize_match_text,
+    resolve_doc_ids_from_titles,
+    resolve_topic_from_question,
+    supplement_retrieval_for_target_docs,
+)
+from app.services.llm import call_llm
+
+
+def process_query(payload: QueryRequest) -> QueryResponse:  # noqa: C901 – lógica RAG densa por diseño
+    top_k = payload.top_k or state.CONFIG.get("retrieve", {}).get("top_k", 4)
+    temperature = payload.temperature
+    mode = payload.mode
+
+    query_text = payload.question
+    effective_mode = mode
+    quoted_titles = extract_quoted_titles(payload.question)
+    target_doc_ids_for_filter: Set[str] = set()
+    catalog = get_documents_catalog()
+    explicit_target_doc_ids = extract_explicit_target_doc_ids(payload.question, catalog)
+    if explicit_target_doc_ids:
+        target_doc_ids_for_filter = set(explicit_target_doc_ids)
+
+    pregunta_lower = payload.question.lower().strip()
+
+    chatbot_min_top_k = int(state.CONFIG.get("retrieve", {}).get("chatbot_top_k", 16))
+    if mode == "chatbot":
+        top_k = max(top_k, chatbot_min_top_k)
+
+    # === 0. Triggers: ayuda, smalltalk, saludo ===
+    help_triggers = [str(t).lower() for t in state.TRIGGERS.get("help", [])]
+    smalltalk_triggers = [str(t).lower() for t in state.TRIGGERS.get("smalltalk", [])]
+    greeting_triggers = [str(t).lower() for t in state.TRIGGERS.get("greeting", [])]
+
+    if contains_any_trigger(pregunta_lower, help_triggers):
+        return QueryResponse(answer=state.HELP_SCOPE_TEXT, retrieved=[])
+    if contains_any_trigger(pregunta_lower, smalltalk_triggers):
+        return QueryResponse(answer=state.ABOUT_BOT_TEXT, retrieved=[])
+    if contains_any_trigger(pregunta_lower, greeting_triggers):
+        return QueryResponse(answer=state.GREETING_TEXT, retrieved=[])
+
+    # === 0.1. Intenciones de resumen / tabla ===
+    multi_summary = False
+    summary_keywords = ["resumo", "resumen", "summary", "resuma", "resumir"]
+    table_keywords = ["tabela", "tabla", "table", "gerar tabela", "gera uma tabela"]
+    summary_modes = {"summary", "summary_multi", "summary_sections", "summary_sections_multi"}
+    table_modes = {"table", "table_multi"}
+    multi_doc_markers = [
+        "esses documentos", "esses 5 documentos", "esses cinco documentos",
+        "esses 10 documentos", "esses dez documentos",
+        "documentos listados", "documentos acima", "documentos mostrados",
+        "os documentos", "los documentos", "all documents",
+        "todos", "todas", "all", "ambos", "both",
+        "os 3", "los 3", "3 documentos", "3 docs",
+    ]
+
+    has_summary_intent = contains_any_trigger(pregunta_lower, summary_keywords)
+    has_table_intent = contains_any_trigger(pregunta_lower, table_keywords)
+    has_multi_doc_reference = contains_any_trigger(pregunta_lower, multi_doc_markers)
+    target_sections = detect_target_sections(pregunta_lower)
+
+    if has_summary_intent and has_multi_doc_reference and not state.LAST_LISTED_DOCS:
+        return QueryResponse(
+            answer=(
+                "Não encontrei uma lista recente de documentos no contexto atual. "
+                "Por favor, liste os documentos novamente e depois peça o resumo dos documentos listados."
+            ),
+            retrieved=[],
+        )
+
+    if has_table_intent and has_multi_doc_reference:
+        docs_scope = state.LAST_LISTED_DOCS if state.LAST_LISTED_DOCS else catalog
+        if docs_scope:
+            effective_mode = "table_multi"
+            target_doc_ids_for_filter = {str(d.get("id")) for d in docs_scope if d.get("id")}
+            titulos = [str(d.get("title") or d.get("id")) for d in docs_scope if (d.get("title") or d.get("id"))]
+            titulos_str = "; ".join(titulos)
+            query_text = (
+                "Gere uma tabela comparativa, usando apenas os trechos fornecidos, para os documentos alvo abaixo. "
+                "Use colunas objetivas e inclua citações [n] nas células factuais relevantes. "
+                f"Documentos alvo ({len(titulos)}): {titulos_str}"
+            )
+            top_k = max(top_k, max(12, len(docs_scope) * 8))
+        else:
+            effective_mode = "table"
+            top_k = max(top_k, 12)
+    elif has_table_intent:
+        effective_mode = "table"
+        top_k = max(top_k, 12)
+
+    if state.LAST_LISTED_DOCS and has_summary_intent and has_multi_doc_reference and target_sections:
+        multi_summary = True
+        effective_mode = "summary_sections_multi"
+        docs_scope = state.LAST_LISTED_DOCS
+        target_doc_ids_for_filter = {str(d.get("id")) for d in docs_scope if d.get("id")}
+        titulos = [str(d.get("title") or d.get("id")) for d in docs_scope if (d.get("title") or d.get("id"))]
+        titulos_str = "; ".join(titulos)
+        sections_text = ", ".join(target_sections)
+        query_text = (
+            f"Resuma SOMENTE as seções '{sections_text}' de CADA documento listado abaixo, sem misturar conteúdos entre documentos. "
+            "Formato obrigatório: um bloco por documento com título. "
+            "Para cada seção solicitada, escreva minimo 150 palavras, com mais detalhe técnico. "
+            "Use citações [n] ao longo do texto. "
+            f"Documentos alvo ({len(titulos)}): {titulos_str}"
+        )
+        top_k = max(top_k, max(12, len(docs_scope) * 8))
+
+    elif state.LAST_LISTED_DOCS and has_summary_intent and has_multi_doc_reference:
+        multi_summary = True
+        effective_mode = "summary_multi"
+        docs_scope = state.LAST_LISTED_DOCS
+        target_doc_ids_for_filter = {str(d.get("id")) for d in docs_scope if d.get("id")}
+        titulos_list: List[str] = [
+            str(d.get("title") or d.get("id"))
+            for d in docs_scope
+            if (d.get("title") or d.get("id"))
+        ]
+        titulos_str = "; ".join(titulos_list)
+        query_text = (
+            "Com base exclusivamente nos trechos dos documentos abaixo, "
+            "elabore um resumo integrado e sintético, destacando temas centrais, "
+            "pontos em comum e diferenças relevantes entre eles."
+            "IMPORTANTE: use citações no formato [n] ao longo do texto. Documentos: "
+            + titulos_str
+        )
+        top_k = max(top_k, max(12, len(docs_scope) * 6))
+
+    # === Detección de pedido de listado de documentos ===
+    keywords_lista = [
+        "list", "lista", "listar", "mostrar", "exibir", "quais são",
+        "quais sao", "que documentos", "documentos disponíveis",
+        "documentos disponiveis", "documentos indexados",
+    ]
+    doc_words = ["documento", "documentos", "documents"]
+    topic_words = ["topic", "topico", "tópico", "tema"]
+    topics_catalog = get_topics_catalog_from_metadata()
+    requested_topic = resolve_topic_from_question(payload.question, topics_catalog)
+    has_topic_reference = contains_any_trigger(pregunta_lower, topic_words) or bool(requested_topic)
+
+    is_list_request = (
+        (not multi_summary)
+        and (not has_table_intent)
+        and contains_any_trigger(pregunta_lower, keywords_lista)
+        and contains_any_trigger(pregunta_lower, doc_words)
+    )
+
+    requested_n: int | None = None
+    num_match = re.search(r"\b(\d{1,3})\b", pregunta_lower)
+    if num_match:
+        try:
+            requested_n = int(num_match.group(1))
+        except ValueError:
+            requested_n = None
+
+    if is_list_request:
+        if has_topic_reference and requested_topic:
+            documentos = list_documents_from_metadata(topic=requested_topic)
+        else:
+            if hasattr(state.RETRIEVER, "list_documents"):
+                documentos = state.RETRIEVER.list_documents()
+            else:
+                documentos = list_documents_from_metadata()
+
+        total = len(documentos)
+        limite = max(1, min(requested_n, total)) if requested_n is not None else total
+        documentos_mostrados = documentos[:limite]
+
+        if has_topic_reference and requested_topic:
+            lista_formatada = "\n".join([
+                f"{i+1}. {doc.get('title', doc.get('id', 'Desconhecido'))}"
+                for i, doc in enumerate(documentos_mostrados)
+            ])
+            resposta = (
+                f"📚 **Documentos do tópico '{requested_topic}' ({limite} de {total} no total):**\n\n"
+                + lista_formatada
+            )
+        else:
+            lista_formatada = "\n".join([
+                f"{i+1}. {doc.get('title', doc.get('id', 'Desconhecido'))}"
+                for i, doc in enumerate(documentos_mostrados)
+            ])
+            resposta = (
+                f"📚 **Documentos indexados no sistema ({limite} de {total} no total):**\n\n"
+                + lista_formatada
+            )
+
+        resposta = re.sub(r"\s*</div>\s*$", "", resposta, flags=re.IGNORECASE)
+        state.LAST_LISTED_DOCS = documentos_mostrados
+        return QueryResponse(answer=resposta, retrieved=[])
+
+    # === Resolución de scope para resúmenes y tablas ===
+    is_summary_request = (effective_mode in summary_modes) or has_summary_intent
+    is_table_request = (effective_mode in table_modes) or has_table_intent
+
+    if is_summary_request or is_table_request:
+        resolved_from_titles = (
+            resolve_doc_ids_from_titles(quoted_titles, catalog) if quoted_titles else set()
+        )
+
+        if effective_mode in {"summary_sections", "summary_sections_multi"} and target_sections:
+            sections_text = ", ".join(target_sections)
+            query_text = f"{query_text}\n\nSeções solicitadas: {sections_text}."
+
+        if explicit_target_doc_ids:
+            target_doc_ids_for_filter = set(explicit_target_doc_ids)
+        elif resolved_from_titles:
+            target_doc_ids_for_filter = set(resolved_from_titles)
+        elif (
+            effective_mode in {"summary_multi", "summary_sections_multi", "table_multi"}
+            and state.LAST_LISTED_DOCS
+            and not target_doc_ids_for_filter
+        ):
+            target_doc_ids_for_filter = {
+                str(d.get("id")) for d in state.LAST_LISTED_DOCS if d.get("id")
+            }
+
+        if is_table_request and quoted_titles and not resolved_from_titles:
+            return QueryResponse(
+                answer=(
+                    "Não há informações suficientes na base. "
+                    "Não foi possível localizar exatamente o documento solicitado para gerar a tabela."
+                ),
+                retrieved=[],
+            )
+
+        if target_doc_ids_for_filter:
+            top_k = max(top_k, max(12, len(target_doc_ids_for_filter) * 8))
+        elif quoted_titles:
+            query_text = (
+                f"{payload.question}\n\n"
+                f"Título alvo (priorizar este documento): {'; '.join(quoted_titles)}"
+            )
+            top_k = max(top_k, 12)
+
+    # === 1. Embed y búsqueda ===
+    index_type = state.CONFIG.get("index", {}).get("type", "faiss").lower()
+    normalize = index_type == "faiss"
+    q_vec = embed_query(state.EMBED_MODEL, query_text, normalize=normalize)
+    retrieved: List[Dict[str, Any]] = state.RETRIEVER.retrieve(q_vec, top_k)
+
+    if len(target_doc_ids_for_filter) == 1 and is_summary_request:
+        direct_doc_chunks = collect_metadata_chunks_for_docs(
+            metadata=state.METADATA,
+            target_doc_ids=target_doc_ids_for_filter,
+            max_chunks_per_doc=20,
+        )
+        if direct_doc_chunks:
+            retrieved = direct_doc_chunks
+
+    if target_doc_ids_for_filter:
+        scoped = [
+            item for item in retrieved
+            if str(item.get("document_id", "")) in target_doc_ids_for_filter
+        ]
+        retrieved = scoped
+        chunks_per_doc = 6
+        retrieved = supplement_retrieval_for_target_docs(
+            retrieved=retrieved,
+            target_doc_ids=target_doc_ids_for_filter,
+            metadata=state.METADATA,
+            chunks_per_doc=chunks_per_doc,
+        )
+
+    if quoted_titles and retrieved and not target_doc_ids_for_filter:
+        target_titles_norm = [
+            normalize_match_text(t) for t in quoted_titles if normalize_match_text(t)
+        ]
+
+        def _title_score(item: Dict[str, Any]) -> int:
+            title_norm = normalize_match_text(item.get("document_title") or "")
+            if not title_norm:
+                return 0
+            score = 0
+            for target in target_titles_norm:
+                if title_norm == target:
+                    score = max(score, 3)
+                elif target in title_norm:
+                    score = max(score, 2)
+                elif title_norm in target and len(title_norm) >= 20:
+                    score = max(score, 1)
+            return score
+
+        scored_items = [(item, _title_score(item)) for item in retrieved]
+        best_score = max(score for _, score in scored_items)
+
+        if best_score > 0:
+            best_item = next(item for item, score in scored_items if score == best_score)
+            best_doc_id = best_item.get("document_id")
+            if best_doc_id:
+                retrieved = [item for item, _ in scored_items if item.get("document_id") == best_doc_id]
+            else:
+                retrieved = [item for item, score in scored_items if score == best_score]
+
+    # === 2. Asignar citation_id temporal ===
+    citation_ids: Dict[str, int] = {}
+    next_id = 1
+    for m in retrieved:
+        doc_id = m.get("document_id")
+        if not doc_id:
+            continue
+        if doc_id not in citation_ids:
+            citation_ids[doc_id] = next_id
+            next_id += 1
+        m["citation_id"] = citation_ids[doc_id]
+
+    # === DEBUG ===
+    print("\n[DEBUG] ===== CHUNKS ENVIADOS AL MODELO =====")
+    print(f"[DEBUG] question: {payload.question}")
+    print(f"[DEBUG] mode: {effective_mode}")
+    print(f"[DEBUG] total_chunks: {len(retrieved)}")
+    for i, ch in enumerate(retrieved, start=1):
+        from app.services.helpers import normalizar_texto
+        doc_id = ch.get("document_id", "N/A")
+        doc_title = ch.get("document_title", "N/A")
+        frag_id = ch.get("fragment_id", ch.get("idx", "N/A"))
+        content = normalizar_texto(ch.get("content", ""))
+        preview = content[:220] + ("..." if len(content) > 220 else "")
+        print(
+            f"[DEBUG] #{i} | doc_id={doc_id} | frag={frag_id} | title={doc_title}\n"
+            f"        {preview}"
+        )
+    print("[DEBUG] =====================================\n")
+
+    # === 4. Llamar al LLM ===
+    answer = call_llm(query_text, retrieved, temperature, effective_mode)
+
+    # === 5. Detectar tag especial <<LIST_DOCUMENTS>> ===
+    if answer.strip() == "<<LIST_DOCUMENTS>>":
+        if is_list_request:
+            if hasattr(state.RETRIEVER, "list_documents"):
+                documentos = state.RETRIEVER.list_documents()
+            else:
+                documentos = list_documents_from_metadata()
+            total = len(documentos)
+            limite = max(1, min(requested_n, total)) if requested_n is not None else total
+            documentos_mostrados = documentos[:limite]
+            lista_formatada = "\n".join([
+                f"{i+1}. {doc.get('title', doc.get('id', 'Desconhecido'))}"
+                for i, doc in enumerate(documentos_mostrados)
+            ])
+            resposta = (
+                f"📚 **Documentos indexados no sistema ({limite} de {total} no total):**\n\n"
+                + lista_formatada
+            )
+            resposta = re.sub(r"\s*</div>\s*$", "", resposta, flags=re.IGNORECASE)
+            state.LAST_LISTED_DOCS = documentos_mostrados
+            return QueryResponse(answer=resposta, retrieved=[])
+        else:
+            answer = state.NO_INFO_PREFIX
+
+    # === 6. Sin información ===
+    if answer.strip().startswith(state.NO_INFO_PREFIX) or answer.strip().startswith(
+        "Desculpe, mas não tenho informações"
+    ):
+        if effective_mode == "chatbot" and retrieved:
+            stripped = answer.strip()
+            if stripped.startswith(state.NO_INFO_PREFIX):
+                suffix = stripped[len(state.NO_INFO_PREFIX):].lstrip(" .:-\n\t")
+                answer = (suffix[0].upper() + suffix[1:]) if suffix else build_chatbot_fallback_answer(retrieved)
+            else:
+                answer = build_chatbot_fallback_answer(retrieved)
+        else:
+            return QueryResponse(answer=answer, retrieved=[])
+
+    if effective_mode == "chatbot" and retrieved and not answer.strip():
+        answer = build_chatbot_fallback_answer(retrieved)
+
+    if answer.strip().startswith(state.NO_INFO_PREFIX) or answer.strip().startswith(
+        "Desculpe, mas não tenho informações"
+    ):
+        return QueryResponse(answer=answer, retrieved=[])
+
+    # === 7. Filtro de saludos genéricos ===
+    saludo_regex = r"^(ol[áa]|hola|hello|hi)[!,.]?"
+    generic_prefixes = [
+        "eu sou um assistente",
+        "sou um assistente",
+        "sou um assistente virtual",
+        "eu sou um assistente virtual",
+    ]
+    if re.match(saludo_regex, answer.strip().lower()) or any(
+        answer.strip().lower().startswith(p) for p in generic_prefixes
+    ):
+        return QueryResponse(answer=answer, retrieved=[])
+
+    # === 8. Renumeración de citas ===
+    raw_citations = [int(m.group(1)) for m in re.finditer(r"\[(\d+)\]", answer)]
+    if raw_citations:
+        unique_old_numbers = list(dict.fromkeys(raw_citations))
+        renumber_map = {old: new for new, old in enumerate(unique_old_numbers, start=1)}
+
+        for old, new in renumber_map.items():
+            answer = answer.replace(f"[{old}]", f"[TEMP_{new}]")
+        answer = answer.replace("TEMP_", "")
+        answer = re.sub(r"\[(\d+)\](\s*\[\1\])+", r"[\1]", answer)
+
+        for m in retrieved:
+            old_id = m.get("citation_id")
+            if old_id in renumber_map:
+                m["citation_id"] = renumber_map[old_id]
+            else:
+                m["citation_id"] = None
+
+        retrieved = [m for m in retrieved if m.get("citation_id") is not None]
+    else:
+        retrieved = []
+
+    answer = re.sub(r"\s*</div>\s*$", "", answer, flags=re.IGNORECASE)
+    return QueryResponse(answer=answer, retrieved=retrieved)

configs/config.json

@@ -0,0 +1,58 @@
+{
+    "embeddings": {
+        "model_name": "intfloat/multilingual-e5-large",
+        "output_dir": "embeddings2",
+        "provider": "hf",
+        "max_files_for_debug": 800,
+        "shuffle_sample": true,
+        "random_seed": 42,
+        "require_frontmatter": true,
+        "priority_max": 700,
+        "priority_keywords": [
+            "\\bb[aá]rio\\b",
+            "\\bbarium\\b",
+            "\\bNORM\\b",
+            "naturally occurring radioactive",
+            "TENORM",
+            "226Ra",
+            "228Ra",
+            "Ra-226",
+            "Ra-228",
+            "sedimento[s]? marino[s]?",
+            "marine sediment",
+            "sediment[oa]s? de mar"
+        ]
+    },
+    "splitter": {
+        "type": "tokens",
+        "chunk_size": 450,
+        "overlap": 90
+    },
+    "retrieve": {
+        "top_k": 12,
+        "chatbot_top_k": 20
+    },
+    "paths": {
+        "input_path": "Docs/*.md",
+        "chunks_path": "data/chunks",
+        "embeddings_dir": "data/embeddings",
+        "index_dir": "data/index"
+    },
+   "index": {
+        "type": "faiss",
+        "index_file": "data/index/intfloat/multilingual-e5-large/faiss.index",
+        "metadata_file": "data/index/intfloat/multilingual-e5-large/metadata.jsonl",
+        "host": "https://my-elasticsearch-project-c6a2f9.es.us-central1.gcp.elastic.cloud:443", 
+        "index_name": "chatbot-norm",
+        "vector_field": "embedding",
+        "api_key": null
+    },
+    "llm": {
+        "provider": "openai",
+        "model": "gpt-5.1",
+        "system_prompt": "Você é um assistente especialista em química e Naturally Occurring Radioactive Materials (NORM). Responde somente com informações explícitas dos trechos de contexto. Não faça inferências, não deduza, não invente informações. Regras: - Use exclusivamente os trechos como fonte. - Quando citar fontes, use o formato [n], onde n corresponde ao número da referência na tabela de referências fornecida. - Não invente regulações, datas ou valores que não estejam presentes. - Se a pergunta mencionar anos posteriores a 2025, responda que não há dados disponíveis. - Explique termos técnicos somente se aparecerem no contexto. - Toda frase que derive de um trecho do contexto DEVE ter uma citação obrigatória no formato [n]. Se você não adicionar essas citações, sua resposta está incorreta."
+    },
+    "ui": {
+        "api_url": "http://127.0.0.1:8000/query"
+    }
+}

configs/prompts.json

@@ -0,0 +1,40 @@
+{
+  "system_prompts": {
+    "summary": "Você é um assistente especializado em criar resumos técnicos baseados exclusivamente nos trechos de contexto fornecidos. Você não deve adicionar informações que não apareçam explicitamente nos trechos. Regras: - Use apenas as informações do contexto. - Não invente dados nem interprete além do que está escrito. - Organize o resumo em 2 a 3 parágrafos curtos, seguidos de 3 a 5 bullet points com os pontos-chave mais importantes. - Se o usuário pedir um tipo de resumo (bullet points, curto, longo, técnico), adapte-se mantendo sempre a fidelidade ao contexto. - Se o contexto for insuficiente para responder de forma confiável, comece a resposta exatamente com: \"Não há informações suficientes na base.\" e, em seguida, explique em 1 ou 2 frases por que as informações são insuficientes. - Não responda perguntas que não sejam resumos. - Quando citar fontes, use o formato [n], onde n corresponde ao número da referência na tabela de referências fornecida, mas cite preferencialmente ao final do resumo.",
+    "summary_sections": "Você é um assistente especializado em resumir documentos técnicos por seções específicas. Sua tarefa é produzir um resumo estruturado SOMENTE da(s) seção(ões) solicitada(s) pelo usuário, que podem incluir: Introdução, Metodologia e/ou Resultados, usando exclusivamente os trechos de contexto fornecidos. Regras: - Use apenas as informações do contexto; não invente dados, não extrapole e não inclua interpretação além do texto. - Responda somente com a(s) seção(ões) solicitada(s) pelo usuário. - Para cada seção solicitada, use exatamente o título da seção: '### <Seção>'. - Escreva de 1 a 2 parágrafos longos por seção (ou 4 a 8 bullet points, se o usuário pedir formato em lista), mantendo linguagem técnica clara e objetiva. - Para cada seção solicitada, escreva minimo 150 palavras, com mais detalhe técnico. - Se alguma seção solicitada não estiver presente no contexto, escreva: 'Seção não encontrada no contexto fornecido.' apenas para aquela seção. - Cite fontes, usando o formato [n], onde n corresponde ao número da referência na tabela fornecida, associando cada afirmação factual relevante a pelo menos uma citação [n]. - Não responda perguntas fora da tarefa de resumo de seção.",
+    "summary_sections_multi": "Você é um assistente técnico especializado em resumir documentos por seção específica. Tarefa: resumir SOMENTE a(s) seção(ões) solicitada(s) (Introdução, Metodologia e/ou Resultados) para CADA documento alvo separadamente, usando exclusivamente os trechos fornecidos. Regras: - Não misture conteúdo entre documentos. - Produza um bloco por documento, com o formato: '### Documento: <título>' e, dentro dele, uma subseção para cada seção solicitada usando '### <Seção>'. - Escreva 1 a 2 parágrafos longos por seção (ou 4 a 8 bullet points, se o usuário pedir formato em lista). - Se faltar evidência para um documento ou se alguma seção solicitada não estiver presente no contexto, escreva: 'Seção não encontrada no contexto fornecido.' para o documento/seção correspondente. - Não invente dados, não extrapole e não inclua interpretações além do texto. - Quando citar fontes, use o formato [n], onde n corresponde ao número da referência na tabela fornecida, associando cada afirmação factual relevante a pelo menos uma citação [n]. - Não responda fora da tarefa de resumo por seção em múltiplos documentos.",
+    "table": "Você é um assistente técnico especializado em gerar tabelas de evidência técnica de um único documento, usando exclusivamente os trechos de contexto fornecidos. Regras obrigatórias: - Use somente informações explícitas do contexto. - Não invente dados, não extrapole e não use conhecimento externo. - Responda prioritariamente em tabela Markdown. - Cada linha factual deve ter pelo menos uma citação no formato [n]. - Se um campo não estiver disponível no contexto, preencha com N/D. - Se não houver evidência técnica suficiente para montar a tabela, comece exatamente com: Não há informações suficientes na base. e explique em 1-2 frases. Escopo técnico (prioridade máxima): - Extraia informações principalmente de conteúdos equivalentes a: Introdução, Metodologia e Resultados. - Foque em: objetivo do estudo, desenho/metodologia, amostra/matriz, radionuclídeos, técnicas analíticas, faixas/valores de atividade, principais achados, limitações e implicações. Restrições de relevância: - Não incluir metadados bibliográficos (título, autores, ano, periódico, DOI, afiliação, data de publicação), a menos que o usuário peça explicitamente. - Se o usuário pedir tabela sobre um tema específico, inclua apenas linhas relacionadas a esse tema e ignore o restante.",
+    "table_multi": "Você é um assistente técnico especializado em gerar tabelas comparativas para múltiplos documentos usando exclusivamente os trechos de contexto fornecidos. Regras: - Gere uma tabela Markdown comparativa, com uma linha por documento quando possível. - Não misture fatos entre documentos e não invente dados. - Inclua citações [n] nas células factuais relevantes. - Se um documento não tiver dados para algum campo, use 'N/D' nessa célula. - Se houver dados para parte dos documentos, produza a melhor tabela possível com os dados disponíveis e indique brevemente limitações ao final. Gere a tabela em formato Markdown, mas NÃO a coloque dentro de blocos de código. Escopo técnico (prioridade máxima): - Extraia informações principalmente de conteúdos equivalentes a: Introdução, Metodologia e Resultados. - Foque em: objetivo do estudo, desenho/metodologia, amostra/matriz, radionuclídeos, técnicas analíticas, faixas/valores de atividade, principais achados, limitações e implicações. Restrições de relevância: - Não incluir metadados bibliográficos (título, autores, ano, periódico, DOI, afiliação, data de publicação), a menos que o usuário peça explicitamente. - Se o usuário pedir tabela sobre um tema específico, inclua apenas linhas relacionadas a esse tema e ignore o restante.",
+    "summary_multi": "Você é um assistente especializado em produzir um resumo integrado de vários documentos técnicos sobre química e NORM. Use exclusivamente os trechos de contexto fornecidos, mas considere que eles podem não cobrir TODOS os detalhes de cada documento individual. Regras: - Construa um resumo conjunto em 2 a 3 parágrafos, seguido de 3 a 5 bullet points, destacando temas centrais, pontos em comum e diferenças relevantes entre os documentos. - Evite inventar dados; use apenas o que aparece nos trechos, mas é aceitável que o resumo não cubra exaustivamente todos os aspectos de cada documento. - Não diga que \"não há informações suficientes\" se houver trechos relevantes para pelo menos parte dos documentos; em vez disso, faça o melhor resumo possível com o material disponível e, se necessário, mencione brevemente que algumas informações podem estar incompletas. - Quando citar fontes, use o formato [n], onde n corresponde ao número da referência na tabela de referências fornecida, e garanta que cada afirmação factual relevante esteja associada a pelo menos uma citação [n].",
+    "chatbot": "Você é um assistente especialista em química e Naturally Occurring Radioactive Materials (NORM). Responde somente com informações explícitas dos trechos de contexto fornecidos. Não faça inferências, não deduza, não invente informações. Regras: - Use exclusivamente os trechos como fonte. - Estruture as respostas em parágrafos claros (introdução, explicação principal e, quando fizer sentido, conclusão), podendo incluir bullet points para listar etapas, propriedades ou recomendações, sempre baseados no contexto. - Explique termos técnicos em linguagem acessível sempre que houver informação suficiente no contexto para isso. - Quando citar fontes, use o formato [n], onde n corresponde ao número da referência na tabela de referências fornecida, e garanta que cada afirmação factual relevante esteja associada a pelo menos uma citação [n]. - Não invente regulações, datas ou valores que não estejam presentes. - Se a pergunta mencionar anos posteriores a 2026, responda claramente que não há dados disponíveis na base para esses anos e não tente extrapolar. - Se houver informação parcial relevante no contexto: - Responda utilizando apenas essa informação disponível. - Não complete lacunas com conhecimento externo. - Se NÃO houver nenhuma informação relevante no contexto: - Comece a resposta exatamente com: \"Não há informações suficientes na base.\" - Em seguida, explique em 1 ou 2 frases o que falta ou quais limites da base levam a essa conclusão.",
+    "gerar_ideias": "Você é um gerador especialista de ideias criativas, estratégicas e inovadoras. Sua função é produzir ideias originais, diferenciadas e acionáveis, baseadas exclusivamente na solicitação do usuário. Princípios a seguir: Priorize o pensamento divergente em vez do convencional. Evite ideias genéricas ou comuns. Combine disciplinas sempre que possível. Mantenha um equilíbrio entre criatividade e implementação realista (a menos que o usuário solicite ideias futuristas ou radicais). As ideias devem ser claras, concretas e explicadas de forma breve. Não repita padrões óbvios nem reformule a mesma ideia com variações mínimas. Caso o usuário não especifique restrições, assuma uma liberdade criativa moderada. Se a solicitação for ambígua, gere múltiplas abordagens possíveis. Se o tema for amplo, cubra diferentes ângulos estratégicos. Se o usuário solicitar muitas ideias, aumente progressivamente o nível de originalidade. Formato padrão de saída (a menos que o usuário indique outro): Para cada ideia, inclua: -Nome breve. -Descrição clara. -Elemento inovador. -Potencial aplicação ou impacto.",
+    "gerar_slides": "Você é um assistente especialista em design instrucional e apresentações. Sua função é transformar uma lista de ideias em um esqueleto de apresentação em slides, sem gerar o arquivo final, apenas uma estrutura em JSON. Regras gerais: - Use exclusivamente as ideias fornecidas pelo usuário (não invente novos tópicos centrais). - Organize a apresentação com um título geral, seções lógicas e slides numerados. - Para cada slide, defina: título curto, 3 a 6 bullet points e, opcionalmente, notas do apresentador com breves orientações de fala. - Adapte o nível de detalhe ao público-alvo e ao objetivo indicados pelo usuário, quando fornecidos. - Evite texto excessivamente longo em um único bullet; prefira frases curtas e claras. - Não inclua marcação Markdown, apenas texto simples. - Saída obrigatoriamente em JSON válido, com o seguinte formato: {{ \"title\": \"Título da apresentação\", \"slides\": [ {{ \"title\": \"Título do slide 1\", \"bullets\": [\"ponto 1\", \"ponto 2\"], \"notes\": \"Notas breves para o apresentador (opcional)\" }} ] }}. Não inclua nenhum texto fora do JSON."
+  },
+  "meta": {
+    "no_information_prefix": "Não há informações suficientes na base.",
+    "about_bot": "Sou o Chatbot NORM, um assistente especializado em química e materiais radioativos de ocorrência natural (NORM). Respondo com base nos documentos técnicos indexados na base de conhecimento deste sistema.",
+    "greeting": "Olá! Sou o Chatbot NORM, um assistente treinado para responder perguntas sobre química e NORM usando os documentos técnicos indexados. Você pode, por exemplo, pedir um resumo de um documento específico ou perguntar sobre um isótopo radioativo.",
+    "help_scope": "Posso ajudar respondendo perguntas sobre química, radioatividade natural (NORM), isótopos específicos e documentos técnicos indexados neste sistema. Faça perguntas objetivas e, se possível, mencione o tema ou documento de interesse para eu recuperar os trechos mais relevantes.",
+    "offtopic_default": "Minha função é responder apenas com base nos documentos técnicos de química e NORM que foram indexados. Para outros assuntos fora desse domínio, posso não ter informações suficientes na base.",
+    "goodbye": "Foi um prazer ajudar. Se precisar de mais alguma coisa sobre química ou NORM, é só perguntar novamente.",
+    "triggers": {
+      "greeting": [
+        "olá", "ola", "hola", "hello", "hi", "bom dia",
+        "boa tarde", "boa noite"
+      ],
+      "smalltalk": [
+        "quem é vc", "quem e vc", "quem é voce", "quem e voce",
+        "quem é você", "quem és tu", "quien eres", "quien es usted"
+      ],
+      "help": [
+        "em que pode me ajudar", "em que podemos ajudar",
+        "em que podeme ajudar",
+        "em que vc pode me ajudar", "em que voce pode me ajudar",
+        "em que você pode me ajudar", "em que voce pode ajudar",
+        "em que você pode ajudar", "que tipo de pergunta",
+        "que tipo de perguntas", "tipo de perguntas o bot",
+        "tipo de perguntas o chatbot"
+      ]
+    }
+  }
+}

pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "chatbot-norm"
+version = "0.1.0"
+requires-python = ">=3.9"
+dependencies = []
+
+[tool.setuptools]
+packages = [
+    "utils",
+    "app",
+    "app.core",
+    "app.models",
+    "app.services",
+    "app.routers",
+]

requirements.txt

@@ -0,0 +1,20 @@
+torch==2.3.0
+langchain_text_splitters==0.2.2
+sentence-transformers==3.0.1
+langchain_experimental==0.0.64
+tiktoken==0.7.0
+langchain-openai==0.1.14
+langchain-core==0.2.33
+langchain==0.2.14
+pandas==2.3.3
+tables==3.9.2
+fastapi==0.115.0
+uvicorn[standard]==0.30.1
+faiss-cpu==1.8.0.post1
+numpy==1.26.4
+openai>=1.32.0,<2.0.0
+elasticsearch>=8.0.0,<9.0.0
+python-docx==1.2.0
+markitdown[all]
+python-multipart==0.0.22
+python-pptx==0.6.23

scripts/build_index.py

@@ -0,0 +1,52 @@
+import os
+import sys
+import shutil
+import numpy as np
+import faiss
+from pathlib import Path
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if ROOT not in sys.path:
+	sys.path.insert(0, ROOT)
+from utils import base_utils as bu
+
+def build_faiss_index(config_path: str = "configs/config.json") -> None:
+	config = bu.load_config(config_path)
+
+	embeddings_dir = config["paths"].get("embeddings_dir", "data/embeddings")
+	index_dir = config["paths"].get("index_dir", "data/index")
+
+	embeddings_path = os.path.join(embeddings_dir, "embeddings.npy")
+	metadata_path = os.path.join(embeddings_dir, "metadata.jsonl")
+
+	if not os.path.exists(embeddings_path) or not os.path.exists(metadata_path):
+		raise FileNotFoundError(
+			f"embeddings.npy or metadata.jsonl not found in {embeddings_dir}. "
+			"Run scripts/generate_embeddings.py first."
+		)
+
+	Path(index_dir).mkdir(parents=True, exist_ok=True)
+
+	embs = np.load(embeddings_path).astype("float32")
+	if embs.ndim != 2:
+		raise ValueError("embeddings.npy must be a 2D array [N, D]")
+
+	num_vectors, dim = embs.shape
+	print(f"Loaded embeddings: {num_vectors} vectors of dimension {dim}")
+
+	faiss.normalize_L2(embs)
+
+	index = faiss.IndexFlatIP(dim)
+	index.add(embs)
+
+	index_file = os.path.join(index_dir, "faiss.index")
+	faiss.write_index(index, index_file)
+	print("Index written to", index_file)
+
+	target_metadata_path = os.path.join(index_dir, "metadata.jsonl")
+	shutil.copyfile(metadata_path, target_metadata_path)
+	print("Metadata copied to", target_metadata_path)
+
+
+if __name__ == "__main__":
+	build_faiss_index()

scripts/embd_index.py

@@ -0,0 +1,39 @@
+from utils import base_utils as bu
+from utils import md_to_faiss
+from utils import retrieval_utils as ru
+
+def main():    
+    config = bu.load_config("configs/config.json")
+    model_name = config["embeddings"]["model_name"]
+    input_path = config["paths"]["input_path"]
+    index_dir = config["paths"]["index_dir"]
+    output_dir = config["embeddings"]["output_dir"]
+    splitter = config["splitter"]["type"]
+    chunk_size = config["splitter"]["chunk_size"]
+    chunk_overlap = config["splitter"]["overlap"]
+    max_docs = config["embeddings"]["max_files_for_debug"]
+    shuffle = bool(config["embeddings"].get("shuffle_sample", False))
+    random_seed = config["embeddings"].get("random_seed")
+    require_frontmatter = bool(config["embeddings"].get("require_frontmatter", False))
+    priority_keywords = config["embeddings"].get("priority_keywords") or []
+    priority_max = config["embeddings"].get("priority_max")
+    retrieval_model = ru.load_model(model_name)
+
+    md_to_faiss.build_faiss_from_md(
+        input_path = input_path,
+        index_dir = index_dir,
+        model_name = model_name,
+        splitter = splitter,
+        chunk_size = chunk_size,
+        chunk_overlap = chunk_overlap,
+        retrieval_model = retrieval_model,
+        max_documents = max_docs,
+        shuffle = shuffle,
+        random_seed = random_seed,
+        require_frontmatter = require_frontmatter,
+        priority_keywords = priority_keywords,
+        priority_max = priority_max,
+    )
+
+if __name__ == "__main__":
+    main()

scripts/generate_embeddings.py

@@ -0,0 +1,39 @@
+import os
+import sys
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+if ROOT not in sys.path:
+    sys.path.insert(0, ROOT)
+from utils import base_utils as bu
+from utils import retrieval_utils as ru
+
+def main():
+    config = bu.load_config("configs/config.json")
+
+    os.makedirs(config["embeddings"]["output_dir"], exist_ok=True)
+
+    model_name = config["embeddings"]["model_name"]
+    input_path = config["paths"]["input_path"]
+    output_dir = config["embeddings"]["output_dir"]
+    splitter = config["splitter"]["type"]
+    chunk_size = config["splitter"]["chunk_size"]
+    chunk_overlap = config["splitter"]["overlap"]
+    retrieval_model = ru.load_model(model_name)
+
+    numpy_output_dir = config.get("paths", {}).get("embeddings_dir", "data/embeddings")
+    max_files = config.get("embeddings", {}).get("max_files_for_debug") or None
+
+    ru.generate_embeddings(
+        chunk_size=chunk_size,
+        chunk_overlap=chunk_overlap,
+        model_name=model_name,
+        input_path=input_path,
+        output_folder=output_dir,
+        splitter=splitter,
+        retrieval_model=retrieval_model,
+        export_numpy=True,
+        numpy_output_dir=numpy_output_dir,
+        max_files=max_files,
+    )
+
+if __name__ == "__main__":
+    main()

scripts/index_to_elasticsearch.py

@@ -0,0 +1,104 @@
+import json
+import os
+from typing import Dict, Any
+
+import numpy as np
+from elasticsearch import Elasticsearch, helpers
+
+from utils import base_utils as bu
+
+
+def load_embeddings_and_metadata(config: Dict[str, Any]):
+    paths = config.get("paths", {})
+    emb_dir = paths.get("embeddings_dir", "data/embeddings")
+
+    emb_path = os.path.join(emb_dir, "embeddings.npy")
+    meta_path = os.path.join(emb_dir, "metadata.jsonl")
+
+    if not os.path.exists(emb_path) or not os.path.exists(meta_path):
+        raise FileNotFoundError(
+            f"embeddings.npy or metadata.jsonl not found in {emb_dir}. "
+            "Run scripts.generate_embeddings first."
+        )
+
+    embeddings = np.load(emb_path)
+
+    metadata = []
+    with open(meta_path, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                metadata.append(json.loads(line))
+
+    if embeddings.shape[0] != len(metadata):
+        raise ValueError(
+            f"Embeddings count ({embeddings.shape[0]}) and metadata lines ({len(metadata)}) do not match."
+        )
+
+    return embeddings, metadata
+
+
+def ensure_index(client: Elasticsearch, index_name: str, dims: int, vector_field: str = "embedding"):
+    if client.indices.exists(index=index_name):
+        return
+
+    body = {
+        "mappings": {
+            "properties": {
+                "idx": {"type": "integer"},
+                "document_id": {"type": "keyword"},
+                "document_title": {"type": "text", "fields": {"raw": {"type": "keyword"}}},
+                "fragment_id": {"type": "integer"},
+                "content": {"type": "text"},
+                vector_field: {"type": "dense_vector", "dims": dims},
+            }
+        }
+    }
+    client.indices.create(index=index_name, body=body)
+
+
+def bulk_index_to_es(config: Dict[str, Any]):
+    idx_cfg = config.get("index", {})
+    host = idx_cfg.get("host", "http://localhost:9200")
+    index_name = idx_cfg.get("index_name", "chatbot-norm")
+    vector_field = idx_cfg.get("vector_field", "embedding")
+
+    embeddings, metadata = load_embeddings_and_metadata(config)
+    api_key = idx_cfg.get("api_key") or os.getenv("ELASTIC_API_KEY")
+    username = idx_cfg.get("username")
+    password = idx_cfg.get("password")
+
+    if api_key:
+        client = Elasticsearch(host, api_key=api_key)
+    elif username and password:
+        client = Elasticsearch(host, basic_auth=(username, password))
+    else:
+        client = Elasticsearch(host)
+
+    dims = embeddings.shape[1]
+    ensure_index(client, index_name, dims=dims, vector_field=vector_field)
+
+    def gen_actions():
+        for emb_vec, meta in zip(embeddings, metadata):
+            doc = {
+                "idx": meta.get("idx"),
+                "document_id": meta.get("document_id"),
+                "document_title": meta.get("document_title"),
+                "fragment_id": meta.get("fragment_id"),
+                "content": meta.get("content"),
+                vector_field: emb_vec.astype(float).tolist(),
+            }
+            yield {
+                "_index": index_name,
+                "_source": doc,
+            }
+
+    helpers.bulk(client, gen_actions())
+
+
+def main():
+    config = bu.load_config("configs/config.json")
+    bulk_index_to_es(config)
+
+
+if __name__ == "__main__":
+    main()

scripts/normalize_md_titles.py

@@ -0,0 +1,126 @@
+import os
+import glob
+
+DOCS_DIR = "Docs"  
+MAX_SCAN_LINES = 30  
+
+def guess_title_from_filename(filename: str) -> str:
+    """Crea un título legible a partir del nombre de archivo."""
+    base = os.path.splitext(os.path.basename(filename))[0]
+
+    title = base.replace("_", " ").replace("-", " ")
+
+    if title.isupper():
+        title = title.title()
+    return title.strip()
+
+
+def normalize_text_for_match(text: str) -> str:
+    """Normaliza texto para comparación aproximada (minúsculas, sin símbolos comunes)."""
+    cleaned = text.replace("_", " ").replace("-", " ")
+    cleaned = cleaned.replace("(", " ").replace(")", " ")
+    cleaned = cleaned.replace(",", " ").replace(".", " ")
+    cleaned = " ".join(cleaned.split())
+    return cleaned.lower()
+
+
+def looks_like_title(line: str) -> bool:
+    """Heurística sencilla para detectar líneas "tipo título" (no muy largas, poco ruido numérico)."""
+    txt = line.strip()
+    if not txt:
+        return False
+    # Evitar URLs claras
+    if "http://" in txt or "https://" in txt:
+        return False
+
+    if len(txt) > 200:
+        return False
+
+    digits = sum(c.isdigit() for c in txt)
+    if digits > len(txt) * 0.4:
+        return False
+    return True
+
+def normalize_md_file(path: str) -> None:
+    with open(path, "r", encoding="utf-8") as f:
+        lines = f.readlines()
+
+    if not lines:
+        return
+
+    filename_title = guess_title_from_filename(path)
+    filename_norm = normalize_text_for_match(filename_title)
+
+    best_idx = None
+    best_title = None
+    best_score = 0.0
+
+    for i, line in enumerate(lines[:MAX_SCAN_LINES]):
+        raw_line = line.rstrip("\n")
+        stripped = raw_line.strip()
+        if not stripped:
+            continue
+
+        is_heading = stripped.startswith("#")
+        candidate = stripped.lstrip("#").strip() if is_heading else stripped
+
+        if not looks_like_title(candidate):
+            continue
+
+        cand_norm = normalize_text_for_match(candidate)
+        if not cand_norm:
+            continue
+
+        fname_words = set(filename_norm.split())
+        cand_words = set(cand_norm.split())
+        if not fname_words:
+            overlap = 0.0
+        else:
+            overlap = len(fname_words & cand_words) / len(fname_words)
+
+        score = overlap
+
+        if is_heading:
+            score += 0.1
+
+        if score > best_score:
+            best_score = score
+            best_idx = i
+            best_title = candidate
+
+    # Umbral: si no encontramos nada razonable, usamos el nombre del archivo
+    if best_title is None or best_score < 0.3:
+        new_title_text = filename_title
+        insert_idx = 0
+        for i, line in enumerate(lines):
+            if line.strip():
+                insert_idx = i
+                break
+        new_title = f"# {new_title_text}\n"
+        lines.insert(insert_idx, new_title + "\n")
+    else:
+        raw_norm = best_title.replace("_", " ").replace("-", " ")
+        if raw_norm.isupper():
+            raw_norm = raw_norm.title()
+        new_title = f"# {raw_norm}\n"
+        lines[best_idx] = new_title
+
+    with open(path, "w", encoding="utf-8") as f:
+        f.writelines(lines)
+
+def main():
+    pattern = os.path.join(DOCS_DIR, "*.md")
+    files = glob.glob(pattern)
+    print(f"Encontrados {len(files)} arquivos .md em {DOCS_DIR}")
+
+    for i, path in enumerate(files, start=1):
+        print(f"[{i}/{len(files)}] Normalizando título de: {os.path.basename(path)}")
+        try:
+            normalize_md_file(path)
+        except Exception as e:
+            print(f"  -> Erro ao processar {path}: {e}")
+
+    print("Normalização de títulos concluída.")
+
+if __name__ == "__main__":
+    main()

scripts/test_retrieval_cli.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""CLI para probar retrieval del backend (sin frontend).
+
+Uso:
+  python scripts/test_retrieval_cli.py
+  python scripts/test_retrieval_cli.py --question "O que é NORM?"
+  python scripts/test_retrieval_cli.py --question "césio-137" --top-k 20
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Any, Dict, List
+
+import app.api_server as srv
+
+
+def _print_header(top_k: int, normalize: bool) -> None:
+    print("=" * 90)
+    print("Teste de retrieval (modo chatbot)")
+    print(f"top_k efetivo: {top_k}")
+    print(f"index.type: {srv.CONFIG.get('index', {}).get('type', 'faiss')}")
+    print(f"normalize L2: {normalize}")
+    print("=" * 90)
+
+
+def _print_chunk(i: int, chunk: Dict[str, Any], max_chars: int) -> None:
+    doc_id = chunk.get("document_id", "N/A")
+    title = chunk.get("document_title", "N/A")
+    topic = chunk.get("topic", "N/A")
+    frag_id = chunk.get("fragment_id", chunk.get("idx", "N/A"))
+    score = chunk.get("score")
+    cit_id = chunk.get("citation_id")
+    text = srv._normalizar_texto(chunk.get("content", ""))
+    preview = text[:max_chars] + ("..." if len(text) > max_chars else "")
+
+    print(f"\n[{i}] citation_id={cit_id} | score={score} | doc_id={doc_id} | frag={frag_id}")
+    print(f"    title: {title}")
+    print(f"    topic: {topic}")
+    print(f"    chunk: {preview}")
+
+
+def _run_retrieval(question: str, top_k_override: int | None, max_chars: int) -> None:
+    question = (question or "").strip()
+    if not question:
+        print("Pergunta vazia. Tente novamente.")
+        return
+
+    pregunta_lower = question.lower().strip()
+
+    help_triggers = [str(t).lower() for t in srv.TRIGGERS.get("help", [])]
+    smalltalk_triggers = [str(t).lower() for t in srv.TRIGGERS.get("smalltalk", [])]
+    greeting_triggers = [str(t).lower() for t in srv.TRIGGERS.get("greeting", [])]
+
+    # Replica o comportamento do endpoint: alguns casos não passam pelo retrieval.
+    if srv._contains_any_trigger(pregunta_lower, help_triggers):
+        print("[SKIP] A pergunta bateu em trigger de help; no endpoint isso retorna sem retrieval.")
+        print(f"Resposta esperada: {srv.HELP_SCOPE_TEXT}")
+        return
+    if srv._contains_any_trigger(pregunta_lower, smalltalk_triggers):
+        print("[SKIP] A pergunta bateu em trigger de smalltalk; no endpoint isso retorna sem retrieval.")
+        print(f"Resposta esperada: {srv.ABOUT_BOT_TEXT}")
+        return
+    if srv._contains_any_trigger(pregunta_lower, greeting_triggers):
+        print("[SKIP] A pergunta bateu em trigger de greeting; no endpoint isso retorna sem retrieval.")
+        print(f"Resposta esperada: {srv.GREETING_TEXT}")
+        return
+
+    top_k = top_k_override or srv.CONFIG.get("retrieve", {}).get("top_k", 4)
+    chatbot_min_top_k = int(srv.CONFIG.get("retrieve", {}).get("chatbot_top_k", 16))
+    top_k = max(int(top_k), chatbot_min_top_k)
+
+    index_type = srv.CONFIG.get("index", {}).get("type", "faiss").lower()
+    normalize = index_type == "faiss"
+
+    _print_header(top_k=top_k, normalize=normalize)
+
+    q_vec = srv.embed_query(srv.EMBED_MODEL, question, normalize=normalize)
+    retrieved: List[Dict[str, Any]] = srv.RETRIEVER.retrieve(q_vec, top_k)
+
+    citation_ids: Dict[str, int] = {}
+    next_id = 1
+    for m in retrieved:
+        doc_id = m.get("document_id")
+        if not doc_id:
+            continue
+        if doc_id not in citation_ids:
+            citation_ids[doc_id] = next_id
+            next_id += 1
+        m["citation_id"] = citation_ids[doc_id]
+
+    print(f"Pergunta: {question}")
+    print(f"Chunks recuperados: {len(retrieved)}")
+
+    if not retrieved:
+        print("Nenhum chunk recuperado.")
+        return
+
+    for i, chunk in enumerate(retrieved, start=1):
+        _print_chunk(i=i, chunk=chunk, max_chars=max_chars)
+
+    print("\nFim.\n")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Testa retrieval do backend no modo chatbot")
+    parser.add_argument("--question", "-q", type=str, help="Pergunta para execução única")
+    parser.add_argument("--top-k", type=int, default=None, help="Override de top_k")
+    parser.add_argument(
+        "--max-chars",
+        type=int,
+        default=320,
+        help="Máximo de caracteres exibidos por chunk",
+    )
+    args = parser.parse_args()
+
+    if args.question:
+        _run_retrieval(args.question, args.top_k, args.max_chars)
+        return 0
+
+    print("Modo interativo. Digite sua pergunta (ou 'sair' para encerrar).")
+    while True:
+        try:
+            q = input("\nPergunta> ").strip()
+        except (EOFError, KeyboardInterrupt):
+            print("\nEncerrado.")
+            return 0
+
+        if q.lower() in {"sair", "exit", "quit"}:
+            print("Encerrado.")
+            return 0
+
+        _run_retrieval(q, args.top_k, args.max_chars)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

utils/base_utils.py

@@ -0,0 +1,128 @@
+import os
+import json
+
+
+def load_config(config_path="configs/config.json"):
+    with open(config_path, "r", encoding="utf-8") as f:
+        config = json.load(f)
+    return config
+
+def load_prompts(path="configs/prompts.json"):
+    """Carrega o arquivo completo de prompts.
+
+    Retorna um dicionário com todas as seções definidas
+    (em especial "system_prompts" e "meta"), para que
+    tanto o LLM quanto as respostas fixas usem a mesma
+    fonte de configuração.
+    """
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+def load_md(file_path):
+    with open(file_path, "r", encoding="utf-8") as f:
+        text = f.read()
+    return text
+
+
+def extract_frontmatter(text: str) -> dict:
+    """Extrae un frontmatter YAML básico delimitado por '---' al inicio.
+
+    Soporta claves simples y listas en formato:
+    authors:\n  - "A"\n  - "B"
+    """
+    if not text:
+        return {}
+
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+
+    frontmatter_lines = []
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        frontmatter_lines.append(line)
+
+    data: dict = {}
+    current_key = None
+    for raw in frontmatter_lines:
+        line = raw.rstrip()
+        if not line.strip():
+            continue
+
+        if line.lstrip().startswith("- ") and current_key:
+            value = line.lstrip()[2:].strip().strip('"').strip("'")
+            data.setdefault(current_key, [])
+            if isinstance(data[current_key], list):
+                data[current_key].append(value)
+            continue
+
+        if ":" in line:
+            key, value = line.split(":", 1)
+            key = key.strip()
+            value = value.strip().strip('"').strip("'")
+            if value == "":
+                current_key = key
+                data[key] = []
+            else:
+                current_key = key
+                data[key] = value
+
+    return data
+
+
+def extract_title_from_md(text: str, default: str) -> str:
+
+    if not text:
+        return default
+
+    def _es_generico_ou_numero(line: str) -> bool:
+        """Detecta líneas poco informativas: solo número/año o rótulos genéricos."""
+        val = line.strip()
+        if not val:
+            return True
+
+        # Solo dígitos ("2007", "69", etc.)
+        if val.isdigit():
+            return True
+
+        # Año de 4 dígitos aislado
+        if len(val) == 4 and val.isdigit():
+            return True
+
+        lower = val.lower()
+        genericos = {
+            "article",
+            "artigo",
+            "artículo",
+            "issue",
+            "number",
+            "número",
+        }
+        if lower in genericos:
+            return True
+
+        return False
+
+    lines = [l.rstrip("\n") for l in text.splitlines()]
+
+    # 1) Buscar primer heading "#" que no sea genérico/numérico
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+        if line.startswith("#"):
+            candidate = line.lstrip("#").strip()
+            if candidate and not _es_generico_ou_numero(candidate):
+                return candidate
+
+    # 2) Si no hay heading válido, buscar primera línea de texto informativa
+    for raw_line in lines:
+        line = raw_line.strip()
+        if not line:
+            continue
+        if not _es_generico_ou_numero(line):
+            return line
+
+    # 3) Fallback
+    return default

utils/conversation_word_export.py

@@ -0,0 +1,183 @@
+import re
+from io import BytesIO
+from typing import Any, Dict, List, Tuple
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Pt, RGBColor
+
+
+# ---------------------------------------------------------------------------
+# Markdown table helpers
+# ---------------------------------------------------------------------------
+
+_TABLE_ROW_RE = re.compile(r"^\|(.+)\|$")
+_SEPARATOR_RE = re.compile(r"^\|[-:| ]+\|$")
+_INLINE_MD_RE = re.compile(r"\*{1,2}([^*]+)\*{1,2}|`([^`]+)`")
+
+
+def _strip_inline_md(text: str) -> str:
+    """Remove common inline markdown markers (bold, italic, code) from text."""
+    return _INLINE_MD_RE.sub(lambda m: m.group(1) or m.group(2), text)
+
+
+def _is_table_separator(line: str) -> bool:
+    return bool(_SEPARATOR_RE.match(line.strip()))
+
+
+def _parse_table_rows(lines: List[str]) -> List[List[str]]:
+    """Convert markdown table lines into a list of rows (list of cell strings)."""
+    rows: List[List[str]] = []
+    for line in lines:
+        if _is_table_separator(line):
+            continue
+        m = _TABLE_ROW_RE.match(line.strip())
+        if m:
+            cells = [_strip_inline_md(c.strip()) for c in m.group(1).split("|")]
+            rows.append(cells)
+    return rows
+
+
+def _shade_cell(cell, hex_color: str) -> None:
+    """Apply a background fill colour to a table cell."""
+    tc = cell._tc
+    tcPr = tc.get_or_add_tcPr()
+    shd = OxmlElement("w:shd")
+    shd.set(qn("w:val"), "clear")
+    shd.set(qn("w:color"), "auto")
+    shd.set(qn("w:fill"), hex_color)
+    tcPr.append(shd)
+
+
+def _add_markdown_table(doc: Document, lines: List[str]) -> None:
+    """Render a markdown table as a formatted Word table."""
+    rows = _parse_table_rows(lines)
+    if not rows:
+        return
+
+    max_cols = max(len(r) for r in rows)
+    table = doc.add_table(rows=len(rows), cols=max_cols)
+    table.style = "Table Grid"
+
+    for r_idx, row in enumerate(rows):
+        tr = table.rows[r_idx]
+        for c_idx in range(max_cols):
+            cell_text = row[c_idx] if c_idx < len(row) else ""
+            cell = tr.cells[c_idx]
+            para = cell.paragraphs[0]
+            run = para.add_run(cell_text)
+            if r_idx == 0:
+                run.bold = True
+                run.font.color.rgb = RGBColor(0xFF, 0xFF, 0xFF)
+                _shade_cell(cell, "2E74B5")  # blue header
+
+    doc.add_paragraph()  # spacing after table
+
+
+# ---------------------------------------------------------------------------
+# Content block splitter
+# ---------------------------------------------------------------------------
+
+def _split_into_blocks(content: str) -> List[Tuple[str, Any]]:
+    """
+    Split markdown content into alternating ("text", str) and ("table", list[str])
+    blocks so each can be rendered appropriately.
+    """
+    blocks: List[Tuple[str, Any]] = []
+    text_lines: List[str] = []
+    table_lines: List[str] = []
+    in_table = False
+
+    for line in content.split("\n"):
+        stripped = line.strip()
+        is_table_line = (
+            stripped.startswith("|")
+            and stripped.endswith("|")
+            and len(stripped) > 2
+        )
+
+        if is_table_line:
+            if not in_table:
+                if text_lines:
+                    blocks.append(("text", "\n".join(text_lines)))
+                    text_lines = []
+                in_table = True
+            table_lines.append(line)
+        else:
+            if in_table:
+                blocks.append(("table", list(table_lines)))
+                table_lines = []
+                in_table = False
+            text_lines.append(line)
+
+    if in_table and table_lines:
+        blocks.append(("table", table_lines))
+    elif text_lines:
+        blocks.append(("text", "\n".join(text_lines)))
+
+    return blocks
+
+
+def _add_content(doc: Document, content: str) -> None:
+    """Add message content to *doc*, converting markdown tables to Word tables."""
+    if not content:
+        return
+    for block_type, data in _split_into_blocks(content):
+        if block_type == "table":
+            _add_markdown_table(doc, data)
+        else:
+            text = data.strip()
+            if text:
+                doc.add_paragraph(text)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def build_conversation_docx(messages: List[Dict[str, Any]]) -> bytes:
+    """Build a .docx file from chat messages and return raw bytes."""
+    doc = Document()
+    doc.add_heading("Conversa Chatbot NORM ⚛", level=1)
+
+    for msg in messages:
+        role = str(msg.get("role") or "")
+        content = str(msg.get("content") or "").strip()
+
+        if not content:
+            continue
+
+        doc.add_heading(role, level=2)
+        _add_content(doc, content)
+
+        references = str(msg.get("references") or "").strip()
+        if references:
+            cleaned_refs = references.replace("<br>", "\n")
+            doc.add_paragraph("Referencias:")
+            doc.add_paragraph(cleaned_refs)
+
+    buffer = BytesIO()
+    doc.save(buffer)
+    buffer.seek(0)
+    return buffer.getvalue()
+
+
+def build_single_response_docx(message: Dict[str, Any]) -> bytes:
+    """Build a .docx file for a single assistant response and return raw bytes."""
+    doc = Document()
+    doc.add_heading("Ultima resposta do chatbot ⚛", level=1)
+
+    content = str(message.get("content") or "").strip()
+    _add_content(doc, content)
+
+    references = str(message.get("references") or "").strip()
+    if references:
+        cleaned_refs = references.replace("<br>", "\n")
+        doc.add_paragraph("Referencias:")
+        doc.add_paragraph(cleaned_refs)
+
+    buffer = BytesIO()
+    doc.save(buffer)
+    buffer.seek(0)
+    return buffer.getvalue()

utils/md_to_faiss.py

@@ -0,0 +1,364 @@
+import os
+import glob
+import json
+import re
+import faiss
+from pathlib import Path
+from utils import base_utils as bu
+from utils import retrieval_utils as ru
+
+
+TOPIC_KEYWORDS = {
+    "Marine and coastal ecosystems": [
+        "coastal",
+        "coast",
+        "estuary",
+        "bay",
+        "gulf",
+        "lagoon",
+        "marine ecosystem",
+        "biodiversity",
+        "seagrass",
+        "coral",
+        "phytoplankton",
+        "zooplankton",
+        "sediment",
+        "benthic",
+        "fish",
+        "shellfish",
+        "mussel",
+    ],
+    "Marine and environmental studies": [
+        "marine",
+        "ocean",
+        "sea",
+        "environment",
+        "environmental",
+        "ecology",
+        "pollution",
+        "contamination",
+        "monitoring",
+        "impact",
+        "ecosystem",
+        "water quality",
+        "biota",
+    ],
+    "Geochemistry and Elemental Analysis": [
+        "geochemistry",
+        "geochemical",
+        "elemental",
+        "trace element",
+        "isotopic",
+        "isotope",
+        "mineral",
+        "petrology",
+        "sediment chemistry",
+        "composition",
+        "xrf",
+        "icp",
+        "spectrometry",
+    ],
+    "Radioactivity and Radon Measurements": [
+        "radioactivity",
+        "radon",
+        "radiation",
+        "dosimetry",
+        "dose",
+        "activity concentration",
+        "fukushima",
+        "cesium",
+        "caesium",
+        "cs-137",
+        "137cs",
+        "131i",
+        "iodine-131",
+        "uranium",
+        "thorium",
+        "226ra",
+        "222rn",
+        "220rn",
+        "210pb",
+        "210po",
+    ],
+    "Hydrocarbon exploration and reservoir analysis": [
+        "hydrocarbon",
+        "reservoir",
+        "petroleum",
+        "oil",
+        "gas",
+        "shale",
+        "porosity",
+        "permeability",
+        "basin",
+        "seismic",
+        "well log",
+        "drilling",
+        "production",
+        "exploration",
+        "source rock",
+    ],
+}
+
+
+def _normalize_frontmatter_topic(topic_value):
+    if isinstance(topic_value, str):
+        value = topic_value.strip()
+        return value or None
+
+    if isinstance(topic_value, list):
+        for item in topic_value:
+            if isinstance(item, str) and item.strip():
+                return item.strip()
+    return None
+
+
+def _infer_topic_from_text(text: str) -> str | None:
+    if not text:
+        return None
+
+    lowered = text.lower()
+    scores = {}
+
+    for topic, keywords in TOPIC_KEYWORDS.items():
+        score = 0
+        for kw in keywords:
+            kw = kw.lower().strip()
+            if not kw:
+                continue
+
+            # For single words use word boundaries; for phrases count raw matches.
+            if " " in kw:
+                score += lowered.count(kw)
+            else:
+                score += len(re.findall(rf"\\b{re.escape(kw)}\\b", lowered))
+
+        scores[topic] = score
+
+    best_topic, best_score = max(scores.items(), key=lambda item: item[1])
+    return best_topic if best_score > 0 else None
+
+
+def build_faiss_from_md(
+    input_path: str,
+    index_dir: str,
+    model_name: str,
+    splitter: str,
+    chunk_size: int,
+    chunk_overlap: int,
+    retrieval_model,
+    max_documents: int | None = None,
+    shuffle: bool = False,
+    random_seed: int | None = None,
+    require_frontmatter: bool = False,
+    priority_keywords: list[str] | None = None,
+    priority_scan_chars: int = 4000,
+    priority_max: int | None = None,
+):
+    """
+    Build or extend a FAISS index directly from markdown documents.
+    """
+
+    index_dir = os.path.join(index_dir, model_name)
+    Path(index_dir).mkdir(parents=True, exist_ok=True)
+    index_path = os.path.join(index_dir, "faiss.index")
+    metadata_path = os.path.join(index_dir, "metadata.jsonl")
+    index_info_path = os.path.join(index_dir, "index_info.json")
+    text_splitter = ru.get_text_splitter(splitter, chunk_size, chunk_overlap)
+    md_files = sorted(glob.glob(input_path))
+
+    if not md_files:
+        raise RuntimeError(f"No markdown files found at {input_path}")
+
+    if os.path.exists(index_path):
+        print("Existing FAISS index found. Loading...")
+        index = faiss.read_index(index_path)
+        dim = index.d
+        global_idx = index.ntotal
+    else:
+        print("No existing FAISS index found. Creating new one...")
+        index = None
+        dim = None
+        global_idx = 0
+
+    indexed_docs = set()
+    if os.path.exists(metadata_path):
+        with open(metadata_path, "r", encoding="utf-8") as f:
+            for line in f:
+                if line.strip():
+                    try:
+                        m = json.loads(line)
+                        doc_id = m.get("document_id")
+                        if doc_id:
+                            indexed_docs.add(doc_id)
+                    except json.JSONDecodeError:
+                        pass
+
+    print(f"Already indexed documents: {len(indexed_docs)}")
+
+    md_files = [
+        f for f in md_files
+        if os.path.splitext(os.path.basename(f))[0] not in indexed_docs
+    ]
+
+    # Filtra archivos sin frontmatter YAML válido (si se pidió).
+    if require_frontmatter:
+        filtered: list[str] = []
+        for f in md_files:
+            try:
+                with open(f, "r", encoding="utf-8") as fh:
+                    head = fh.read(4096)
+            except OSError:
+                continue
+            if head.lstrip().startswith("---") and "title:" in head:
+                filtered.append(f)
+        print(f"Files with frontmatter: {len(filtered)} / {len(md_files)}")
+        md_files = filtered
+
+    # Separa archivos prioritarios (matchean alguna keyword) del resto.
+    priority_files: list[str] = []
+    other_files: list[str] = md_files
+    if priority_keywords:
+        patterns = [re.compile(kw, flags=re.IGNORECASE) for kw in priority_keywords]
+        priority_files = []
+        other_files = []
+        for f in md_files:
+            name = os.path.basename(f)
+            matched = any(p.search(name) for p in patterns)
+            if not matched:
+                try:
+                    with open(f, "r", encoding="utf-8") as fh:
+                        sample = fh.read(priority_scan_chars)
+                    matched = any(p.search(sample) for p in patterns)
+                except OSError:
+                    matched = False
+            (priority_files if matched else other_files).append(f)
+        print(
+            f"Priority matches ({priority_keywords!r}): {len(priority_files)}; "
+            f"others: {len(other_files)}"
+        )
+
+    if shuffle:
+        import random as _random
+        rng = _random.Random(random_seed)
+        rng.shuffle(priority_files)
+        rng.shuffle(other_files)
+        print(
+            f"Shuffled candidates (seed={random_seed!r}) "
+            f"[priority={len(priority_files)}, other={len(other_files)}]"
+        )
+
+    # Aplica cupo máximo a prioritarios para dejar espacio a variedad.
+    if priority_max is not None and len(priority_files) > priority_max:
+        leftovers = priority_files[priority_max:]
+        priority_files = priority_files[:priority_max]
+        other_files = other_files + leftovers
+        if shuffle:
+            import random as _random2
+            _random2.Random(random_seed).shuffle(other_files)
+        print(
+            f"Priority capped at {priority_max}; "
+            f"remaining priority moved to pool (others={len(other_files)})"
+        )
+
+    md_files = priority_files + other_files
+
+    if max_documents is not None:
+        md_files = md_files[:max_documents]
+
+    total_docs = len(md_files)
+    if total_docs == 0:
+        print("No new documents to index. FAISS is up to date.")
+        return
+
+    print(f"Indexing {total_docs} new documents")
+
+    with open(metadata_path, "a", encoding="utf-8") as meta_f:
+
+        for i, file in enumerate(md_files, start=1):
+            progress = (i / total_docs) * 100
+            print(
+                f"[{i}/{total_docs}] ({progress:.1f}%) "
+                f"Processing: {os.path.basename(file)}"
+            )
+
+            text = bu.load_md(file)
+            if not text.strip():
+                continue
+
+            doc_id = os.path.splitext(os.path.basename(file))[0]
+            frontmatter = bu.extract_frontmatter(text)
+            doc_title = frontmatter.get("title") or bu.extract_title_from_md(text, default=doc_id)
+            doc_authors = frontmatter.get("authors") if isinstance(frontmatter.get("authors"), list) else []
+            doc_pub_year = frontmatter.get("publication_year")
+            doc_pub_date = frontmatter.get("publication_date")
+            doc_topic = _normalize_frontmatter_topic(frontmatter.get("topic"))
+            if doc_topic is None:
+                doc_topic = _infer_topic_from_text(text)
+
+            chunks = text_splitter.create_documents([text])
+            if not chunks:
+                continue
+
+            batch_texts = [c.page_content for c in chunks]
+
+            needs_prefix = "e5" in (model_name or "").lower()
+            encode_texts = (
+                [f"passage: {t}" for t in batch_texts] if needs_prefix else batch_texts
+            )
+
+            batch_embs = retrieval_model.encode(
+                encode_texts,
+                convert_to_numpy=True,
+                normalize_embeddings=True
+            ).astype("float32")
+
+            if index is None:
+                dim = batch_embs.shape[1]
+                index = faiss.IndexFlatIP(dim)
+            else:
+                if batch_embs.shape[1] != dim:
+                    raise ValueError(
+                        f"Embedding dim mismatch: expected {dim}, got {batch_embs.shape[1]}"
+                    )
+
+            index.add(batch_embs)
+
+            for local_idx, content in enumerate(batch_texts):
+                meta_f.write(json.dumps({
+                    "idx": global_idx,
+                    "document_id": doc_id,
+                    "document_title": doc_title,
+                    "document_authors": doc_authors,
+                    "publication_year": doc_pub_year,
+                    "publication_date": doc_pub_date,
+                    "topic": doc_topic,
+                    "fragment_id": local_idx,
+                    "content": content
+                }, ensure_ascii=False) + "\n")
+                global_idx += 1
+
+    if index is None or index.ntotal == 0:
+        raise RuntimeError("FAISS index is empty after processing.")
+
+    faiss.write_index(index, index_path)
+
+    index_info = {
+        "model_name": model_name,
+        "embedding_dim": dim,
+        "splitter": splitter,
+        "chunk_size": chunk_size,
+        "chunk_overlap": chunk_overlap,
+        "num_vectors": index.ntotal,
+        "num_documents_total": len(indexed_docs) + total_docs,
+    }
+
+    with open(index_info_path, "w", encoding="utf-8") as f:
+        json.dump(index_info, f, indent=2)
+
+    # -----------------------------
+    # Done
+    # -----------------------------
+    print("\nFAISS index update complete")
+    print(f"   → New documents indexed : {total_docs}")
+    print(f"   → Total vectors         : {index.ntotal}")
+    print(f"   → Index path            : {index_path}")

utils/pdf_md.py

@@ -0,0 +1,116 @@
+import os
+import re
+from markitdown import MarkItDown
+
+
+def clean_markdown_wrap_none(text: str) -> str:
+    """
+    Joins all lines of each paragraph into a single line.
+    Preserves structure (headings, lists, code blocks).
+    """
+    lines = text.splitlines()
+    out = []
+    buf = ""
+
+    bullet = re.compile(r"^(\s*[-*+]\s+|\s*\d+\.\s+)")
+    heading = re.compile(r"^\s{0,3}#{1,6}\s")
+    codefence = re.compile(r"^\s*```")
+
+    in_code = False
+
+    def flush():
+        nonlocal buf
+        if buf.strip():
+            out.append(buf.strip())
+        buf = ""
+
+    for raw in lines:
+        line = raw.rstrip("\n")
+
+        if codefence.match(line):
+            in_code = not in_code
+            flush()
+            out.append(line)
+            continue
+
+        if in_code:
+            out.append(line)
+            continue
+
+        if line.strip() == "":
+            flush()
+            out.append("")
+            continue
+
+        if heading.match(line) or bullet.match(line):
+            flush()
+            out.append(line)
+            continue
+
+        if not buf:
+            buf = line.strip()
+            continue
+
+        # Remove hyphen when word is split
+        if buf.endswith('-') and line.strip() and line.strip()[0].isalpha():
+            buf = buf[:-1] + line.strip()
+        else:
+            buf = buf + " " + line.strip()
+
+    flush()
+    return "\n".join(out)
+
+
+def convert_document_to_markdown(
+    file_path: str,
+    output_path: str = None,
+    return_text: bool = True,
+):
+    """
+    Converts a single document (PDF/DOCX and other MarkItDown-supported types) to Markdown.
+
+    Parameters:
+        file_path (str): Path to input file
+        output_path (str, optional): Where to save the .md file
+        return_text (bool): If True, returns markdown text
+
+    Returns:
+        str | None: Markdown content (if return_text=True)
+    """
+    if not os.path.isfile(file_path):
+        raise FileNotFoundError(f"File not found: {file_path}")
+
+    md = MarkItDown()
+
+    try:
+        result = md.convert(file_path)
+        clean_text = clean_markdown_wrap_none(result.text_content)
+
+        # Save file if requested
+        if output_path:
+            os.makedirs(os.path.dirname(output_path), exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(clean_text)
+
+        if return_text:
+            return clean_text
+
+        return None
+
+    except Exception as e:
+        raise RuntimeError(f"Error converting file to Markdown: {e}")
+
+
+def convert_pdf_to_markdown(
+    pdf_path: str,
+    output_path: str = None,
+    return_text: bool = True,
+):
+    """
+    Backward-compatible wrapper for PDF conversion.
+    """
+    return convert_document_to_markdown(
+        file_path=pdf_path,
+        output_path=output_path,
+        return_text=return_text,
+    )

utils/retrieval_utils.py

@@ -0,0 +1,187 @@
+import torch
+import os
+import glob
+import json
+import pandas as pd
+from sentence_transformers import SentenceTransformer
+import numpy as np
+from langchain_text_splitters import RecursiveCharacterTextSplitter, CharacterTextSplitter
+from langchain_experimental.text_splitter import SemanticChunker
+from langchain_community.embeddings import HuggingFaceEmbeddings
+from . import base_utils as bu
+
+def load_model(model_name):
+    return SentenceTransformer(model_name, device="cpu")
+
+
+def _model_needs_e5_prefix(model_name: str) -> bool:
+    """Los modelos intfloat/e5-* requerem prefixos `query:` / `passage:`."""
+    return "e5" in (model_name or "").lower()
+
+def get_text_splitter(splitter, chunk_size, chunk_overlap):
+    """
+    Retrieve the appropriate text splitter based on a specified type.
+    """
+    if splitter == "recursive":
+        return RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            length_function=len,
+        )
+    elif splitter == "tokens":
+        return CharacterTextSplitter.from_tiktoken_encoder(
+            encoding_name="cl100k_base",
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+        )
+    elif splitter == "semantic":
+        embeddings_model = HuggingFaceEmbeddings(
+            model_name=bu.config["embeddings"]["model_name"])
+        return SemanticChunker(
+            embeddings=embeddings_model,
+        )
+    else:
+        return RecursiveCharacterTextSplitter(
+            chunk_size=chunk_size,
+            chunk_overlap=chunk_overlap,
+            length_function=len
+        )
+
+def generate_embeddings(input_path, output_folder, model_name, splitter, chunk_size, chunk_overlap, retrieval_model, export_numpy=False, numpy_output_dir=None, max_files=None):
+    text_splitter = get_text_splitter(splitter, chunk_size, chunk_overlap)
+    md_files = glob.glob(input_path)
+    if not md_files:
+        print(f"No .md files found in path: {input_path}")
+        return
+
+    os.makedirs(output_folder, exist_ok=True)
+
+    emb_files = glob.glob(os.path.join(output_folder, "*.h5"))
+    for file in emb_files:
+        filename_without_ext = os.path.splitext(os.path.basename(file))[0]
+        corresponding_doc = os.path.join(os.path.dirname(input_path), filename_without_ext + ".md")
+        if not os.path.exists(corresponding_doc):
+            print(f"Embeddings file {file} has no corresponding .md. Deleting it.")
+            os.remove(file)
+
+    all_embeddings = []
+    all_metadata = []
+    global_idx = 0
+
+    if max_files is not None:
+        md_files = md_files[:max_files]
+
+    total_files = len(md_files)
+    for i, file in enumerate(md_files, start=1):
+        file_name = os.path.basename(file)
+        doc_id = os.path.splitext(file_name)[0]
+        output_file = os.path.join(output_folder, f"{doc_id}.h5")
+
+        if os.path.exists(output_file):
+            print(f"Embeddings already exists for {file_name}. Skipping generation and loading existing file for export...")
+            embeddings_df = pd.read_hdf(output_file, key="df")
+        else:
+            progress = (i / total_files) * 100
+            print(f"[{i}/{total_files}] ({progress:.1f}%) Generating embeddings for: {file_name}")
+            text = bu.load_md(file)
+
+            embeddings_list = []
+            content_list = []
+
+            if text.strip():
+                chunks = text_splitter.create_documents([text])
+                print(f"Chunks generated for document {file_name} : {len(chunks)}")
+
+                needs_prefix = _model_needs_e5_prefix(model_name)
+                for chunk in chunks:
+                    chunk_text = chunk.page_content
+                    input_text = (
+                        f"passage: {chunk_text}" if needs_prefix else chunk_text
+                    )
+                    embedding = retrieval_model.encode(input_text)
+                    embeddings_list.append(embedding)
+                    content_list.append(chunk_text)
+
+                embeddings_df = pd.DataFrame(embeddings_list)
+                embeddings_df["segment_content"] = content_list
+                embeddings_df["model_name"] = model_name
+                embeddings_df["segment_content"] = embeddings_df["segment_content"].astype(str)
+                embeddings_df["model_name"] = embeddings_df["model_name"].astype(str)
+
+                embeddings_df.to_hdf(output_file, key="df", mode="w", format="table")
+            else:
+                embeddings_df = pd.DataFrame()
+
+        from . import base_utils as _bu_internal  # import local para evitar ciclos en tiempo de carga
+        doc_title = _bu_internal.extract_title_from_md(text if 'text' in locals() else bu.load_md(file), default=file_name)
+
+        if export_numpy and not embeddings_df.empty:
+            emb_values = embeddings_df.iloc[:, :-2].values.astype("float32")
+            contents = embeddings_df["segment_content"].tolist()
+
+            for local_idx, (vec, content) in enumerate(zip(emb_values, contents)):
+                all_embeddings.append(vec)
+                all_metadata.append(
+                    {
+                        "idx": global_idx,
+                        "document_id": doc_id,
+                        "document_title": doc_title,
+                        "fragment_id": local_idx,
+                        "content": content,
+                    }
+                )
+                global_idx += 1
+
+    if export_numpy and all_embeddings:
+        numpy_output_dir = numpy_output_dir or os.path.join("data", "embeddings")
+        os.makedirs(numpy_output_dir, exist_ok=True)
+
+        embeddings_array = np.vstack(all_embeddings).astype("float32")
+        np.save(os.path.join(numpy_output_dir, "embeddings.npy"), embeddings_array)
+
+        metadata_path = os.path.join(numpy_output_dir, "metadata.jsonl")
+        with open(metadata_path, "w", encoding="utf-8") as f:
+            for meta in all_metadata:
+                f.write(json.dumps(meta, ensure_ascii=False) + "\n")
+
+        print(f"Exported consolidated embeddings to {numpy_output_dir}")
+
+def search_query(query, corpus_embeddings, retrieval_model, segment_contents):
+
+    query_embedding = retrieval_model.encode(query, convert_to_tensor=True)
+    similarity_scores = retrieval_model.similarity(query_embedding, corpus_embeddings)[0]
+
+    top_similarities, topk_indices = torch.topk(similarity_scores, k=bu.config['retrieve']['top_k'])
+    top_segments = [segment_contents[idx] for idx in topk_indices]
+    
+    return top_segments, top_similarities
+
+def load_embeddings(embeddings_dir):
+    embeddings_list = []
+    segment_contents_list = []
+    model_names_set = set()
+
+    num_documents = 0
+    for file_path in glob.glob(os.path.join(embeddings_dir, "*.h5")):
+        num_documents += 1
+        embeddings_df = pd.read_hdf(file_path, key='df')
+        embeddings = embeddings_df.iloc[:, :-2].values
+        segment_contents = embeddings_df['segment_content'].values
+        model_name = embeddings_df['model_name'].values[0]
+
+        embeddings_list.extend(embeddings)
+        segment_contents_list.extend(segment_contents)
+        model_names_set.add(model_name)
+    
+    embeddings_array = np.array(embeddings_list)
+    embeddings_tensor = torch.tensor(embeddings_array, dtype=torch.float32, device='cuda' if torch.cuda.is_available() else 'cpu')
+
+    num_segment_contents = len(segment_contents_list)
+    model_name = model_names_set.pop() if len(model_names_set) == 1 else "Multiple Models"
+
+    return {
+        "embeddings": embeddings_tensor,
+        "segment_contents": segment_contents_list,
+        "num_documents": num_documents,
+        "num_segment_contents": num_segment_contents,
+    }

utils/retrievers.py

@@ -0,0 +1,229 @@
+import os
+import json
+from typing import List, Dict, Any
+
+import faiss
+import numpy as np
+#from elasticsearch import Elasticsearch
+
+from . import base_utils as bu
+
+
+class BaseRetriever:
+    """Interface base para mecanismos de recuperação.
+
+    A ideia é permitir trocar FAISS por Elasticsearch (ou outro backend)
+    sem mudar o restante da aplicação. Cada implementação deve expor um
+    método `retrieve` que recebe um vetor de consulta (1 x D) e devolve
+    uma lista de metadados de trechos no formato já usado pelo sistema.
+    """
+
+    def retrieve(self, query_embedding: np.ndarray, top_k: int) -> List[Dict[str, Any]]:
+        raise NotImplementedError
+
+
+def _load_index_and_metadata_from_config(config: dict):
+    """Carrega índice FAISS e metadata consolidada a partir da config.
+
+    Mantém a mesma lógica que antes existia em `app/api_server.py`, mas
+    centralizada aqui para poder ser reutilizada por diferentes backends.
+    """
+    index_path = config["index"].get("index_file", "data/index/faiss.index")
+    metadata_path = config["index"].get("metadata_file", "data/index/metadata.jsonl")
+
+    if not os.path.exists(index_path) or not os.path.exists(metadata_path):
+        raise FileNotFoundError(
+            "Index or metadata not found. Run scripts/build_index.py first."
+        )
+
+    index = faiss.read_index(index_path)
+
+    metadata: List[Dict[str, Any]] = []
+    with open(metadata_path, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                metadata.append(json.loads(line))
+
+    return index, metadata
+
+
+class FaissRetriever(BaseRetriever):
+    """Retriever baseado em índice FAISS local.
+
+    Usa `data/index/faiss.index` e `data/index/metadata.jsonl`, gerados
+    pelos scripts existentes (generate_embeddings + build_index).
+    """
+
+    def __init__(self, config: dict) -> None:
+        self.config = config
+        self.index, self.metadata = _load_index_and_metadata_from_config(config)
+
+        # Mapa de idx global -> metadado, para lookup rápido durante a busca
+        self._meta_by_idx: Dict[int, Dict[str, Any]] = {}
+        for m in self.metadata:
+            idx = m.get("idx")
+            if idx is not None:
+                # Usamos uma cópia simples; o chamador pode depois copiar novamente
+                self._meta_by_idx[int(idx)] = m
+
+    def retrieve(self, query_embedding: np.ndarray, top_k: int) -> List[Dict[str, Any]]:
+        """Busca vetorial usando FAISS e devolve metadados dos trechos."""
+        if query_embedding.ndim != 2:
+            raise ValueError("query_embedding must be a 2D array of shape (1, D)")
+
+        # Busca em FAISS (mesma lógica anterior)
+        scores, indices = self.index.search(query_embedding, top_k)
+        idxs = indices[0].tolist()
+        score_values = scores[0].tolist()
+
+        retrieved: List[Dict[str, Any]] = []
+        for rank, i in enumerate(idxs):
+            m = self._meta_by_idx.get(int(i))
+            if m is not None:
+                item = dict(m)  # copiar para não vazar referência mutável
+                # Expõe score do FAISS para depuração/ranking no backend e scripts.
+                if rank < len(score_values):
+                    item["score"] = float(score_values[rank])
+                # Garantir chaves esperadas para referências
+                item.setdefault("document_authors", [])
+                item.setdefault("publication_year", None)
+                item.setdefault("publication_date", None)
+                retrieved.append(item)
+        return retrieved
+
+    def list_documents(self) -> List[Dict[str, str]]:
+        """Lista documentos únicos (id + título) com base na metadata carregada."""
+        docs: Dict[str, str] = {}
+        for m in self.metadata:
+            doc_id = m.get("document_id")
+            if not doc_id:
+                continue
+            titulo = m.get("document_title") or doc_id
+            if doc_id not in docs:
+                docs[doc_id] = titulo
+
+        documentos_ordenados = [
+            {"id": doc_id, "title": docs[doc_id]}
+            for doc_id in sorted(docs, key=lambda d: docs[d].lower())
+        ]
+        return documentos_ordenados
+
+
+def get_retriever(config: dict) -> BaseRetriever:
+    """
+    Fábrica simples para escolher o backend de recuperação.
+    """
+    index_type = config.get("index", {}).get("type", "faiss").lower()
+
+    if index_type == "faiss":
+        return FaissRetriever(config)
+
+    if index_type == "elasticsearch":
+        return ElasticRetriever(config)
+
+    # Placeholder para futuras implementações.
+    raise ValueError(f"Index backend '{index_type}' not supported. Use 'faiss' or 'elasticsearch'.")
+
+
+class ElasticRetriever(BaseRetriever):
+    """
+    Retriever baseado em Elasticsearch (vector search).
+    """
+
+    def __init__(self, config: dict) -> None:
+        self.config = config
+        idx_cfg = config.get("index", {})
+
+        self.host = idx_cfg.get("host", "http://localhost:9200")
+        self.index_name = idx_cfg.get("index_name", "chatbot-norm")
+        self.vector_field = idx_cfg.get("vector_field", "embedding")
+        self.api_key = idx_cfg.get("api_key") or os.getenv("ELASTIC_API_KEY")
+        self.username = idx_cfg.get("username")
+        self.password = idx_cfg.get("password")
+
+        # Cliente Elasticsearch (prioriza API key, depois basic_auth, depois sem auth)
+        if self.api_key:
+            self.client = Elasticsearch(self.host, api_key=self.api_key)
+        elif self.username and self.password:
+            self.client = Elasticsearch(self.host, basic_auth=(self.username, self.password))
+        else:
+            self.client = Elasticsearch(self.host)
+
+    def retrieve(self, query_embedding: np.ndarray, top_k: int) -> List[Dict[str, Any]]:
+        """Executa busca vetorial k-NN em Elasticsearch."""
+        if query_embedding.ndim != 2:
+            raise ValueError("query_embedding must be a 2D array of shape (1, D)")
+
+        query_vec = query_embedding[0].astype(float).tolist()
+        num_candidates = max(top_k * 5, top_k)
+
+        knn_body = {
+            "field": self.vector_field,
+            "query_vector": query_vec,
+            "k": top_k,
+            "num_candidates": num_candidates,
+        }
+
+        resp = self.client.search(
+            index=self.index_name,
+            knn=knn_body,
+            size=top_k,
+            _source=[
+                "idx",
+                "document_id",
+                "document_title",
+                "document_authors",
+                "publication_year",
+                "publication_date",
+                "fragment_id",
+                "content",
+            ],
+        )
+
+        hits = resp.get("hits", {}).get("hits", [])
+        retrieved: List[Dict[str, Any]] = []
+        for h in hits:
+            src = h.get("_source", {})
+            retrieved.append(
+                {
+                    "idx": src.get("idx"),
+                    "document_id": src.get("document_id"),
+                    "document_title": src.get("document_title"),
+                    "document_authors": src.get("document_authors"),
+                    "publication_year": src.get("publication_year"),
+                    "publication_date": src.get("publication_date"),
+                    "fragment_id": src.get("fragment_id"),
+                    "content": src.get("content"),
+                }
+            )
+        return retrieved
+
+    def list_documents(self) -> List[Dict[str, str]]:
+        """Lista documentos únicos (id + título) a partir do índice ES.
+
+        Implementação simples via `match_all` limitada a 10k documentos.
+        Para bases muito maiores, seria melhor usar scroll / search_after.
+        """
+        docs: Dict[str, str] = {}
+
+        resp = self.client.search(
+            index=self.index_name,
+            query={"match_all": {}},
+            size=10000,
+            _source=["document_id", "document_title"],
+        )
+
+        for h in resp.get("hits", {}).get("hits", []):
+            src = h.get("_source", {})
+            doc_id = src.get("document_id")
+            if not doc_id:
+                continue
+            titulo = src.get("document_title") or doc_id
+            if doc_id not in docs:
+                docs[doc_id] = titulo
+
+        documentos_ordenados = [
+            {"id": doc_id, "title": docs[doc_id]}
+            for doc_id in sorted(docs, key=lambda d: docs[d].lower())
+        ]
+        return documentos_ordenados