Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
257 lines (201 loc) · 6.49 KB

ARCHITECTURE.md

File metadata and controls

257 lines (201 loc) · 6.49 KB

Arquitectura - Fase 0

Visión General

┌─────────────────────────────────────┐
│         USUARIO (Voz)               │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    Push-to-Talk (cmd+space)         │
│    Activa captura de audio          │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    VAD (Voice Activity Detection)   │
│    Detecta cuando usuario habla     │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    STT (Whisper small)              │
│    Transcribe audio → texto         │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    Buffer de Contexto (20 msgs)    │
│    Mantiene historial              │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    LLM (Llama 3.2 3B)              │
│    Genera respuesta                │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│    TTS (macOS say)                 │
│    Texto → voz                     │
│                                    │
│    Sistema de Interrupciones:     │
│    VAD paralelo detecta habla     │
│    → Cancela TTS inmediatamente   │
└────────────────────────────────────┘

Módulos

Audio (src/audio/)

vad.py - Voice Activity Detection

  • WebRTC VAD
  • Detecta habla del usuario
  • Configuración de aggressiveness (0-3)

stt.py - Speech-to-Text

  • Whisper (OpenAI)
  • Modelo: small
  • Latencia: 0.5-1.5s

tts.py - Text-to-Speech

  • macOS say command
  • Voz: Jorge (español)
  • Split en oraciones para interrupciones

push_to_talk.py - Activación por Tecla

  • Pynput keyboard listener
  • Default: cmd+space
  • Async events

interruption.py - Sistema de Interrupciones ⭐

  • Enfoque A: TTS por chunks + VAD paralelo
  • Cancela TTS inmediatamente si usuario habla
  • Captura nuevo input del usuario

hotword.py - Detección de Palabra Clave

  • 🚧 SEMANA 3 - TODOs
  • Placeholder para Porcupine

LLM (src/llm/)

llama_client.py - Cliente Llama

  • Ollama API
  • 3 perfiles: testing, production, conversational
  • Q4_K_M quantization (2GB RAM)

Conversation (src/conversation/)

context.py - Buffer de Contexto

  • FIFO deque (20 mensajes)
  • System prompt siempre presente
  • Export para logging

manager.py - Gestor Conversacional

  • Coordina flujo completo
  • Captura → Transcribe → LLM → Habla
  • Maneja interrupciones

Utils (src/utils/)

config_loader.py - Carga de Configuración

  • Lee config.yaml
  • Notación de punto para acceso
  • Crea directorios necesarios

logging_system.py - Sistema de Logging

  • Structlog
  • Session logs con timestamps
  • Latencias de cada componente
  • Tracking de contexto

Flujo de Datos

Turno Normal (Sin Interrupción)

1. Usuario presiona cmd+space
2. VAD detecta inicio de habla
3. Captura audio hasta silencio
4. Whisper transcribe → texto
5. Añadir a contexto
6. Llama genera respuesta
7. Añadir respuesta a contexto
8. TTS habla (por oraciones)
9. VAD monitorea (por si interrumpe)
10. Completado

Latencia total: ~1.5-3s

Con Interrupción

1-6. [Igual que arriba]
7. TTS empieza a hablar oración 1
8. VAD detecta habla del usuario
9. ⚠️ INTERRUPCIÓN DETECTADA
10. Cancela TTS inmediatamente
11. Captura lo que usuario está diciendo
12. Whisper transcribe interrupción
13. Añadir a contexto
14. Llama genera nueva respuesta
15. TTS habla nueva respuesta

Latencia interrupción: <200ms

Configuración (config.yaml)

Perfiles LLM

Perfil Temp Tokens Latencia Uso
testing 0.1 50 0.3-0.6s Validación rápida
production 0.3 150 0.8-1.5s Balance (default)
conversational 0.7 250 1.5-2.5s Natural

VAD Aggressiveness

  • 0: Muy sensible (más falsos positivos)
  • 1: Sensible
  • 2: Balanceado (default)
  • 3: Agresivo (puede perder habla)

Logging

Cada sesión genera:

logs/sessions/session_YYYYMMDD_HHMMSS.log

Contiene:

  • Timestamp de cada interacción
  • Latencias (VAD, STT, LLM, total)
  • Contexto usado (últimos N mensajes)
  • Token counts
  • Interrupciones con VAD confidence
  • Errores con traceback

Testing

Test de Latencias

python tests/test_latency.py

Mide:

  • VAD: <1ms
  • STT: ~1.5s
  • LLM: 0.3-2.5s (según perfil)
  • Pipeline total: <3s (target)

Test 1-100 (Guiado)

python scripts/test_counting.py

Valida:

  • Interrupciones funcionan
  • Contexto se mantiene
  • Cambios de dirección
  • Cambios de reglas

Limitaciones Fase 0

❌ No soportado en Fase 0:

  • Funciones/herramientas externas
  • Web search
  • Filesystem operations
  • Email management
  • Workspaces
  • Task queue
  • LLM Complejo (Claude API)
  • Persistencia en disco (solo en RAM)

✅ Solo conversación pura con contexto en memoria

Próximas Fases

Fase 1 (Semanas 4-7):

  • Dual LLM (Llama + Claude)
  • Task Queue asíncrona
  • Web search
  • Persistencia básica (SQLite)

Fase 2 (Semanas 8-11):

  • Filesystem completo
  • MCP servers
  • Bandeja de entrada

Ver PROYECTO_ASISTENTE_VOZ_ESPECIFICACION.md para roadmap completo.