> For the complete documentation index, see [llms.txt](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/empezando-con-taina/base-conocimiento.md). # Base de conocimiento Taína utiliza un sistema de Generación Aumentada por Recuperación (RAG) para responder preguntas sobre servicios gubernamentales con datos confiables. Esta sección explica cómo funciona la base de conocimiento, de dónde provienen los datos y cómo poblarla. ## Cómo funciona La base de conocimiento sigue este flujo: ``` API del Catálogo → Pipeline → ChromaDB → Agente Taína (catalogo.digital (preprocessing/) (storage/chroma/) (responde al .gob.do) → *_rag_documents → embeddings ciudadano) .json ``` 1. **Fuente de datos**: La API del Catálogo de Servicios del Estado Dominicano, gestionada por la OGTIC 2. **Preprocessing**: Scripts que descargan, limpian y estructuran los datos de cada servicio en formato JSON 3. **Ingesta**: El módulo `src/ingest.py` lee los archivos JSON, genera embeddings con Google Gemini y los almacena en ChromaDB 4. **Búsqueda semántica**: Cuando un ciudadano hace una pregunta, Taína busca en ChromaDB los documentos más relevantes y los usa como contexto para responder *** ## Fuentes oficiales de datos > **Referencia obligatoria**: Los datos que alimentan a Taína provienen del Catálogo de Servicios del Estado Dominicano, administrado por la OGTIC. Los técnicos deben familiarizarse con estos portales antes de trabajar con el pipeline de datos. | Recurso | URL | Descripción | | ----------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | **Portal de Documentación** | [docs.digital.gob.do](https://docs.digital.gob.do/) | Documentación general de las plataformas digitales del Estado | | **Catálogo de Servicios** | [Catálogo](https://docs.digital.gob.do/shelves/catalogo-de-servicios-del-estado-dominicano) | Estante con la documentación del catálogo de servicios | | **Manual de Integración API** | [Manual API](https://docs.digital.gob.do/books/manual-de-integracion-api) | Endpoints, autenticación y estructura de datos de la API | *** ## Estructura de los archivos de datos ### Directorio `data/chunks/` El catálogo de servicios se carga desde archivos JSON ubicados en `data/chunks/`. El sistema busca automáticamente archivos que sigan el patrón: ``` data/chunks/ ├── 120_rag_documents.json ├── 163_rag_documents.json ├── 245_rag_documents.json └── ... ``` > **Patrón de nombre**: `{service_id}_rag_documents.json` > > El sistema escanea la carpeta `data/chunks/` buscando todos los archivos que coincidan con `*_rag_documents.json`. Este es el mecanismo que usa el catálogo de servicios (ver `src/qa/catalog.py`). ### Estructura interna de cada archivo Cada archivo `*_rag_documents.json` es un array JSON donde cada elemento representa un **chunk** (fragmento de información) con un tipo específico: ```json [ { "id": "servicio_principal_163", "content": "Servicio: Renovación de Licencia de Conducir\nInstitución: INTRANT\n...", "metadata": { "service_id": "163", "tipo": "servicio_principal", "nombre_servicio": "Renovación de Licencia de Conducir", "institucion": "INTRANT" } }, { "id": "variacion_163_0", "content": "Variación: Categoría 01\nPrecio: RD$ 1,900...", "metadata": { "service_id": "163", "tipo": "variacion_servicio", "categoria": "Categoría 01", "precio": 1900.0, "moneda": "RD$" } } ] ``` ### Los 5 tipos de chunks Cada servicio se descompone en hasta 5 tipos de chunks para optimizar la búsqueda: | Tipo | Contenido | | -------------------- | ----------------------------------------------------------- | | `servicio_principal` | Nombre, institución, descripción, objetivo, canales | | `variacion_servicio` | Procedimiento, requisitos, documentos, precio por variación | | `ubicaciones` | Oficinas, direcciones, horarios | | `canal_digital` | Enlace al portal web para trámite en línea | | `contacto` | Teléfonos, correos, portal institucional | > Si un servicio no tiene información para algún tipo, el sistema genera automáticamente un **placeholder** que indica al ciudadano que contacte la institución directamente. *** ## Cómo poblar la base de conocimiento El script `setup_databases.sh` automatiza todo el proceso de descarga, procesamiento e ingesta. Hay dos formas de usarlo: *** ### Opción A: Ingesta automática desde la API oficial (Recomendado) Este script se conecta a la API del Catálogo de Servicios del Estado Dominicano, descarga todos los servicios, crea los bloques RAG optimizados y construye toda la inteligencia estructurada de Taína: ```bash cd backend/ ./setup_databases.sh --env produccion --build-qa ``` **¿Qué hace internamente?** 1. Lee las credenciales `API_USERNAME` y `API_PASSWORD` del `.env` 2. Obtiene un token JWT usando `scripts/auth_get_token.sh` 3. Descarga cada servicio listado en `data/service_ids.txt` 4. Limpia el HTML y genera archivos `*_rag_documents.json` en `data/chunks/` 5. Ejecuta la ingesta vectorial en `storage/chroma/` (colección `servicios`) 6. Con `--build-qa`, genera pares pregunta-respuesta y construye `storage/chroma_qa/` > **Requisitos previos:** Las credenciales de la API (`API_USERNAME`, `API_PASSWORD`) deben estar configuradas en tu `backend/.env`. Serán proporcionadas por la OGTIC de forma privada. **Opciones disponibles:** | Flag | Descripción | | -------------------------- | ----------------------------------------------------------------- | | `--env staging` | Usa la API del entorno de pruebas | | `--env produccion` | Usa la API de producción | | `--build-qa` | Genera la colección QA complementaria | | `--services "163 245 707"` | Procesa solo los IDs indicados (en vez de leer `service_ids.txt`) | *** ### Opción B: Ingesta manual / Offline Si no tienes acceso a la API o quieres usar datos preprocesados: ```bash # 1. Coloca tus archivos en: backend/data/chunks/ # IMPORTANTE: Los archivos JSON DEBEN tener el sufijo *_rag_documents.json # Ejemplo: 163_rag_documents.json # 2. Ejecuta la ingesta local cd backend/ ./setup_databases.sh --json-dir data/chunks --build-qa ``` > Sin `--env`, el script no intentará conectarse a la API. Solo procesará los archivos ya existentes en `data/chunks/`. *** Al finalizar exitosamente verás: ``` ==> Setup completado Bases: storage/chroma (servicios), storage/chroma_qa (servicios_qa) ``` Para instrucciones detalladas de verificación, consulta el [Paso 6 de la guía de instalación](https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/empezando-con-taina/pages/zx18dcD88YDNHOVSWz6Q#paso-6--verificar-la-instalación). *** ## Referencia de la API del Catálogo La API del Catálogo de Servicios se documenta en el [Manual de Integración](https://docs.digital.gob.do/books/manual-de-integracion-api) publicado por la OGTIC. Este manual describe: * **Endpoints disponibles**: Estructura de URLs para consultar servicios, instituciones, variaciones, etc. * **Autenticación**: Flujo de login basado en JWT (JSON Web Token) * **Estructura de datos**: Campos de cada servicio y sus relaciones Las credenciales de acceso se configuran en el archivo `.env`: ```ini # En backend/.env API_USERNAME=YOUR_API_USERNAME_HERE API_PASSWORD=YOUR_API_PASSWORD_HERE ``` > Estas credenciales serán proporcionadas por la OGTIC de forma privada. Solicítelas al equipo técnico. El script `setup_databases.sh` gestiona la autenticación automáticamente usando `scripts/auth_get_token.sh`, que soporta dos entornos: | Entorno | URL base | Uso | | ------------ | ------------------------------------- | -------------------- | | `staging` | `https://catalogo-staging-*.run.app` | Desarrollo y pruebas | | `produccion` | `https://app.catalogo.digital.gob.do` | Producción | ### Archivos del pipeline (referencia) | Archivo | Ubicación | Propósito | | -------------------- | ---------------- | ------------------------------------------------------------ | | `setup_databases.sh` | `backend/` | **Orquestador principal** — automatiza todo el flujo | | `auth_get_token.sh` | `scripts/` | Obtiene token JWT desde la API del catálogo | | `fetch_service.sh` | `preprocessing/` | Descarga un servicio de la API y transforma campos a español | | `process_service.py` | `preprocessing/` | Limpia HTML, estructura chunks RAG y genera documentos | | `run_pipeline.sh` | `preprocessing/` | Descarga + procesamiento para un servicio | | `batch_process.sh` | `preprocessing/` | Pipeline para múltiples servicios en lote | | `service_ids.txt` | `data/` | Lista de IDs de servicios a descargar | ### Archivos generados por servicio Para el servicio `163`, el pipeline genera: ``` 163.json # JSON original descargado de la API 163_clean.json # JSON con HTML limpio 163_rag_documents.json # Documentos preparados para ChromaDB (este es el que usa Taína) 163_summary.json # Resumen del procesamiento ``` *** ## Generación de índice QA (opcional) Complementa la base de conocimiento principal con pares pregunta-respuesta para mejorar la cobertura conversacional: ```bash # Generar QA desde los chunks docker compose exec taina-backend python -m src.qa.generator \ --input_dir data/chunks \ --output_dir data/QA # Construir el índice QA en ChromaDB docker compose exec taina-backend python -m src.qa.build_qa_index \ --qa_dir data/QA \ --persist_path storage/chroma_qa \ --collection_name servicios_qa \ --reset ``` *** ## Archivos resultantes | Directorio | Contenido | | ----------------------- | ------------------------------------------ | | `data/chunks/` | Archivos `*_rag_documents.json` (entrada) | | `data/QA/` | Pares pregunta-respuesta generados | | `storage/chroma/` | Colección principal ChromaDB (`servicios`) | | `storage/chroma_qa/` | Colección QA ChromaDB (`servicios_qa`) | | `data/QA/manifest.json` | Resumen de la generación de QA | > Los documentos con `metadata.placeholder = true` indican que esa sección carece de información real y el agente comunicará al ciudadano que contacte la institución directamente. *** ## Módulos del backend involucrados El proceso de ingesta y búsqueda utiliza los siguientes módulos del código fuente en `backend/src/`: | Módulo | Descripción | | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------- | | `src/ingest.py` | Pipeline principal de ingesta: lee archivos JSON de `data/chunks/`, genera embeddings y los almacena en ChromaDB | | `src/qa/catalog.py` | Escanea `data/chunks/` buscando archivos `*_rag_documents.json` y construye el catálogo de servicios | | `src/qa/generator.py` | Genera pares pregunta-respuesta a partir de los chunks para la colección QA | | `src/qa/build_qa_index.py` | Construye la colección QA en ChromaDB (`servicios_qa`) | | `src/vectors/chroma_vector.py` | Cliente de ChromaDB: gestión de colecciones, retrievers y búsqueda semántica | | `src/embeddings/gemini_embedding.py` | Genera embeddings con Google Gemini (modelo `text-embedding-004`) | | `src/utils/doc_loader.py` | Carga y estructura documentos JSON, valida metadata y genera placeholders | *** ## Verificar la base de conocimiento ```bash # Verificar colección principal docker compose exec taina-backend python3 -c " import chromadb client = chromadb.PersistentClient(path='storage/chroma') collection = client.get_collection('servicios') print(f'✅ Colección servicios: {collection.count()} documentos') " # Verificar colección QA (si la generaste) docker compose exec taina-backend python3 -c " import chromadb client = chromadb.PersistentClient(path='storage/chroma_qa') collection = client.get_collection('servicios_qa') print(f'✅ Colección servicios_qa: {collection.count()} documentos') " ``` *** ## Próximo paso Con la base de conocimiento lista, continúa con la [guía de instalación paso a paso](/taina-agente-ia-ogtic/empezando-con-taina/installation.md) para levantar Taína con Docker. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://public-intelligence.gitbook.io/taina-agente-ia-ogtic/empezando-con-taina/base-conocimiento.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.