> 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/arquitectura-y-conceptos/estructura-proyecto/catalogo-servicios.md).

# Catálogo de servicios

El catálogo de servicios permite al agente responder preguntas sobre trámites gubernamentales. Se apoya en los documentos RAG generados por el pipeline y en un conjunto de herramientas asincrónicas definidas en `src/tools.py`.

## Tipos de documentos

Cada servicio se modela con los siguientes tipos:

* `servicio_principal`: Información general y descripción.
* `variacion_servicio`: Procedimientos específicos, costos y requisitos por categoría.
* `ubicaciones`: Oficinas físicas, horarios y teléfonos.
* `canal_digital`: Pasos e URLs para trámites en línea.
* `contacto`: Números, correos y enlaces institucionales.
* `placeholder`: Mensaje controlado cuando faltan datos oficiales.

Estos documentos se identifican por `metadata.service_id` y `metadata.tipo`, lo que facilita filtrados específicos desde las herramientas.

## Herramientas disponibles

Las siguientes funciones se exponen al LLM para recuperar información estructurada (ver detalles en `referencias/herramientas.md`):

1. `list_services`: Busca servicios por nombre, institución o palabra clave.
2. `get_service_overview`: Devuelve descripción y canales principales.
3. `list_service_variations`: Lista variaciones con requisitos y costos.
4. `get_service_locations`: Entrega ubicaciones, horarios y contacto físico.
5. `get_service_digital_channel`: Retorna pasos y enlaces digitales.
6. `get_service_contact`: Devuelve correos y teléfonos oficiales.
7. `ask_knowledge_base`: Realiza búsqueda semántica en los chunks RAG.
8. `get_current_date`: Exposición controlada de la fecha actual para validar vigencias.

## Mejoras de calidad

* **Normalización de datos**: Los scripts del pipeline limpian HTML, homogenizan listas y generan variaciones legibles por voz.
* **Placeholders controlados**: Permiten informar al ciudadano cuando falta información real y sugieren contactar al \*462 o visitar `gob.do`.
* **QA etiquetada**: Complementa la base principal con ejemplos conversacionales que el agente puede citar directamente.
* **Validación de metadata**: Cada chunk exige `service_id`, `nombre_servicio`, `tipo` e `institucion` para facilitar reconstrucciones y auditorías.

## Configuración interna

```python
_RETRIEVER_CONFIG = {
    "chunks": {
        "directory": Path("storage/chroma"),
        "collection": "servicios",
        "retriever_k": 3,
    },
    "qa": {
        "directory": Path("storage/chroma_qa"),
        "collection": "servicios_qa",
        "retriever_k": 3,
    },
}

MAX_SEARCH_RESULTS = 10
SEARCH_TIMEOUT = 10
```

Ajusta estas variables cuando cambies el tamaño de los índices o necesites ampliar la recuperación.

## Manejo de errores

```python
ERROR_RESPONSES = {
    "knowledge_base_unavailable": (
        "Lo siento, temporalmente no puedo acceder a la base de conocimientos. "
        "Para obtener información actualizada sobre servicios gubernamentales, "
        "puedes contactar al asterisco 4 6 2 o visitar www.gob.do"
    ),
    "no_results_found": (
        "No encontré información específica sobre tu consulta. "
        "Te recomiendo contactar a la institución o llamar al asterisco 4 6 2."
    ),
    "search_error": (
        "Hubo un inconveniente técnico al buscar la información. "
        "Intenta reformular tu pregunta o contacta al asterisco 4 6 2."
    ),
}
```

Los placeholders (`metadata.placeholder = true`) también devuelven mensajes específicos para guiar al ciudadano.

## Sanitización para TTS

```python
def sanitize_text_for_tts(text: str) -> str:
    sanitized = text.replace(\"**\", \"\")
    sanitized = sanitized.replace(\"*462\", \"asterisco 4 6 2\")
    sanitized = sanitized.replace(\"US$\", \"USD \")
    sanitized = re.sub(r\"RD\\$\\s*([\\d.,]+)\", lambda m: _format_currency(m.group(1), \"pesos dominicanos\"), sanitized)
    sanitized = sanitized.replace(\"08:00:00\", \"8 de la mañana\").replace(\"16:00:00\", \"4 de la tarde\")
    return sanitized.strip()
```

La sanitización asegura que la síntesis de voz pronuncie precios, horarios y siglas correctamente.

## Pruebas rápidas

```python
import asyncio
from src.tools import (
    list_services, get_service_overview, list_service_variations,
    get_service_locations, get_service_digital_channel,
    get_service_contact, ask_knowledge_base, get_current_date,
)

async def smoke_tests():
    print(await list_services(limit=3))
    print(await get_service_overview(\"163\"))
    print(await list_service_variations(\"163\"))
    print(await get_service_locations(\"163\")) 
    print(await get_service_digital_channel(\"163\"))
    print(await get_service_contact(\"163\"))
    kb = await ask_knowledge_base(\"licencia de conducir\") 
    print(kb[:200] + \"...\")
    print(await get_current_date())

asyncio.run(smoke_tests())
```

Mantén las herramientas sincronizadas con los cambios en los documentos. Si agregas un nuevo tipo de chunk o metadata asegúrate de actualizar `src/tools.py` y la documentación asociada.

> Consulta [Manejo de Errores y Recuperación](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/estructura-proyecto/manejo-errores.md) para entender los fallbacks implementados cuando las herramientas o retrievers presentan fallos.


---

# 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/arquitectura-y-conceptos/estructura-proyecto/catalogo-servicios.md?ask=<question>&goal=<endgoal>
```

`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.