tia_regional_xai_tts_pool/docs/refactor-plan.md

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