> 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/configuracion-entorno.md).

# Variables de entorno y credenciales

Taína requiere credenciales de varios servicios en la nube para funcionar. Todas las variables se configuran en un archivo `.env` dentro de la carpeta `backend/`. Este archivo **nunca debe subirse a un repositorio** — ya está excluido en el `.gitignore`.

## Crear el archivo .env

```bash
# Desde la raíz del repositorio
cp backend/.env.example backend/.env
```

Abre `backend/.env` con tu editor preferido y completa los valores según las instrucciones a continuación.

***

## Credenciales de servicios de IA

Estas son las credenciales **obligatorias** para que Taína funcione. Sin ellas, el agente no puede arrancar.

### LiveKit – Comunicación en tiempo real

LiveKit gestiona las sesiones de audio/video WebRTC entre el ciudadano y Taína.

| Variable             | Descripción                                                      |
| -------------------- | ---------------------------------------------------------------- |
| `LIVEKIT_URL`        | URL WebSocket segura del servidor LiveKit (empieza con `wss://`) |
| `LIVEKIT_API_KEY`    | Identificador público del proyecto LiveKit                       |
| `LIVEKIT_API_SECRET` | Secreto privado para firmar tokens de acceso                     |

**Cómo obtenerlas:**

1. Crea una cuenta gratuita en [LiveKit Cloud](https://cloud.livekit.io/)
2. Crea un nuevo proyecto
3. Ve a **Settings** → **Keys**
4. Copia la URL, API Key y API Secret

```ini
LIVEKIT_URL=wss://tu-proyecto-xxxxx.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxx
LIVEKIT_API_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Google Gemini – Modelo de lenguaje

Google Gemini es el "cerebro" de Taína: interpreta las preguntas del ciudadano, razona sobre la base de conocimiento y genera las respuestas.

| Variable         | Descripción                               |
| ---------------- | ----------------------------------------- |
| `GOOGLE_API_KEY` | Clave de acceso a la API de Google Gemini |

**Cómo obtenerla:**

1. Ve a [Google AI Studio](https://aistudio.google.com/apikey)
2. Haz clic en **Create API Key**
3. Selecciona un proyecto de Google Cloud (o crea uno nuevo)
4. Copia la clave generada

```ini
GOOGLE_API_KEY=AIzaSyxxxxxxxxxxxxxxxxxxxxxxxxx
```

### Deepgram – Voz a texto (STT)

Deepgram convierte lo que el ciudadano dice por micrófono en texto escrito para que Gemini pueda procesarlo.

| Variable            | Descripción                                       |
| ------------------- | ------------------------------------------------- |
| `DEEPGRAM_API_KEY`  | Clave de acceso a la API de Deepgram              |
| `DEEPGRAM_LANGUAGE` | Idioma de reconocimiento (`es` para español)      |
| `DEEPGRAM_MODEL`    | Modelo de reconocimiento (`enhanced` recomendado) |

**Cómo obtenerla:**

1. Crea una cuenta en [Deepgram Console](https://console.deepgram.com/)
2. Ve a **API Keys** → **Create Key**
3. Copia la clave generada

```ini
DEEPGRAM_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
DEEPGRAM_LANGUAGE=es
DEEPGRAM_MODEL=enhanced
```

### ElevenLabs – Texto a voz (TTS)

ElevenLabs genera la voz de Taína: natural, cálida y en español dominicano.

| Variable              | Descripción                                    |
| --------------------- | ---------------------------------------------- |
| `ELEVEN_API_KEY`      | Clave de API de ElevenLabs                     |
| `ELEVENLABS_API_KEY`  | Misma clave (alias por compatibilidad interna) |
| `ELEVENLABS_VOICE_ID` | ID de la voz específica que usará Taína        |

**Cómo obtenerlas:**

1. Crea una cuenta en [ElevenLabs](https://elevenlabs.io/)
2. Ve a tu perfil → **API Keys** → copia la key
3. Para el Voice ID: ve a **Voices** → selecciona una voz (o clona una) → copia el ID desde el panel de configuración o la URL

```ini
ELEVEN_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELEVENLABS_API_KEY=sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
ELEVENLABS_VOICE_ID=xxxxxxxxxxxxxxxxxxxxxxxxx
```

> Ambas variables `ELEVEN_API_KEY` y `ELEVENLABS_API_KEY` deben contener el mismo valor. Existen por compatibilidad con distintas versiones del SDK.

### Cartesia – STT alternativo (opcional)

Cartesia es un proveedor alternativo de Speech-to-Text. La configuración activa por defecto usa Deepgram, pero Cartesia está disponible como fallback.

| Variable           | Descripción              |
| ------------------ | ------------------------ |
| `CARTESIA_API_KEY` | Clave de API de Cartesia |

**Cómo obtenerla:** Crea una cuenta en [Cartesia](https://play.cartesia.ai/) → API Keys.

***

## Google Cloud Storage (grabaciones)

Si se habilita la funcionalidad de grabación de sesiones (LiveKit Egress), Taína necesita un bucket de Google Cloud Storage donde almacenar los archivos.

| Variable                         | Descripción                                            |
| -------------------------------- | ------------------------------------------------------ |
| `GCP_BUCKET`                     | Nombre del bucket de GCS                               |
| `GCP_CREDENTIALS_PATH`           | Ruta al archivo JSON de credenciales (Service Account) |
| `GOOGLE_APPLICATION_CREDENTIALS` | Misma ruta (usada por el SDK de Google)                |

**Cómo configurar:**

1. En [Google Cloud Console](https://console.cloud.google.com/), crea un proyecto (o usa uno existente)
2. Ve a **IAM** → **Service Accounts** → **Create Service Account**
3. Asigna el rol **Storage Object Admin**
4. En la Service Account creada, ve a **Keys** → **Add Key** → **JSON**
5. Descarga el archivo JSON y guárdalo como `google_bucket_config.json` en `backend/`
6. Usa `google_bucket_config.json.example` como referencia del formato esperado

```ini
GCP_BUCKET=nombre-de-tu-bucket
GCP_CREDENTIALS_PATH=google_bucket_config.json
GOOGLE_APPLICATION_CREDENTIALS=google_bucket_config.json
```

***

## Perfil institucional

Estas variables personalizan las respuestas de Taína para la institución que la despliega.

| Variable               | Descripción                                                  |
| ---------------------- | ------------------------------------------------------------ |
| `ORGANIZATION_COUNTRY` | País de la institución (ej: República Dominicana)            |
| `ORGANIZATION_PHONE`   | Teléfono de contacto oficial (se usa en respuestas de error) |
| `ORGANIZATION_PORTAL`  | Portal web oficial de la institución                         |
| `ORGANIZATION_NAME`    | Nombre completo de la institución                            |
| `CURRENCY_NAME_RD`     | Nombre de la moneda local (ej: pesos dominicanos)            |
| `CURRENCY_NAME_US`     | Nombre del dólar estadounidense para respuestas de precios   |

***

## Credenciales de la API del Catálogo de Servicios

Estas credenciales permiten descargar los datos del **Catálogo de Servicios del Estado Dominicano** para alimentar la base de conocimiento de Taína.

> **Documentación oficial de la API (OGTIC):**
>
> * Portal general: [docs.digital.gob.do](https://docs.digital.gob.do/)
> * Catálogo de Servicios: [Estante del Catálogo](https://docs.digital.gob.do/shelves/catalogo-de-servicios-del-estado-dominicano)
> * Manual de Integración API: [Manual de Integración](https://docs.digital.gob.do/books/manual-de-integracion-api)

| Variable       | Descripción                                                |
| -------------- | ---------------------------------------------------------- |
| `API_USERNAME` | Email para autenticarse contra la API del Catálogo Digital |
| `API_PASSWORD` | Contraseña para la API del Catálogo Digital                |

**Credenciales** (proporcionadas por la OGTIC de forma privada):

```ini
API_USERNAME=YOUR_API_USERNAME_HERE
API_PASSWORD=YOUR_API_PASSWORD_HERE
```

El script `scripts/auth_get_token.sh` consume estas variables para obtener un token JWT y conectarse a los endpoints descritos en el [Manual de Integración API](https://docs.digital.gob.do/books/manual-de-integracion-api).

> Solicite las credenciales de acceso al equipo técnico de la OGTIC. Estas se entregarán de forma privada y no deben versionarse en el repositorio.

***

## Modelos de IA

| Variable          | Descripción                                                  | Valor por defecto           |
| ----------------- | ------------------------------------------------------------ | --------------------------- |
| `LLM_MODEL`       | Modelo de lenguaje de Google Gemini                          | `gemini-2.5-flash`          |
| `EMBEDDING_MODEL` | Modelo para vectorizar documentos de la base de conocimiento | `models/text-embedding-004` |

***

## Configuración operativa

Estas variables permiten ajustar el rendimiento y la estabilidad del agente. Los valores por defecto son adecuados para la mayoría de despliegues.

### Memoria y rendimiento

| Variable            | Descripción                                                            | Valor por defecto |
| ------------------- | ---------------------------------------------------------------------- | ----------------- |
| `MAX_MEMORY_MB`     | Límite de memoria por worker (MB). Si se excede, el worker se reinicia | `2500`            |
| `WARNING_MEMORY_MB` | Umbral de advertencia de memoria (MB)                                  | `1800`            |
| `WORKER_PROCESSES`  | Número de procesos idle listos para atender sesiones                   | `3`               |
| `LOAD_THRESHOLD`    | Umbral de carga (0.0-1.0). Si se supera, se rechazan nuevas sesiones   | `0.8`             |

### Timeouts (en segundos)

| Variable                | Descripción                                | Valor por defecto |
| ----------------------- | ------------------------------------------ | ----------------- |
| `STT_TIMEOUT`           | Espera máxima del servicio de voz a texto  | `30`              |
| `LLM_TIMEOUT`           | Espera máxima del modelo de lenguaje       | `45`              |
| `TTS_TIMEOUT`           | Espera máxima del servicio de texto a voz  | `20`              |
| `HEALTH_CHECK_INTERVAL` | Frecuencia de chequeos de salud (segundos) | `300`             |

### ChromaDB (base de datos vectorial)

| Variable                 | Descripción                                    | Valor por defecto   |
| ------------------------ | ---------------------------------------------- | ------------------- |
| `CHROMA_COLLECTION_NAME` | Nombre de la colección principal de documentos | `servicios`         |
| `CHROMA_DIRECTORY`       | Ruta de almacenamiento de la base vectorial    | `storage/chroma`    |
| `CHROMA_QA_COLLECTION`   | Nombre de la colección de preguntas-respuestas | `servicios_qa`      |
| `CHROMA_QA_DIRECTORY`    | Ruta de almacenamiento de la base QA           | `storage/chroma_qa` |
| `EMBEDDING_BATCH_SIZE`   | Documentos a vectorizar por lote               | `3`                 |
| `RETRIEVER_K`            | Número de documentos retornados por búsqueda   | `3`                 |
| `RETRIEVER_FETCH_K`      | Documentos candidatos antes del re-ranking     | `9`                 |

### Rate limiting

| Variable                  | Descripción                            | Valor por defecto |
| ------------------------- | -------------------------------------- | ----------------- |
| `MAX_REQUESTS_PER_MINUTE` | Solicitudes máximas por minuto         | `60`              |
| `MAX_CONCURRENT_SESSIONS` | Sesiones de voz simultáneas permitidas | `10`              |

### Logging

| Variable               | Descripción                                       | Valor por defecto |
| ---------------------- | ------------------------------------------------- | ----------------- |
| `LOG_LEVEL`            | Nivel mínimo de log (DEBUG, INFO, WARNING, ERROR) | `INFO`            |
| `LOG_ROTATION_SIZE_MB` | Tamaño máximo de un archivo de log antes de rotar | `100`             |
| `LOG_RETENTION_DAYS`   | Días de retención de archivos de log              | `30`              |

### Feature toggles

| Variable                     | Descripción                                              | Valor por defecto |
| ---------------------------- | -------------------------------------------------------- | ----------------- |
| `EGRESS_QUOTA_CHECK`         | Verificar cuota de grabaciones antes de iniciar          | `false`           |
| `MAX_CONCURRENT_EGRESS`      | Grabaciones simultáneas máximas                          | `2`               |
| `ENABLE_HEALTH_CHECKS`       | Activar chequeos de salud periódicos                     | `true`            |
| `ENABLE_PERFORMANCE_LOGGING` | Registrar métricas de rendimiento en logs                | `true`            |
| `ENABLE_AUTO_RECOVERY`       | Reintentar automáticamente cuando un componente falla    | `true`            |
| `MAX_RETRY_ATTEMPTS`         | Número máximo de reintentos por operación                | `3`               |
| `RETRY_BACKOFF_MULTIPLIER`   | Multiplicador exponencial entre reintentos (1s, 2s, 4s…) | `2.0`             |

***

## Resumen: checklist de credenciales

Antes de continuar, confirma que tu archivo `.env` contiene al menos estas variables con valores reales:

* [ ] `LIVEKIT_URL`, `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`
* [ ] `GOOGLE_API_KEY`
* [ ] `DEEPGRAM_API_KEY`
* [ ] `ELEVENLABS_API_KEY`, `ELEVENLABS_VOICE_ID`
* [ ] `ELEVEN_API_KEY` (mismo valor que `ELEVENLABS_API_KEY`)
* [ ] `CARTESIA_API_KEY`

## Próximo paso

Con el `.env` configurado, continúa con la [construcción de la base de conocimiento](/taina-agente-ia-ogtic/empezando-con-taina/base-conocimiento.md).


---

# 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/configuracion-entorno.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.