first commit

docs/refactor-plan.md

@@ -0,0 +1,116 @@
+# Refactor Plan
+
+## Objetivo
+
+Fazer um refactor incremental da camada de runtime de voz sem quebrar:
+- contrato do bridge websocket
+- integracao com LiveKit
+- pipeline atual de negocio
+- comportamento de interrupcao, idle nudge e finalizacao
+
+## Problema atual
+
+Hoje o arquivo `app/livekit/main.py` concentra responsabilidades demais:
+- wiring do AgentSession
+- timers
+- politica de interrupcao
+- idle nudge
+- finalizacao
+- chamada da pipeline
+- speak / wait_for_playout
+- notificacao ao bridge
+
+Isso dificulta manutencao, teste e evolucao para alternativas futuras como:
+- `llm_node`
+- agente remoto via API
+- politica de chamada mais previsivel
+
+## Direcao arquitetural
+
+Separar o runtime em camadas:
+- adapters: wrappers dos componentes atuais (pipeline, speech, bridge, export)
+- runtime: coordenacao da chamada
+- domain: estado, eventos e comandos
+- policies: regras puras de interrupcao, idle e finalizacao
+- engine: reducer e scheduler
+
+## Principios
+
+- preservar comportamento antes de trocar mecanismo
+- extrair boundaries antes de mudar a orquestracao
+- isolar side effects
+- tornar finalizacao idempotente
+- introduzir estado explicito da chamada
+
+## Fases sugeridas
+
+### Fase 1: Boundaries
+
+Extrair sem mudar comportamento:
+- `PipelineAdapter`
+- `SpeechService`
+- `BridgeGateway`
+- `ExportService`
+
+Saida esperada:
+- `app/livekit/main.py` menor
+- regras ainda iguais as de hoje
+
+### Fase 2: Runtime explicito
+
+Introduzir:
+- `CallState`
+- `CallRuntime`
+- comandos e eventos
+
+Saida esperada:
+- menor uso de `nonlocal`
+- caminhos de execucao mais faceis de seguir
+
+### Fase 3: Policies e scheduler
+
+Migrar:
+- interrupcao
+- idle nudge
+- idle close
+- finalize once
+
+Saida esperada:
+- regras de chamada isoladas e testaveis
+
+### Fase 4: Evolucao de IA
+
+Avaliar depois da estabilizacao:
+- `llm_node`
+- agente remoto via API
+- SSE / websocket para agente externo
+
+Saida esperada:
+- STT / IA / TTS com fronteiras mais limpas
+
+## Fora de escopo inicial
+
+- reescrever bridge
+- substituir pipeline de negocio
+- trocar protocolo websocket externo
+- mudar contrato de audio
+
+## Definition of done por fase
+
+### Fase 1
+- sem mudanca de contrato externo
+- sem mudanca de fluxo de audio
+- classes novas usadas pelo `main.py`
+
+### Fase 2
+- estado da chamada centralizado
+- menos logica de coordenacao inline
+
+### Fase 3
+- timers centralizados
+- finalizacao unica e previsivel
+- regras de interrupcao sem duplicacao
+
+### Fase 4
+- nova integracao de IA desacoplada do fluxo manual atual
+- comparacao controlada com comportamento anterior