# Asistente de Voz

**Nombre:** Penny  
**Versión:** 1.0  
**Estado:** Especificación

---

## Descripción

PENNY es el asistente personal de voz del sistema DECK. Proporciona interfaz conversacional hablada 100% natural.

```
┌─────────────────────────────────────────────────────────────────┐
│                         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."               │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Principios

| Principio | Descripción |
|-----------|-------------|
| **Privacidad radical** | Audio procesado 100% local |
| **Conversación natural** | Turnos fluidos, latencia <2s |
| **Log como verdad** | Todo está en el log |
| **Planos separados** | Contextos cargables independientemente |
| **GRACE como backend** | PENNY pregunta, GRACE extrae |

---

## Arquitectura

```
┌─────────────────────────────────────────────────────────────────┐
│                    PENNY VOICE ENGINE                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐│
│  │  Silero    │  │  Faster    │  │   PENNY    │  │   XTTS-v2  ││
│  │   VAD      │─▶│  Whisper   │─▶│   CORE     │─▶│  /Kokoro   ││
│  │            │  │            │  │            │  │            ││
│  │ Detecta    │  │ Transcribe │  │ Orquesta   │  │ Sintetiza  ││
│  │ voz        │  │ audio      │  │ todo       │  │ respuesta  ││
│  └────────────┘  └────────────┘  └─────┬──────┘  └────────────┘│
│                                        │                        │
│                    ┌───────────────────┼───────────────────┐    │
│                    │                   │                   │    │
│                    ▼                   ▼                   ▼    │
│            ┌─────────────┐     ┌─────────────┐                  │
│            │   PLANOS    │     │    GRACE    │                  │
│            │   (Log)     │     │ (S-CONTRACT)│                  │
│            └─────────────┘     └─────────────┘                  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                                   │
                                   │ SOLO texto (nunca audio)
                                   ▼
                    ┌─────────────────────────────┐
                    │      Claude API             │
                    └─────────────────────────────┘
```

---

## 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 S-CONTRACT
   ├── 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
```

---

## Planos de Información

El Log está organizado en planos que se cargan independientemente:

| Plano | Nombre | Descripción | Comportamiento |
|-------|--------|-------------|----------------|
| 0 | SISTEMA | Instrucciones base | INMUTABLE durante sesión |
| 1 | PERSONALIDAD | Tono, estilo, nombre, voz | CONFIGURABLE por usuario |
| 2 | CONTEXTO PERSONAL | Info usuario, preferencias | PERSISTENTE entre sesiones |
| 3 | CONTEXTO AMBIENTAL | Fecha, hora, estado sistema | DINÁMICO cada sesión |
| 4 | DATASET | Datos específicos de tarea | OPCIONAL bajo demanda |
| 5 | CONVERSACIÓN | Historial de sesión | TEMPORAL durante sesión |

---

## Modelos Autoalojados

| Componente | Modelo | Descripción |
|------------|--------|-------------|
| VAD | Silero VAD v5 | Detección de actividad vocal |
| ASR | Faster-Whisper Large-v3 | Transcripción |
| TTS | XTTS-v2 / Kokoro | Síntesis de voz |
| LLM | Claude API | Solo texto, streaming |

---

## Configuración

```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"
      device: "cuda"
      compute_type: "float16"
    
    tts:
      type: "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://..."
    retain_audio_days: 7
    retain_text_days: 365
```

---

## Rol en el Sistema

```
┌─────────────────────────────────────────────────────────────────┐
│                   DECK (Servidor Personal)                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Usuario ◄────────────────────────────────────► PENNY         │
│            (voz natural)                │         (habla)       │
│                                         │                       │
│                          ┌──────────────┼──────────────┐        │
│                          │              │              │        │
│                          ▼              ▼              ▼        │
│                    ┌─────────┐   ┌─────────┐   ┌─────────┐     │
│                    │  GRACE  │   │   LOG   │   │  DECK   │     │
│                    │ (datos) │   │(planos) │   │(acciones│     │
│                    └─────────┘   └─────────┘   └─────────┘     │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## Características Conversacionales

| Característica | Descripción |
|----------------|-------------|
| **Barge-in** | Usuario puede interrumpir |
| **Turn detection** | Detecta fin de turno por silencio |
| **Contexto** | Mantiene contexto durante sesión |
| **Streaming** | Respuesta progresiva mientras genera |

---

## Pendiente

- [ ] Configurar servidor con GPU
- [ ] Instalar modelos (Whisper, XTTS-v2, Silero)
- [ ] Crear tablas de log
- [ ] Definir planos específicos
- [ ] Grabar voz base para clonación TTS
- [ ] Implementar pipeline con Pipecat
- [ ] Ajustar turn detection