tzzr/system-docs
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
1b392803fdc033ed34ee09d466b0eead8599d7a3
system-docs/v4-archive/penny/docs/PENNY_ESPECIFICACION.md

1194 lines
48 KiB
Markdown
Raw Normal View History

Archive: System v4 - Estado al 2024-12-24
2025-12-24 17:28:34 +00:00
# PENNY — Asistente Personal de Voz
**Especificación Técnica v1.0**
**Componente del Sistema DECK**
---
## Índice
1. [Definición](#1-definición)
2. [Arquitectura](#2-arquitectura)
3. [Planos de Información](#3-planos-de-información)
4. [Estructura del Log](#4-estructura-del-log)
5. [Integración con GRACE](#5-integración-con-grace)
6. [Pipeline de Voz](#6-pipeline-de-voz)
7. [Modelos Autoalojados](#7-modelos-autoalojados)
8. [Conversación Natural por Turnos](#8-conversación-natural-por-turnos)
9. [Implementación de Referencia](#9-implementación-de-referencia)
---
## 1. Definición
### 1.1 ¿Qué es PENNY?
PENNY es el **asistente personal de voz** del sistema DECK. Proporciona una interfaz conversacional hablada 100% natural para interactuar con el ecosistema.
```
┌─────────────────────────────────────────────────────────────────────┐
│ PENNY │
│ │
│ • ES la voz del DECK │
│ • ES la interfaz hablada con el usuario │
│ • ES quien llama a GRACE cuando necesita datos │
│ • HABLA con el usuario (GRACE no puede) │
│ • REGISTRA todo en el log (planos de información) │
│ • MANTIENE contexto durante la sesión │
│ │
│ "PENNY habla, GRACE procesa, el Log recuerda." │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 1.2 Principios Fundamentales
| Principio | Descripción |
|-----------|-------------|
| **Privacidad radical** | Audio procesado 100% local en servidor autoalojado |
| **Conversación natural** | Turnos fluidos, interrupciones, latencia <2s |
| **Log como fuente de verdad** | Todo está en el log, incluyendo personalidad |
| **Planos separados** | Contextos cargables independientemente |
| **GRACE como backend** | PENNY pregunta, GRACE extrae, PENNY responde |
### 1.3 Rol en el Sistema
```
┌─────────────────────────────────────────────────────────────────────┐
│ DECK (Servidor Personal) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Usuario ◄────────────────────────────────────────────► PENNY │
│ (voz natural) │ (habla) │
│ │ │
│ ┌──────────────┼──────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ GRACE │ │ LOG │ │ VAULT │ │
│ │ (datos) │ │(planos) │ │(recados)│ │
│ └─────────┘ └─────────┘ └─────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 2. Arquitectura
### 2.1 Diagrama de Componentes
```
┌─────────────────────────────────────────────────────────────────────┐
│ PENNY VOICE ENGINE (Servidor Local) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ Silero │ │ Faster │ │ PENNY │ │ XTTS-v2 │ │
│ │ VAD │──▶ Whisper │──▶ CORE │──▶ /Kokoro │ │
│ │ │ │ │ │ │ │ │ │
│ │ Detecta │ │ Transcribe │ │ Orquesta │ │ Sintetiza │ │
│ │ voz │ │ audio │ │ todo │ │ respuesta │ │
│ └────────────┘ └────────────┘ └─────┬──────┘ └────────────┘ │
│ │ │
│ ┌───────────────────┼───────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PLANOS │ │ GRACE │ │ THE VAULT │ │
│ │ (Log) │ │ (Contrato │ │ (Recados) │ │
│ │ │ │ Común) │ │ │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
│
│ SOLO texto (nunca audio)
▼
┌─────────────────────────────┐
│ Claude API │
│ (Conversación inteligente) │
└─────────────────────────────┘
```
### 2.2 Flujo de Procesamiento
```
┌─────────────────────────────────────────────────────────────────────┐
│ FLUJO VOZ → VOZ │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. VAD DETECTA (Silero) │
│ └── Usuario empieza a hablar │
│ └── Usuario termina (silencio 700ms) │
│ │
│ 2. ASR TRANSCRIBE (Faster-Whisper) │
│ └── Audio → Texto │
│ └── ~200-400ms con GPU │
│ │
│ 3. PENNY CORE PROCESA │
│ ├── Cargar planos relevantes │
│ ├── ¿Necesita GRACE? → Llamar con Contrato Común │
│ ├── Construir prompt con contexto │
│ └── Enviar a Claude API (solo texto) │
│ │
│ 4. LLM RESPONDE (Claude) │
│ └── Streaming de tokens │
│ └── ~1-2s primera palabra │
│ │
│ 5. TTS SINTETIZA (XTTS-v2/Kokoro) │
│ └── Texto → Audio │
│ └── Streaming mientras llegan tokens │
│ │
│ 6. LOG REGISTRA │
│ └── Todo el intercambio → plano CONVERSACION │
│ │
│ LATENCIA TOTAL OBJETIVO: <2 segundos voice-to-voice │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 3. Planos de Información
### 3.1 Concepto
El Log de PENNY está organizado en **planos** (layers) que se cargan independientemente. Cada plano tiene un propósito específico y puede actualizarse sin afectar a los demás.
```
┌─────────────────────────────────────────────────────────────────────┐
│ PLANOS DE INFORMACIÓN │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 0: SISTEMA │ │
│ │ Instrucciones base, comportamiento fundamental │ │
│ │ INMUTABLE durante sesión │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 1: PERSONALIDAD │ │
│ │ Tono, estilo, nombre, voz │ │
│ │ CONFIGURABLE por usuario │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 2: CONTEXTO PERSONAL │ │
│ │ Información del usuario, preferencias, historial │ │
│ │ PERSISTENTE entre sesiones │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 3: CONTEXTO AMBIENTAL │ │
│ │ Fecha, hora, ubicación, estado del sistema │ │
│ │ DINÁMICO (actualiza cada sesión) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 4: DATASET │ │
│ │ Datos específicos de la tarea actual │ │
│ │ OPCIONAL (carga bajo demanda) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ PLANO 5: CONVERSACIÓN │ │
│ │ Historial de la sesión actual │ │
│ │ VOLÁTIL (se archiva al cerrar sesión) │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 3.2 Definición de Planos
#### PLANO 0: SISTEMA
```yaml
plano: SISTEMA
id: plano_0
persistencia: permanente
modificable: false
contenido:
version: "1.0"
nombre_asistente: "Penny"
capacidades:
- conversacion_natural
- gestion_recados
- consulta_datos_via_grace
- registro_habitos
limitaciones:
- no_modifica_datos_directamente
- no_ejecuta_acciones_externas
- no_accede_internet
reglas:
- respuestas_concisas_max_3_oraciones
- confirmar_antes_de_crear_recados
- nunca_inventar_datos
integraciones:
grace: true
vault: true
vision_builder: true
```
#### PLANO 1: PERSONALIDAD
```yaml
plano: PERSONALIDAD
id: plano_1
persistencia: permanente
modificable: true
contenido:
nombre: "Penny"
tono: "Cercano pero profesional"
estilo: "Directo, sin rodeos, eficiente"
tratamiento: "Tuteo natural"
humor: "Ligero cuando apropiado"
muletillas_evitar:
- "¡Claro que sí!"
- "¡Por supuesto!"
- "¡Genial!"
expresiones_permitidas:
- "Vale"
- "Entendido"
- "Listo"
voz_tts:
modelo: "xtts-v2"
speaker_wav: "/voces/penny_base.wav"
idioma: "es"
velocidad: 1.0
```
#### PLANO 2: CONTEXTO PERSONAL
```yaml
plano: CONTEXTO_PERSONAL
id: plano_2
persistencia: permanente
modificable: true
player_id: "uuid-usuario"
contenido:
nombre_usuario: "Carlos"
preferencias:
idioma: "es"
formato_hora: "24h"
formato_fecha: "dd/mm/yyyy"
recordar:
- "Prefiere respuestas cortas"
- "Trabaja en tecnología"
- "Tiene reuniones los lunes por la mañana"
no_recordar:
- datos_financieros_especificos
- conversaciones_marcadas_privadas
historial_reciente:
ultima_sesion: "2025-12-15T18:30:00Z"
temas_frecuentes:
- "proyectos"
- "recados"
- "calendario"
```
#### PLANO 3: CONTEXTO AMBIENTAL
```yaml
plano: CONTEXTO_AMBIENTAL
id: plano_3
persistencia: sesion
modificable: auto
contenido:
fecha: "2025-12-16"
hora: "10:30"
dia_semana: "martes"
timezone: "Europe/Madrid"
estado_sistema:
grace_disponible: true
vault_disponible: true
ultimo_backup: "2025-12-16T03:00:00Z"
recados_pendientes: 3
eventos_hoy:
- "14:00 - Llamada con cliente"
- "17:00 - Revisión semanal"
```
#### PLANO 4: DATASET
```yaml
plano: DATASET
id: plano_4
persistencia: sesion
modificable: false
carga: bajo_demanda
contenido:
tipo: "productos"
fuente: "/bloques/datasets/catalogo_2025.json"
registros: 1547
campos:
- nombre
- precio
- stock
- categoria
fecha_actualizacion: "2025-12-10"
```
#### PLANO 5: CONVERSACIÓN
```yaml
plano: CONVERSACION
id: plano_5
persistencia: sesion
modificable: append_only
contenido:
sesion_id: "uuid-sesion"
inicio: "2025-12-16T10:25:00Z"
turnos:
- turno: 1
rol: "usuario"
timestamp: "2025-12-16T10:25:15Z"
texto: "¿Qué tengo pendiente para hoy?"
audio_hash: "sha256..."
duracion_ms: 2100
- turno: 2
rol: "penny"
timestamp: "2025-12-16T10:25:17Z"
texto: "Tienes 3 recados pendientes y 2 eventos: llamada con cliente a las 14:00 y revisión semanal a las 17:00."
tokens_usados: 45
latencia_ms: 1850
grace_llamadas: 0
```
### 3.3 Planos Adicionales Sugeridos
| Plano | Propósito | Persistencia |
|-------|-----------|--------------|
| **MEMORIA_CORTA** | Últimas 5 sesiones resumidas | 7 días |
| **EXPERTISE** | Conocimiento específico de dominio | Permanente |
| **RESTRICCIONES** | Límites y reglas temporales | Configurable |
| **MODO** | Estado actual (trabajo/personal/descanso) | Sesión |
---
## 4. Estructura del Log
### 4.1 Tabla Principal: PENNY_LOG
```sql
CREATE TABLE penny_log (
-- Identificadores
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
sesion_id UUID NOT NULL,
turno_index INTEGER NOT NULL,
-- Timing
timestamp_inicio TIMESTAMPTZ NOT NULL,
timestamp_fin TIMESTAMPTZ,
-- Contenido
rol VARCHAR(10) NOT NULL CHECK (rol IN ('usuario', 'penny', 'sistema')),
texto TEXT NOT NULL,
texto_hash VARCHAR(64) NOT NULL,
-- Audio (solo para entrada de usuario)
audio_ref VARCHAR(255), -- hostinger://audio/sesion/turno.wav
audio_hash VARCHAR(64),
audio_duracion_ms INTEGER,
-- Métricas
latencia_total_ms INTEGER,
latencia_asr_ms INTEGER,
latencia_llm_ms INTEGER,
latencia_tts_ms INTEGER,
tokens_prompt INTEGER,
tokens_respuesta INTEGER,
-- Trazabilidad
trace_id UUID,
grace_llamadas JSONB DEFAULT '[]',
-- Planos cargados
planos_activos JSONB NOT NULL,
-- Calidad
interrumpido BOOLEAN DEFAULT false,
confidence_asr DECIMAL(4,3),
-- Índices
CONSTRAINT unique_sesion_turno UNIQUE (sesion_id, turno_index)
);
-- Índices
CREATE INDEX idx_penny_log_sesion ON penny_log(sesion_id);
CREATE INDEX idx_penny_log_timestamp ON penny_log(timestamp_inicio);
CREATE INDEX idx_penny_log_trace ON penny_log(trace_id);
```
### 4.2 Tabla: PENNY_PLANOS
```sql
CREATE TABLE penny_planos (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-- Identificación
plano_tipo VARCHAR(50) NOT NULL,
plano_version VARCHAR(20) NOT NULL,
player_id UUID, -- NULL para planos globales
-- Contenido
contenido JSONB NOT NULL,
contenido_hash VARCHAR(64) NOT NULL,
-- Metadata
fecha_creacion TIMESTAMPTZ DEFAULT NOW(),
fecha_modificacion TIMESTAMPTZ DEFAULT NOW(),
modificado_por VARCHAR(100),
-- Estado
activo BOOLEAN DEFAULT true,
CONSTRAINT unique_plano_version UNIQUE (plano_tipo, plano_version, player_id)
);
```
### 4.3 Tabla: PENNY_SESIONES
```sql
CREATE TABLE penny_sesiones (
id UUID PRIMARY KEY,
-- Usuario
player_id UUID NOT NULL,
-- Timing
inicio TIMESTAMPTZ NOT NULL,
fin TIMESTAMPTZ,
duracion_total_ms INTEGER,
-- Estadísticas
total_turnos INTEGER DEFAULT 0,
total_tokens_prompt INTEGER DEFAULT 0,
total_tokens_respuesta INTEGER DEFAULT 0,
-- Planos usados
planos_cargados JSONB NOT NULL,
-- Resumen
resumen TEXT, -- Generado al cerrar sesión
temas_detectados JSONB DEFAULT '[]',
-- Estado
estado VARCHAR(20) DEFAULT 'activa' CHECK (estado IN ('activa', 'cerrada', 'archivada'))
);
```
### 4.4 Ejemplo de Registro Completo
```json
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"sesion_id": "660e8400-e29b-41d4-a716-446655440001",
"turno_index": 3,
"timestamp_inicio": "2025-12-16T10:26:00.000Z",
"timestamp_fin": "2025-12-16T10:26:01.850Z",
"rol": "penny",
"texto": "La factura es de Telefónica por 45,90 euros con fecha del 10 de diciembre.",
"texto_hash": "sha256:a1b2c3...",
"latencia_total_ms": 1850,
"latencia_asr_ms": 0,
"latencia_llm_ms": 1200,
"latencia_tts_ms": 650,
"tokens_prompt": 1250,
"tokens_respuesta": 32,
"trace_id": "770e8400-e29b-41d4-a716-446655440002",
"grace_llamadas": [
{
"modulo": "FIELD_EXTRACTOR",
"trace_id": "880e8400-e29b-41d4-a716-446655440003",
"latencia_ms": 450,
"status": "SUCCESS"
}
],
"planos_activos": {
"plano_0": "v1.0",
"plano_1": "v1.2",
"plano_2": "v3.1",
"plano_3": "auto",
"plano_4": null,
"plano_5": "current"
},
"interrumpido": false,
"confidence_asr": null
}
```
---
## 5. Integración con GRACE
### 5.1 Principio Fundamental
```
┌─────────────────────────────────────────────────────────────────────┐
│ PENNY ↔ GRACE │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ PENNY puede HABLAR GRACE puede PROCESAR │
│ PENNY no puede PROCESAR DATOS GRACE no puede HABLAR │
│ │
│ Cuando PENNY necesita datos: │
│ 1. PENNY llama a GRACE usando Contrato Común │
│ 2. GRACE procesa y devuelve datos estructurados │
│ 3. PENNY formula respuesta hablada con los datos │
│ │
│ "PENNY es la voz, GRACE es el cerebro analítico" │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 5.2 Módulos de GRACE que PENNY Puede Invocar
| Módulo | Cuándo PENNY lo llama |
|--------|----------------------|
| `ASR` | Audio del usuario → Texto (interno, no directo) |
| `TTS` | Texto de respuesta → Audio (interno, no directo) |
| `FIELD_EXTRACTOR` | "¿Qué dice esta factura?" |
| `SUMMARIZER` | "Resume este documento" |
| `CLASSIFIER` | "¿De qué tipo es este email?" |
| `TASK_DETECTOR` | "¿Qué tareas hay en esta reunión?" |
| `LANG_NORMALIZER` | Detectar idioma de entrada |
### 5.3 Formato de Llamada PENNY → GRACE
```json
{
"contract_version": "1.2",
"profile": "FULL",
"envelope": {
"trace_id": "penny-trace-uuid",
"parent_trace_id": "sesion-uuid",
"step_id": "grace-call-uuid",
"step_index": 1,
"total_steps": 1,
"idempotency_key": "sha256-del-contenido",
"timestamp_init": "2025-12-16T10:26:00.000Z",
"ttl_ms": 10000
},
"routing": {
"module": "FIELD_EXTRACTOR",
"version": "1.0",
"provider_preference": ["local"],
"fallback_chain": ["FIELD_EXTRACTOR_LOCAL"],
"max_fallback_level": 1
},
"context": {
"lang": "es",
"mode": "strict",
"pii_filter": true,
"player_id": "uuid-usuario",
"caller": "PENNY",
"caller_sesion": "uuid-sesion-penny"
},
"payload": {
"type": "document",
"encoding": "url",
"content": "hostinger://uploads/factura_2025.pdf",
"content_hash": "sha256...",
"schema_expected": "extracted_invoice"
},
"storage": {
"input_location": "internal",
"output_location": "internal",
"persist_intermediate": false
},
"security": {
"encryption_profile": "E2E_BASIC",
"data_sensitivity": "MEDIUM",
"pii_detected": true
}
}
```
### 5.4 Flujo Completo de Ejemplo
```
Usuario: "¿Qué dice la factura que escaneé ayer?"
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 1: ASR (interno) │
│ Audio → "¿Qué dice la factura que escaneé ayer?" │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 2: PENNY detecta necesidad de GRACE │
│ Análisis: usuario pide contenido de documento → FIELD_EXTRACTOR │
│ Buscar: última factura escaneada del usuario │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 3: PENNY → GRACE (Contrato Común) │
│ Request: FIELD_EXTRACTOR + documento │
│ Response: { proveedor: "Telefónica", total: 45.90, fecha: "..." } │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 4: PENNY construye respuesta │
│ Prompt a Claude con datos de GRACE + contexto de planos │
│ Respuesta: "La factura es de Telefónica por 45,90€..." │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 5: TTS (interno) │
│ Texto → Audio │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ PASO 6: LOG │
│ Registrar turno completo + llamada a GRACE + métricas │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 6. Pipeline de Voz
### 6.1 Stack Autoalojado Recomendado
```yaml
# Configuración 100% local para máxima privacidad
pipeline:
vad:
modelo: silero-vad-v5
ubicacion: local
config:
threshold: 0.5
min_speech_duration_ms: 250
min_silence_duration_ms: 700 # Fin de turno
speech_pad_ms: 30
asr:
modelo: faster-whisper
variante: large-v3 # Máxima calidad
ubicacion: local
config:
compute_type: float16
device: cuda
language: es
beam_size: 5
vad_filter: true
fallback:
- variante: distil-large-v2 # Más rápido
- variante: medium # Mínimo aceptable
llm:
modelo: claude-sonnet-4
ubicacion: api # Único componente externo
config:
max_tokens: 150
temperature: 0.7
streaming: true
nota: "Solo texto, nunca audio. Zero Data Retention si enterprise."
tts:
modelo: xtts-v2
ubicacion: local
config:
speaker_wav: "/voces/penny_base.wav"
language: es
gpt_cond_len: 6
streaming: true
fallback:
- modelo: kokoro-82m # Más rápido, menor calidad
- modelo: piper # Emergencia
```
### 6.2 Requisitos de Hardware
```yaml
hardware_minimo:
gpu: RTX 3060 (12GB VRAM)
cpu: 8 cores
ram: 32GB
almacenamiento: 100GB SSD NVMe
distribucion_vram:
faster_whisper_large: ~3GB
xtts_v2: ~3GB
buffer: ~6GB
hardware_recomendado:
gpu: RTX 3080/3090 (10-24GB VRAM)
cpu: 12+ cores
ram: 64GB
almacenamiento: 500GB SSD NVMe
beneficios:
- Modelos más grandes
- Batch processing
- Menor latencia
```
### 6.3 Latencias Objetivo
| Componente | Objetivo | Máximo Aceptable |
|------------|----------|------------------|
| VAD | <50ms | 100ms |
| ASR | <400ms | 800ms |
| LLM (primer token) | <500ms | 1500ms |
| LLM (completo) | <1500ms | 3000ms |
| TTS (primer audio) | <200ms | 500ms |
| **Total voice-to-voice** | **<2000ms** | **<4000ms** |
---
## 7. Modelos Autoalojados
### 7.1 Comparativa ASR
| Modelo | Latencia | Calidad | VRAM | Recomendación |
|--------|----------|---------|------|---------------|
| Whisper Large V3 | 400ms | ★★★★★ | 3GB | **Producción** |
| Whisper Distil Large V2 | 200ms | ★★★★☆ | 2GB | Baja latencia |
| Whisper Medium | 300ms | ★★★☆☆ | 2GB | Fallback |
| Whisper Small | 150ms | ★★☆☆☆ | 1GB | No recomendado |
### 7.2 Comparativa TTS
| Modelo | Latencia | Naturalidad | VRAM | Clonación | Recomendación |
|--------|----------|-------------|------|-----------|---------------|
| XTTS-v2 | 300ms | ★★★★★ | 3GB | ✅ 6s audio | **Producción** |
| Kokoro-82M | 150ms | ★★★★☆ | 1GB | ❌ | Baja latencia |
| Piper | 50ms | ★★★☆☆ | <1GB | ❌ | Emergencia |
| OpenVoice | 400ms | ★★★★☆ | 2GB | ✅ | Alternativa |
### 7.3 Experiencias Reales de Usuarios
```
┌─────────────────────────────────────────────────────────────────────┐
│ FASTER-WHISPER + XTTS-v2 en RTX 3080 │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ "Conseguí ~500ms latencia voice-to-voice con un modelo 24B │
│ de Mistral via Ollama. La clave es el streaming de TTS." │
│ — KoljaB, RealtimeVoiceChat │
│ │
│ "En una 4090 con faster-distil-whisper-large-v2 bajamos │
│ a 300ms de latencia total. Es casi como hablar con alguien." │
│ — voicechat2 │
│ │
│ "XTTS-v2 clone de la voz de mi abuelo me hizo llorar. │
│ Vale cada dolor de cabeza de instalación." │
│ — GitHub contributor │
│ │
│ "El turn detection es lo más difícil. Silero VAD funciona │
│ bien pero hay que ajustar los thresholds para cada persona." │
│ — Reddit r/LocalLLaMA │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## 8. Conversación Natural por Turnos
### 8.1 Principios de Turn-Taking
```
┌─────────────────────────────────────────────────────────────────────┐
│ CONVERSACIÓN NATURAL │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. DETECCIÓN DE FIN DE TURNO │
│ ├── Silencio: 700ms mínimo (configurable) │
│ ├── Prosodia: bajada de tono indica fin │
│ └── Semántica: frase completa detectada │
│ │
│ 2. BARGE-IN (Interrupción) │
│ ├── Usuario puede interrumpir a PENNY │
│ ├── VAD detecta voz mientras TTS reproduce │
│ └── Se cancela TTS y se procesa nueva entrada │
│ │
│ 3. BACKCHANNELING │
│ ├── "Mm-hmm", "Vale", "Sí" no son turnos completos │
│ └── PENNY no debe responder a acknowledgments │
│ │
│ 4. OVERLAPPING │
│ ├── Permitir ligero solapamiento natural │
│ └── No cortar bruscamente al usuario │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 8.2 Configuración de Turn Detection
```yaml
turn_detection:
silero_vad:
speech_threshold: 0.5
min_speech_ms: 250
min_silence_ms: 700 # Fin de turno
padding_ms: 30
end_of_turn:
# Tiempo de silencio para considerar fin de turno
confident_silence_ms: 500 # Si hay alta confianza semántica
uncertain_silence_ms: 1000 # Si la frase parece incompleta
max_silence_ms: 2000 # Forzar fin de turno
barge_in:
enabled: true
min_user_speech_ms: 200 # Evitar falsos positivos
cancel_tts: true
cancel_llm_streaming: true
backchanneling:
ignore_patterns:
- "^(mhm|mm|sí|ajá|vale|ok|ya)$"
max_duration_ms: 500
```
### 8.3 Manejo de Estados
```
┌─────────────────────────────────────────────────────────────────────┐
│ ESTADOS DE PENNY │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ IDLE ──────────────────────────────────────────────────────────▶ │
│ │ │
│ │ VAD detecta voz │
│ ▼ │
│ LISTENING ─────────────────────────────────────────────────────▶ │
│ │ │
│ │ Silencio detectado (end of turn) │
│ ▼ │
│ PROCESSING ────────────────────────────────────────────────────▶ │
│ │ │
│ │ ASR completo + LLM responde │
│ ▼ │
│ SPEAKING ──────────────────────────────────────────────────────▶ │
│ │ │
│ ├── TTS termina → IDLE │
│ │ │
│ └── Barge-in → LISTENING (cancela TTS) │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### 8.4 Feedback Visual/Sonoro
```yaml
feedback:
estados:
idle:
led: "azul tenue"
sonido: null
listening:
led: "azul pulsante"
sonido: "bip_inicio" # Opcional
processing:
led: "amarillo"
sonido: null
speaking:
led: "verde"
sonido: null
error:
led: "rojo"
sonido: "error_tone"
transiciones:
inicio_escucha: true # Feedback al empezar a escuchar
fin_escucha: false # Sin feedback (fluido)
inicio_respuesta: false # Directo a hablar
```
---
## 9. Implementación de Referencia
### 9.1 Estructura de Directorios
```
/penny/
├── config/
│ ├── pipeline.yaml # Configuración de modelos
│ ├── planos/
│ │ ├── sistema.yaml # Plano 0
│ │ ├── personalidad.yaml # Plano 1
│ │ └── default_user.yaml # Plano 2 template
│ └── turn_detection.yaml # Configuración de turnos
│
├── core/
│ ├── penny_core.py # Orquestador principal
│ ├── planos_manager.py # Gestión de planos
│ ├── grace_client.py # Cliente para GRACE
│ └── log_writer.py # Escritura a PENNY_LOG
│
├── voice/
│ ├── vad_processor.py # Silero VAD
│ ├── asr_processor.py # Faster-Whisper
│ ├── tts_processor.py # XTTS-v2 / Kokoro
│ └── turn_manager.py # Gestión de turnos
│
├── models/
│ ├── whisper/
│ │ └── large-v3/
│ ├── xtts/
│ │ └── v2/
│ └── silero/
│ └── vad_v5.onnx
│
├── voces/
│ └── penny_base.wav # Voz base para clonación
│
└── server/
├── main.py # Servidor FastAPI
├── websocket.py # WebSocket handler
└── routes.py # Endpoints REST
```
### 9.2 Dependencias
```bash
# requirements.txt
# Framework
pipecat-ai>=0.0.50
pipecat-ai[silero,whisper,coqui]
# LLM
anthropic>=0.35.0
# Audio
pyaudio>=0.2.14
numpy>=1.24.0
scipy>=1.11.0
soundfile>=0.12.0
# Servidor
fastapi>=0.109.0
uvicorn>=0.27.0
websockets>=12.0
# Base de datos
asyncpg>=0.29.0
sqlalchemy>=2.0.0
# Utilidades
pyyaml>=6.0
python-dotenv>=1.0.0
```
### 9.3 Configuración de Inicio
```yaml
# config/pipeline.yaml
penny:
version: "1.0"
server:
host: "0.0.0.0"
port: 8765
websocket_path: "/ws/voice"
models:
vad:
type: "silero"
path: "models/silero/vad_v5.onnx"
asr:
type: "faster-whisper"
model: "large-v3"
path: "models/whisper/large-v3"
device: "cuda"
compute_type: "float16"
tts:
type: "xtts-v2"
path: "models/xtts/v2"
speaker_wav: "voces/penny_base.wav"
language: "es"
llm:
provider: "anthropic"
model: "claude-sonnet-4-20250514"
max_tokens: 150
temperature: 0.7
streaming: true
grace:
endpoint: "http://localhost:8080/api/v1"
timeout_ms: 10000
log:
database_url: "postgresql://penny:xxx@localhost:5432/penny_db"
retain_audio_days: 7
retain_text_days: 365
```
### 9.4 Ejemplo de Código Core
```python
# core/penny_core.py
import asyncio
from typing import Optional
from dataclasses import dataclass
from .planos_manager import PlanosManager
from .grace_client import GraceClient
from .log_writer import LogWriter
@dataclass
class PennyConfig:
planos_path: str
grace_endpoint: str
llm_config: dict
log_config: dict
class PennyCore:
"""Orquestador principal de PENNY."""
def __init__(self, config: PennyConfig):
self.config = config
self.planos = PlanosManager(config.planos_path)
self.grace = GraceClient(config.grace_endpoint)
self.log = LogWriter(config.log_config)
self.sesion_id: Optional[str] = None
self.turno_index: int = 0
async def iniciar_sesion(self, player_id: str) -> str:
"""Inicia una nueva sesión de conversación."""
self.sesion_id = await self.log.crear_sesion(player_id)
self.turno_index = 0
# Cargar planos
await self.planos.cargar_plano(0) # Sistema
await self.planos.cargar_plano(1) # Personalidad
await self.planos.cargar_plano(2, player_id) # Contexto personal
await self.planos.cargar_plano(3) # Contexto ambiental (auto)
return self.sesion_id
async def procesar_turno(self, texto_usuario: str, audio_ref: Optional[str] = None) -> str:
"""Procesa un turno del usuario y genera respuesta."""
self.turno_index += 1
timestamp_inicio = datetime.utcnow()
# Detectar si necesita GRACE
grace_llamadas = []
if self._necesita_grace(texto_usuario):
resultado_grace = await self._llamar_grace(texto_usuario)
grace_llamadas.append(resultado_grace)
# Construir prompt con planos
prompt = self._construir_prompt(texto_usuario, grace_llamadas)
# Llamar a Claude
respuesta = await self._llamar_llm(prompt)
# Registrar en log
await self.log.registrar_turno(
sesion_id=self.sesion_id,
turno_index=self.turno_index,
rol="usuario",
texto=texto_usuario,
audio_ref=audio_ref,
timestamp_inicio=timestamp_inicio
)
await self.log.registrar_turno(
sesion_id=self.sesion_id,
turno_index=self.turno_index + 1,
rol="penny",
texto=respuesta,
grace_llamadas=grace_llamadas,
timestamp_inicio=datetime.utcnow()
)
self.turno_index += 1
return respuesta
def _necesita_grace(self, texto: str) -> bool:
"""Determina si la consulta requiere llamar a GRACE."""
keywords = ["factura", "documento", "escaneé", "resume", "extraer"]
return any(kw in texto.lower() for kw in keywords)
async def _llamar_grace(self, texto: str) -> dict:
"""Llama a GRACE con el Contrato Común."""
modulo = self._detectar_modulo_grace(texto)
return await self.grace.llamar(
modulo=modulo,
payload={"query": texto},
caller_sesion=self.sesion_id
)
def _construir_prompt(self, texto: str, grace_datos: list) -> str:
"""Construye el prompt completo con todos los planos."""
planos_texto = self.planos.obtener_contexto_completo()
prompt = f"""
{planos_texto}
--- DATOS DE GRACE ---
{json.dumps(grace_datos, indent=2) if grace_datos else "No se consultaron datos."}
--- USUARIO ---
{texto}
--- INSTRUCCIONES ---
Responde de forma concisa (máximo 3 oraciones) siguiendo tu personalidad definida.
"""
return prompt
```
---
## Resumen
PENNY es el asistente de voz del DECK con las siguientes características:
1. **100% autoalojado** excepto Claude API (solo texto)
2. **Planos de información** separados y cargables independientemente
3. **Log completo** de todas las interacciones
4. **Integración con GRACE** via Contrato Común
5. **Conversación natural por turnos** con barge-in y turn detection
6. **Latencia objetivo** <2 segundos voice-to-voice
### Próximos Pasos
1. [ ] Configurar servidor con GPU
2. [ ] Instalar modelos (Whisper, XTTS-v2, Silero)
3. [ ] Crear base de datos y tablas de log
4. [ ] Definir planos específicos del usuario
5. [ ] Grabar voz base para clonación TTS
6. [ ] Implementar pipeline con Pipecat
7. [ ] Ajustar turn detection para conversación natural
---
*Documento generado: Diciembre 2025*
*Versión: 1.0*
Reference in New Issue Copy Permalink