117 lines
2.5 KiB
Markdown
117 lines
2.5 KiB
Markdown
# 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
|