> 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/referencias-tecnicas/integrations/deepgram.md).

# Deepgram

Esta guía explica cómo Taína utiliza Deepgram para Speech-to-Text (STT) optimizado para español dominicano.

Deepgram es el servicio de Speech-to-Text que permite a Taína:

* **Reconocimiento de Voz**: Convertir audio a texto en tiempo real
* **Optimización para Español**: Modelos entrenados para español dominicano
* **Streaming**: Procesamiento en tiempo real de audio
* **Puntuación Automática**: Adición automática de signos de puntuación

## Configuración de Deepgram

### 1. Obtener API Key

#### Deepgram Console

```bash
# 1. Registrarse en Deepgram Console
# https://console.deepgram.com/

# 2. Crear nuevo proyecto
# 3. Generar API key
# 4. Copiar la clave generada

# 5. Configurar en .env
DEEPGRAM_API_KEY=your_deepgram_api_key
```

#### Verificar API Key

```bash
# Test de conectividad
curl -X POST "https://api.deepgram.com/v1/listen" \
     -H "Authorization: Token $DEEPGRAM_API_KEY" \
     -H "Content-Type: audio/wav" \
     --data-binary @test_audio.wav
```

### 2. Configuración en Taína

```python
# src/main.py - Configuración de STT con Deepgram
from livekit.plugins.deepgram import STT

# Configuración de STT
stt = STT.create(
    provider="deepgram",
    model="nova-2",                    # Modelo optimizado para español
    language="es",                     # Idioma español
    sample_rate=16000,                # Frecuencia de muestreo
    channels=1,                       # Mono
    interim_results=True,             # Resultados parciales
    punctuation=True,                 # Puntuación automática
    profanity_filter=False,           # Sin filtro de palabras
    redaction=False,                  # Sin redacción
    diarize=False,                    # Sin diarización
    multichannel=False,              # Sin multicanal
    alternatives=1,                  # Una alternativa
    numerals=True,                    # Reconocer números
    search=["licencia", "conducir", "gobierno"]  # Palabras clave
)
```

### 3. Variables de entorno

```ini
# Deepgram Configuration
DEEPGRAM_API_KEY=your_deepgram_api_key

# Opcional: Configuración avanzada
DEEPGRAM_MODEL=nova-2
DEEPGRAM_LANGUAGE=es
DEEPGRAM_SAMPLE_RATE=16000
DEEPGRAM_PUNCTUATION=true
DEEPGRAM_NUMERALS=true
```

## Configuración avanzada

### Modelos disponibles

```python
# Modelos de Deepgram disponibles
models = {
    "nova-2": {
        "description": "Modelo más reciente y preciso",
        "languages": ["es", "en", "fr", "de"],
        "features": ["punctuation", "numerals", "diarization"],
        "use_case": "Producción, alta precisión"
    },
    "nova": {
        "description": "Modelo estable y confiable",
        "languages": ["es", "en"],
        "features": ["punctuation", "numerals"],
        "use_case": "Desarrollo y validación interna"
    },
    "base": {
        "description": "Modelo básico",
        "languages": ["en"],
        "features": ["punctuation"],
        "use_case": "Prototipos y desarrollo temprano"
    }
}
```

### Configuración de audio

```python
# Configuración optimizada para español dominicano
stt_config = {
    "model": "nova-2",
    "language": "es",
    "sample_rate": 16000,
    "channels": 1,
    "encoding": "linear16",
    "punctuation": True,
    "numerals": True,
    "profanity_filter": False,
    "redaction": False,
    "diarize": False,
    "multichannel": False,
    "alternatives": 1,
    "interim_results": True,
    "endpointing": 300,  # 300ms de silencio para finalizar
    "vad_events": True,  # Eventos de detección de voz
    "search": [
        "licencia", "conducir", "gobierno", "servicio",
        "trámite", "documento", "cédula", "pasaporte"
    ]
}
```

## Integración con LiveKit

### Configuración del Agente

```python
# src/main.py - Integración con LiveKit Agent
async def entrypoint(ctx: JobContext):
    """Entrypoint principal con STT de Deepgram"""
    
    await ctx.wait_for_room()
    room = ctx.room
    
    # Configurar STT
    stt = STT.create(
        provider="deepgram",
        model="nova-2",
        language="es",
        sample_rate=16000,
        channels=1,
        interim_results=True,
        punctuation=True,
        numerals=True
    )
    
    # Configurar TTS
    tts = TTS.create(
        provider="elevenlabs",
        voice_id=os.getenv("ELEVENLABS_VOICE_ID")
    )
    
    # Crear agente
    agent = ProductionAssistant()
    
    # Iniciar con STT/TTS
    await agent.start(ctx, stt=stt, tts=tts)
```

### Manejo de Audio Stream

```python
# Manejo de stream de audio
class AudioStreamHandler:
    def __init__(self, stt):
        self.stt = stt
        self.buffer = []
        self.is_speaking = False
    
    async def on_audio_frame(self, frame):
        """Maneja frames de audio entrantes"""
        if frame.samples:
            # Agregar a buffer
            self.buffer.extend(frame.samples)
            
            # Procesar cuando hay suficiente audio
            if len(self.buffer) >= 1600:  # 100ms a 16kHz
                await self.process_audio_chunk()
    
    async def process_audio_chunk(self):
        """Procesa chunk de audio"""
        audio_data = bytes(self.buffer[:1600])
        self.buffer = self.buffer[1600:]
        
        try:
            # Enviar a Deepgram
            result = await self.stt.recognize(audio_data)
            
            if result.alternatives:
                text = result.alternatives[0].text
                confidence = result.alternatives[0].confidence
                
                if confidence > 0.7:  # Umbral de confianza
                    await self.handle_transcription(text)
                    
        except Exception as e:
            print(f"Error procesando audio: {e}")
```

## Optimización para español dominicano

### Palabras clave específicas

```python
# Palabras clave para servicios gubernamentales dominicanos
dominican_keywords = [
    # Servicios comunes
    "licencia", "conducir", "pasaporte", "cédula", "visa",
    "trámite", "documento", "certificado", "permiso",
    
    # Instituciones
    "intrant", "migración", "jce", "dgii", "ministerio",
    "gobierno", "estado", "público", "oficina",
    
    # Acciones
    "renovar", "solicitar", "obtener", "procesar",
    "pagar", "costo", "precio", "requisito",
    
    # Ubicaciones
    "santo domingo", "distrito nacional", "provincia",
    "oficina", "sede", "dirección", "ubicación"
]

# Configuración con palabras clave
stt = STT.create(
    provider="deepgram",
    model="nova-2",
    language="es",
    search=dominican_keywords,
    punctuation=True,
    numerals=True
)
```

### Configuración de acentos

```python
# Configuración específica para acento dominicano
accent_config = {
    "language": "es",
    "model": "nova-2",
    "punctuation": True,
    "numerals": True,
    "profanity_filter": False,
    "redaction": False,
    "diarize": False,
    "multichannel": False,
    "alternatives": 1,
    "interim_results": True,
    "endpointing": 300,
    "vad_events": True,
    "search": dominican_keywords,
    "smart_format": True,  # Formato inteligente
    "utterance_end_ms": 1000  # 1 segundo de silencio
}
```

## Manejo de errores

### Errores comunes

#### Error: "Invalid API key"

```bash
# Verificar API key
python3 -c "
import os
from dotenv import load_dotenv
load_dotenv()

api_key = os.getenv('DEEPGRAM_API_KEY')
if api_key:
    print(f'API Key: {api_key[:10]}...')
    print('Length:', len(api_key))
else:
    print('API Key not found')
"

# Test de conectividad
curl -X GET "https://api.deepgram.com/v1/projects" \
     -H "Authorization: Token $DEEPGRAM_API_KEY"
```

#### Error: "Audio format not supported"

```python
# Verificar formato de audio
audio_config = {
    "sample_rate": 16000,    # 16kHz
    "channels": 1,           # Mono
    "encoding": "linear16",  # PCM 16-bit
    "format": "wav"          # WAV format
}

# Convertir audio si es necesario
def convert_audio(input_file, output_file):
    import subprocess
    subprocess.run([
        "ffmpeg", "-i", input_file,
        "-ar", "16000",      # Sample rate
        "-ac", "1",          # Mono
        "-f", "wav",         # Format
        output_file
    ])
```

#### Error: "Rate limit exceeded"

```python
# Implementar rate limiting
import asyncio
from datetime import datetime, timedelta

class DeepgramRateLimiter:
    def __init__(self, max_requests=100, time_window=60):
        self.max_requests = max_requests
        self.time_window = time_window
        self.requests = []
    
    async def acquire(self):
        now = datetime.now()
        # Limpiar requests antiguos
        self.requests = [req for req in self.requests 
                        if now - req < timedelta(seconds=self.time_window)]
        
        if len(self.requests) >= self.max_requests:
            sleep_time = self.time_window - (now - self.requests[0]).seconds
            await asyncio.sleep(sleep_time)
        
        self.requests.append(now)
```

### Manejo de Timeouts

```python
# Configuración de timeouts
timeout_config = {
    "connection_timeout": 10,    # 10 segundos
    "request_timeout": 30,       # 30 segundos
    "audio_timeout": 5,          # 5 segundos de silencio
    "max_audio_length": 300      # 5 minutos máximo
}

# Implementar timeout
async def recognize_with_timeout(audio_data, timeout=30):
    try:
        result = await asyncio.wait_for(
            stt.recognize(audio_data),
            timeout=timeout
        )
        return result
    except asyncio.TimeoutError:
        print("STT timeout - audio too long")
        return None
```

## Validación operativa

### Verificación de conectividad

```python
# verify_deepgram_connection.py
import asyncio
import os
from livekit.plugins.deepgram import STT

async def validate_deepgram_connection():
    """Verifica conectividad básica con Deepgram"""
    try:
        stt = STT.create(
            provider="deepgram",
            model="nova-2",
            language="es",
            api_key=os.getenv("DEEPGRAM_API_KEY")
        )
        
        # Audio de ejemplo
        with open("sample_audio.wav", "rb") as f:
            audio_data = f.read()
        
        result = await stt.recognize(audio_data)
        
        if result.alternatives:
            print("✅ Deepgram conectado exitosamente")
            print(f"Transcripción: {result.alternatives[0].text}")
            print(f"Confianza: {result.alternatives[0].confidence}")
        else:
            print("❌ No se pudo transcribir audio")
            
    except Exception as e:
        print(f"❌ Error conectando con Deepgram: {e}")

asyncio.run(validate_deepgram_connection())
```

### Verificación de precisión

```python
# verify_accuracy.py
import asyncio
from livekit.plugins.deepgram import STT

async def validate_accuracy():
    """Valida la precisión con frases frecuentes"""
    sample_phrases = [
        "Hola, necesito renovar mi licencia de conducir",
        "¿Cuánto cuesta el trámite de pasaporte?",
        "¿Dónde puedo hacer el trámite de cédula?",
        "Necesito información sobre servicios de INTRANT"
    ]
    
    stt = STT.create(
        provider="deepgram",
        model="nova-2",
        language="es"
    )
    
    for phrase in sample_phrases:
        # Simular audio (en producción sería audio real)
        result = await stt.recognize(phrase.encode())
        
        if result.alternatives:
            transcribed = result.alternatives[0].text
            confidence = result.alternatives[0].confidence
            
            print(f"Original: {phrase}")
            print(f"Transcrito: {transcribed}")
            print(f"Confianza: {confidence:.2f}")
            print(f"Precisión: {'✅' if confidence > 0.8 else '❌'}")
            print("---")


asyncio.run(validate_accuracy())
```

## Monitoreo y métricas

### Métricas de STT

```python
# src/utils/stt_metrics.py
class DeepgramMetrics:
    def __init__(self):
        self.request_count = 0
        self.total_audio_duration = 0
        self.successful_transcriptions = 0
        self.failed_transcriptions = 0
        self.average_confidence = 0
        self.response_times = []
    
    def record_transcription(self, duration, confidence, response_time, success=True):
        self.request_count += 1
        self.total_audio_duration += duration
        self.response_times.append(response_time)
        
        if success:
            self.successful_transcriptions += 1
            self.average_confidence = (
                (self.average_confidence * (self.successful_transcriptions - 1) + confidence) 
                / self.successful_transcriptions
            )
        else:
            self.failed_transcriptions += 1
    
    def get_stats(self):
        return {
            "total_requests": self.request_count,
            "success_rate": self.successful_transcriptions / max(self.request_count, 1),
            "average_confidence": self.average_confidence,
            "total_audio_duration": self.total_audio_duration,
            "avg_response_time": sum(self.response_times) / len(self.response_times)
        }
```

### Health Check

```python
# src/tools.py - Health check para Deepgram
@function_tool()
async def health_check() -> str:
    """Verifica el estado del sistema incluyendo Deepgram"""
    
    status = {
        "timestamp": datetime.now().isoformat(),
        "deepgram": "unknown",
        "knowledge_base": "unknown",
        "memory_usage": "unknown"
    }
    
    # Verificar Deepgram
    try:
        stt = STT.create(
            provider="deepgram",
            model="nova-2",
            language="es",
            api_key=os.getenv("DEEPGRAM_API_KEY")
        )
        
        # Test con audio de prueba
        test_audio = b"test"  # Audio mínimo
        result = await stt.recognize(test_audio)
        status["deepgram"] = "healthy"
        
    except Exception as e:
        status["deepgram"] = f"error: {str(e)}"
    
    return json.dumps(status)
```

## Configuración de producción

### Optimizaciones de rendimiento

```python
# Configuración optimizada para producción
production_config = {
    "model": "nova-2",
    "language": "es",
    "sample_rate": 16000,
    "channels": 1,
    "punctuation": True,
    "numerals": True,
    "interim_results": True,
    "endpointing": 300,
    "vad_events": True,
    "smart_format": True,
    "utterance_end_ms": 1000,
    "search": dominican_keywords,
    "profanity_filter": False,
    "redaction": False,
    "diarize": False,
    "multichannel": False,
    "alternatives": 1
}
```

### Configuración de red

```python
# Configuración de red para producción
network_config = {
    "connection_timeout": 10,
    "request_timeout": 30,
    "retry_attempts": 3,
    "retry_delay": 1,
    "max_concurrent_requests": 10,
    "keep_alive": True,
    "compression": True
}
```

## Recursos adicionales

* [Deepgram Documentation](https://developers.deepgram.com/)
* [Deepgram API Reference](https://developers.deepgram.com/reference)
* [LiveKit Deepgram Plugin](https://docs.livekit.io/agents/plugins/deepgram/)
* [Speech Recognition Best Practices](https://developers.deepgram.com/docs/best-practices)

## Próximos pasos

1. **Integración ElevenLabs**: [ElevenLabs Integration](/taina-agente-ia-ogtic/referencias-tecnicas/integrations/elevenlabs.md)
2. **Arquitectura de la Base de Conocimiento**: [Arquitectura de la base de conocimiento](/taina-agente-ia-ogtic/arquitectura-y-conceptos/architecture/knowledge-base.md)
3. **Referencia de Configuración**: [Referencia de Configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.md)
4. **Solución de Problemas**: [Solución de problemas](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/index/how-to/troubleshoot.md)

***

¿Necesitas ayuda? Consulta la [guía de solución de problemas](https://github.com/public-intelligence/taina_ogtic/blob/master/taina-gitbook-ogtic/taina-asistente-ia/index/how-to/troubleshoot.md) o la [documentación de configuración](/taina-agente-ia-ogtic/referencias-tecnicas/api/configuration.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/referencias-tecnicas/integrations/deepgram.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.