tia_regional_xai_tts_pool/docs/refactor-log.md

Refactor Log

Este arquivo registra o que mudou a cada etapa do refactor incremental.

Nota:

• as entradas 000 a 010 foram escritas antes da consolidacao da estrutura atual do repositorio
• por isso, varias delas ainda referenciam caminhos antigos sem o prefixo src/
• a partir da entrada 011, os caminhos refletem o layout atual da raiz + src/

Como preencher

Para cada mudanca relevante, registrar:

• data
• objetivo
• arquivos alterados
• comportamento preservado
• comportamento alterado
• risco conhecido
• validacao executada
• proximo passo

Entrada 000 - Baseline documental

• Data: 2026-03-27
• Objetivo: criar uma base de documentacao viva para acompanhar o refactor incremental
• Arquivos alterados:
  • README.md
  • docs/README.md
  • docs/refactor-plan.md
  • docs/refactor-log.md
  • docs/api-overview.md
• Comportamento preservado: nenhum codigo de execucao foi alterado
• Comportamento alterado: nenhum
• Risco conhecido: a documentacao precisa ser mantida junto das mudancas, senao perde valor
• Validacao executada: revisao manual do conteudo criado
• Proximo passo: iniciar Fase 1 com extracao dos adapters de pipeline, speech, bridge e export

Entrada 001 - Fase 1 / adapters extraidos

• Data: 2026-03-27
• Objetivo: extrair boundaries de pipeline, speech, bridge e export sem mudar o comportamento publico da API
• Arquivos alterados:
  • app/livekit/main.py
  • app/livekit/adapters/pipeline_adapter.py
  • app/livekit/adapters/speech_service.py
  • app/livekit/adapters/bridge_gateway.py
  • app/livekit/adapters/export_service.py
  • docs/refactor-log.md
• Comportamento preservado:
  • contrato do websocket do bridge
  • fluxo STT -> pipeline -> TTS
  • notificacao DONE para o bridge
  • exportacao final de sessao
• Comportamento alterado:
  • nenhum comportamento publico planejado
  • app/livekit/main.py passa a delegar responsabilidades para adapters
• Risco conhecido:
  • como a extracao preserva a logica inline, ainda existe acoplamento forte no runtime
  • faltam testes automatizados de regressao para interrupcao, idle nudge e finalizacao
• Validacao executada:
  • revisao manual do diff
  • validacao sintatica prevista apos a extracao
• Proximo passo:
  • reduzir nonlocal no runtime com um CallRuntime explicito
  • preparar o terreno para policies e scheduler unificados

Entrada 002 - Fase 2 / runtime explicito

• Data: 2026-03-27
• Objetivo: encapsular o fluxo da chamada em um CallRuntime com CallState explicito, reduzindo estado implícito e nonlocal em app/livekit/main.py
• Arquivos alterados:
  • app/livekit/main.py
  • app/livekit/runtime/state.py
  • app/livekit/runtime/call_runtime.py
  • docs/refactor-log.md
  • docs/api-overview.md
• Comportamento preservado:
  • contrato do websocket do bridge
  • fluxo STT -> pipeline -> TTS
  • idle nudge, interrupcao e finalizacao continuam com a mesma logica operacional
  • exportacao e notificacao DONE continuam sendo disparadas pelo agent
• Comportamento alterado:
  • app/livekit/main.py passa a ser majoritariamente wiring do session e construcao do runtime
  • o estado mutavel da chamada fica concentrado em CallState
• Risco conhecido:
  • as regras ainda nao foram transformadas em policies puras; a logica segue acoplada ao runtime, apenas mais organizada
  • ainda faltam testes automatizados para cenarios concorrentes de fala, interrupcao e fechamento
• Validacao executada:
  • revisao manual do diff
  • PYTHONDONTWRITEBYTECODE=1 python3 -m py_compile app/livekit/main.py app/livekit/adapters/bridge_gateway.py app/livekit/adapters/export_service.py app/livekit/adapters/pipeline_adapter.py app/livekit/adapters/speech_service.py app/livekit/runtime/state.py app/livekit/runtime/call_runtime.py
• Proximo passo:
  • introduzir command/execution boundaries no runtime
  • preparar a migracao de interrupcao, idle e finalize para policies + scheduler

Entrada 003 - Fase 3 / commands e executor

• Data: 2026-03-29
• Objetivo: separar efeitos colaterais do CallRuntime por meio de comandos tipados e um executor dedicado
• Arquivos alterados:
  • app/livekit/main.py
  • app/livekit/runtime/commands.py
  • app/livekit/runtime/command_executor.py
  • app/livekit/runtime/call_runtime.py
  • docs/refactor-log.md
  • docs/api-overview.md
• Comportamento preservado:
  • contrato do websocket do bridge
  • fluxo STT -> pipeline -> TTS
  • sequencia de idle nudge, interrupcao e finalizacao
  • integracao com LiveKit, pipeline e export sem troca de contrato
• Comportamento alterado:
  • CallRuntime deixa de chamar diretamente bridge/export/speech/pipeline para os principais side effects
  • side effects passam a trafegar por comandos (commands.py) executados por RuntimeCommandExecutor
• Risco conhecido:
  • ainda existe conhecimento de regras dentro de CallRuntime; a extracao atual isola efeitos, mas nao transforma as regras em policies puras
  • agent._ready, agent._run_lock e coordenacao de fila ainda pertencem ao runtime
• Validacao executada:
  • revisao manual do diff
  • validacao sintatica com python3 -c 'from pathlib import Path; paths = [...]; [compile(Path(p).read_text(), p, "exec") for p in paths]'
• Proximo passo:
  • extrair policies de interrupcao, idle e finalizacao
  • introduzir scheduler unico para timers e reduzir logica condicional no runtime

Entrada 004 - Fase 4 / policies e scheduler

• Data: 2026-03-29
• Objetivo: mover regras de interrupcao, idle e finalize-once para policies dedicadas e centralizar timers em um scheduler unico
• Arquivos alterados:
  • app/livekit/main.py
  • app/livekit/policies/interrupt_policy.py
  • app/livekit/policies/idle_policy.py
  • app/livekit/policies/finalization_policy.py
  • app/livekit/runtime/scheduler.py
  • app/livekit/runtime/state.py
  • app/livekit/runtime/call_runtime.py
  • docs/refactor-log.md
  • docs/api-overview.md
• Comportamento preservado:
  • contrato do websocket do bridge
  • fluxo STT -> pipeline -> TTS
  • timers de idle nudge e idle close continuam ativos
  • finalizacao por DONE, room_empty, shutdown_callback e no_user_response continua existindo
• Comportamento alterado:
  • InterruptPolicy passa a decidir interrupcao por stage e filtro de backchannel
  • IdlePolicy passa a concentrar regras de nudge/close
  • FinalizationPolicy passa a concentrar regras de finalize-once e room-empty
  • TimerScheduler passa a concentrar arm/cancel/token dos timers
  • CallState deixa de carregar estado interno de timers
• Risco conhecido:
  • o CallRuntime ainda conhece a ordem operacional completa da chamada; as policies reduzem acoplamento, mas ainda nao existe reducer/event engine
  • RuntimeConfig ainda carrega campos hoje parcialmente sobrepostos pelas policies; isso pode ser simplificado em um corte futuro
• Validacao executada:
  • revisao manual do diff
  • validacao sintatica com python3 -c 'from pathlib import Path; paths = [...]; [compile(Path(p).read_text(), p, "exec") for p in paths]'
• Proximo passo:
  • avaliar se vale introduzir eventos/comandos mais declarativos no runtime ou parar aqui e estabilizar
  • se seguir, o proximo salto natural e um reducer/event engine ou a evolucao da integracao de IA (llm_node ou agente remoto)

Entrada 005 - Estabilizacao / testes unitarios do runtime

• Data: 2026-03-29
• Objetivo: adicionar cobertura automatizada para os cenarios mais criticos do runtime sem depender de LiveKit real
• Arquivos alterados:
  • tests/__init__.py
  • tests/livekit/__init__.py
  • tests/livekit/test_runtime.py
  • docs/refactor-log.md
• Comportamento preservado:
  • nenhum contrato publico da API foi alterado
  • nenhum fluxo de audio ou websocket foi modificado
• Comportamento alterado:
  • o repositorio passa a ter uma suite unitária para policies, scheduler, command executor e cenarios críticos do CallRuntime
• Risco conhecido:
  • os testes ainda usam doubles/fakes e nao substituem validacao integrada com LiveKit real
  • ainda faltam cenarios mais completos de timer real, callback de room e speech handle real
• Validacao executada:
  • python3 -m unittest tests.livekit.test_runtime -v
  • python3 -m unittest discover -s tests -v
• Proximo passo:
  • ampliar cobertura para speech handle real e integracao de callbacks com objetos LiveKit reais, se isso passar a ser area de regressao
  • ou encerrar a fase de estabilizacao e voltar a discutir a evolucao da camada de IA

Entrada 006 - Backend remoto via websocket

• Data: 2026-03-29
• Objetivo: permitir trocar a pipeline local por um agent remoto via websocket, preservando o fluxo STT -> IA -> TTS e o runtime atual
• Arquivos alterados:
  • app/livekit/main.py
  • app/livekit/adapters/agent_backend.py
  • app/livekit/adapters/backend_factory.py
  • app/livekit/adapters/pipeline_adapter.py
  • app/livekit/adapters/remote_agent_ws_adapter.py
  • app/livekit/runtime/command_executor.py
  • requirements.txt
  • tests/livekit/test_remote_agent_ws_adapter.py
  • docs/refactor-log.md
  • docs/api-overview.md
• Comportamento preservado:
  • contrato do websocket do bridge
  • fluxo de audio com LiveKit e TTS no agent local
  • runtime de interrupcao, idle nudge e finalizacao
  • backend langgraph segue como default
• Comportamento alterado:
  • o backend da camada de IA passa a ser selecionavel por AGENT_BACKEND
  • quando AGENT_BACKEND=remote_ws, o agent envia cada turno transcrito para um websocket remoto e vocaliza a resposta retornada
  • a finalizacao pode opcionalmente buscar um result remoto via mensagem type=end
  • o bridge agora repassa agent, RouterCallKeyDay, RouterCallKey, ANI, GSM e ID_FATURA para o agent quando esses campos vierem no metadata do cliente
  • o adapter remoto roteia a chamada para endpoints diferentes de acordo com agent (conta, oferta, cobranca)
  • o agent conta passou a usar contrato proprio em websocket com action/payload na entrada e result.content na resposta
• Risco conhecido:
  • o contrato do websocket remoto ainda e interno e precisa ser homologado com o agent externo real
  • o adapter atual usa conexao websocket por turno, nao uma sessao persistente
  • se o agent remoto nao devolver stage, a politica local dependera do ultimo stage conhecido ou do default configurado
  • o campo timestamp e gerado localmente no momento de cada turno; se o integrador exigir outro formato, isso ainda precisa ser alinhado
• Validacao executada:
  • testes unitarios do adapter remoto e factory
  • execucao da suite unittest
• Proximo passo:
  • homologar o contrato do websocket remoto com payload/resposta reais
  • decidir se a conexao remota deve continuar por turno ou evoluir para sessao persistente

Entrada 007 - Cliente web de voz e call_config por chamada

• Data: 2026-03-30
• Objetivo: disponibilizar um cliente web para testar o fluxo de voz pelo navegador e permitir overrides de STT, TTS e AGENT por chamada
• Arquivos alterados:
  • app/ws_gateway/main.py
  • app/ws_gateway/voice_client.html
  • app/ws_gateway/call_config.py
  • app/livekit/main.py
  • app/livekit/call_config.py
  • app/livekit/adapters/backend_factory.py
  • tests/config/test_call_config.py
  • docs/api-overview.md
  • docs/refactor-log.md
• Comportamento preservado:
  • fluxo principal de audio via /ws/agent
  • bridge continua recebendo start, audio binario e encerrando com stop
  • defaults de STT, TTS e backend continuam vindo de env quando nao houver override
• Comportamento alterado:
  • /voice-client agora serve um cliente web para capturar microfone e ouvir o audio retornado
  • o start pode carregar call_config com overrides por chamada
  • o agent agora aplica overrides de backend, STT e TTS para a sessao corrente
• Risco conhecido:
  • o cliente web usa ScriptProcessorNode, que e suficiente para homologacao mas nao e a opcao mais moderna da Web Audio API
  • os providers dinamicos suportados ainda sao os que ja existem no projeto (internal_http e elevenlabs)
• Validacao executada:
  • testes puros de call_config
  • execucao da suite unittest
• Proximo passo:
  • se o cliente web passar a ser usado em rotina de homologacao, vale migrar a captura/playback para AudioWorklet
  • se surgirem novos providers de STT/TTS, plugar nas factories por chamada

Entrada 008 - Timeline estruturada por chamada

• Data: 2026-03-30
• Objetivo: criar observabilidade ponta a ponta para entender o caminho bridge -> livekit -> stt -> backend -> tts -> stop por chamada
• Arquivos alterados:
  • app/utils/call_timeline.py
  • app/ws_gateway/main.py
  • app/livekit/main.py
  • app/livekit/runtime/call_runtime.py
  • app/livekit/adapters/backend_factory.py
  • app/livekit/adapters/pipeline_adapter.py
  • app/livekit/adapters/remote_agent_ws_adapter.py
  • app/livekit/adapters/bridge_gateway.py
  • app/providers/stt_internal_livekit.py
  • tests/utils/test_call_timeline.py
  • docs/api-overview.md
  • docs/refactor-log.md
• Comportamento preservado:
  • contrato publico de WS /ws/agent
  • fluxo de audio ja existente entre cliente, bridge, LiveKit e agent
  • backends de IA, STT e TTS seguem com a mesma responsabilidade funcional
• Comportamento alterado:
  • bridge e agent agora escrevem uma timeline estruturada em jsonl compartilhada por chamada
  • a timeline usa o mesmo timeline_id e o mesmo origin_unix_ms entre os dois processos para manter a ordem relativa dos eventos
  • o bridge passou a registrar eventos como ready_sent, dispatch_started, agent_join, client_audio_enabled, done_packet_received e call_end
  • o agent passou a registrar eventos como user_transcript_final, pipeline_run_started, pipeline_run_completed, tts_stage_started, interrupt_marked, finalize_started e finalize_completed
  • o provider de STT agora registra etapas de reconhecimento (stt_recognize_started, stt_vosk_completed, stt_http_completed)
  • o backend remoto por websocket agora registra remote_agent_request e remote_agent_response
• Risco conhecido:
  • a timeline registra payloads de request do backend remoto, o que aumenta a verbosidade e pode expor dados sensiveis em ambiente de debug
  • o arquivo jsonl e compartilhado entre dois processos locais; o uso atual com flock e suficiente para dev/homologacao, mas nao substitui observabilidade centralizada
• Validacao executada:
  • py_compile dos arquivos alterados
  • teste unitario novo de timeline
  • execucao completa da suite unittest
• Proximo passo:
  • decidir se a timeline deve continuar sempre habilitada em dev ou ficar atras de flag por ambiente
  • se a homologacao exigir, adicionar visualizador simples da timeline no cliente web

Entrada 009 - Fake remoto para homologacao via UI

• Data: 2026-03-30
• Objetivo: permitir testar o fluxo STT -> remote_ws -> TTS pela UI mesmo sem o agent remoto real estar de pe
• Arquivos alterados:
  • app/ws_gateway/fake_remote_agent.py
  • app/ws_gateway/main.py
  • app/ws_gateway/voice_client.html
  • app/livekit/adapters/backend_factory.py
  • tests/ws_gateway/test_fake_remote_agent.py
  • tests/livekit/test_remote_agent_ws_adapter.py
  • docs/api-overview.md
  • docs/refactor-log.md
• Comportamento preservado:
  • backend remote_ws continua exigindo URL real quando selecionado
  • o contrato do adapter remoto segue o mesmo
• Comportamento alterado:
  • o bridge agora expoe WS /fake-agent/ws
  • a UI ganhou a opcao remote_ws_fake
  • quando remote_ws_fake e selecionado, o agent local aponta para REMOTE_AGENT_WS_FAKE_URL ou usa por padrao ws://127.0.0.1:8000/fake-agent/ws
  • o fake responde nos contratos conta e generico, com progressao simples de stages e encerramento por palavras-chave como encerrar, obrigado e tchau
• Risco conhecido:
  • o fake nao simula comportamento de negocio real; ele serve apenas para homologacao tecnica do fluxo de voz
  • o fake e stateless por conexao, entao a progressao depende do stage enviado pelo agent local
• Validacao executada:
  • testes unitarios do fake remoto
  • testes do backend fake no adapter remoto
  • execucao completa da suite unittest
• Proximo passo:
  • se a homologacao pedir cenarios mais realistas, adicionar scripts por agent (conta, oferta, cobranca) com respostas configuraveis

Template de nova entrada

• Data:
• Objetivo:
• Arquivos alterados:
• Comportamento preservado:
• Comportamento alterado:
• Risco conhecido:
• Validacao executada:
• Proximo passo:

Entrada 010 - Correcao do roteamento remote_ws_fake

• Data: 2026-03-30
• Objetivo: garantir que a selecao remote_ws_fake na UI nao seja sobrescrita pela URL real configurada em REMOTE_AGENT_WS_URL
• Arquivos alterados:
  • app/livekit/adapters/backend_factory.py
  • app/livekit/adapters/remote_agent_ws_adapter.py
  • tests/livekit/test_remote_agent_ws_adapter.py
  • docs/api-overview.md
  • docs/refactor-log.md
• Comportamento preservado:
  • remote_ws continua usando REMOTE_AGENT_WS_URL
  • o adapter remoto continua sendo o mesmo para backend real e fake
• Comportamento alterado:
  • remote_ws_fake agora prioriza sempre REMOTE_AGENT_WS_FAKE_URL, mesmo quando REMOTE_AGENT_WS_URL existe no ambiente
  • a timeline do adapter remoto agora diferencia backend=remote_ws_fake de backend=remote_ws
• Risco conhecido:
  • aliases como fake_remote_ws e ws_fake continuam sendo tratados como remote_ws_fake, mas o label emitido na timeline fica canonico como remote_ws_fake
• Validacao executada:
  • python3 -m unittest tests.livekit.test_remote_agent_ws_adapter -v
  • python3 -m py_compile app/livekit/adapters/backend_factory.py app/livekit/adapters/remote_agent_ws_adapter.py tests/livekit/test_remote_agent_ws_adapter.py
• Proximo passo:
  • validar na chamada real da UI que o timeline e o request usam ws://127.0.0.1:8000/fake-agent/ws

Entrada 011 - Reorganizacao da raiz e remocao de boilerplate

• Data: 2026-04-06
• Objetivo: consolidar a estrutura real do projeto na raiz do repositorio, mantendo src/app e src/agent como codigo-fonte canonico
• Arquivos alterados:
  • README.md
  • makefile
  • Dockerfile
  • pytest.ini
  • .env.example
  • .gitignore
  • .dockerignore
  • requirements.txt
  • livekit.yaml
  • docs/*
  • tests/*
  • k8s/deployment.yaml
  • remocao de pyproject.toml, uv.lock, README copy.md, configs/config.example.yaml e scripts herdados do boilerplate
• Comportamento preservado:
  • src/app e src/agent permanecem como raiz do codigo de execucao
  • o bridge FastAPI continua em src/app/ws_gateway/main.py
  • o projeto continua usando PYTHONPATH=src
• Comportamento alterado:
  • a raiz do repositorio passa a refletir o projeto real, e nao mais o boilerplate original
  • requirements.txt passa a ser a fonte principal de dependencias
  • artefatos de runtime (logs, timeline, __pycache__) deixam de ser versionados
• Risco conhecido:
  • arquivos de infra legados fora do fluxo principal ainda poderiam carregar suposicoes antigas do boilerplate
  • a migracao para requirements.txt simplifica a operacao, mas remove o lockfile anterior
• Validacao executada:
  • python3 -m compileall src tests
  • python3 -m pytest tests/utils/test_call_timeline.py -q
• Proximo passo:
  • revisar a infra auxiliar restante e reduzir ruido operacional na raiz

Entrada 012 - Simplificacao do compose local de observabilidade

• Data: 2026-04-06
• Objetivo: transformar o docker-compose.yml em uma stack minima e coerente para Langfuse local
• Arquivos alterados:
  • docker-compose.yml
• Comportamento preservado:
  • a stack opcional de Langfuse continua disponivel para uso local
  • a aplicacao principal segue fora do compose, operada via make
• Comportamento alterado:
  • remocao do servico mongo
  • consolidacao apenas de langfuse-web, langfuse-worker, postgres, redis, clickhouse e minio
  • reducao de duplicacao com anchors para configuracoes compartilhadas
• Risco conhecido:
  • o compose continua sendo opcional e depende de configuracao explicita do projeto para apontar para Langfuse self-hosted
• Validacao executada:
  • validacao sintatica do YAML com parser local
• Proximo passo:
  • se a equipe mantiver uso frequente, considerar alvos dedicados no makefile para subir e derrubar a stack

Entrada 013 - Provider TTS opcional desacoplado do import global

• Data: 2026-04-06
• Objetivo: impedir que a falta do SDK do ElevenLabs quebrasse o import do modulo inteiro de TTS
• Arquivos alterados:
  • src/app/providers/tts.py
  • tests/providers/test_tts.py
• Comportamento preservado:
  • selecao de provider TTS por configuracao
  • suporte aos providers ja existentes
• Comportamento alterado:
  • o SDK do ElevenLabs deixa de ser carregado no topo do modulo e passa a ser resolvido sob demanda
  • ausencia do SDK passa a gerar missing_elevenlabs_sdk, em vez de falha de import que derruba testes e providers nao relacionados
• Risco conhecido:
  • o provider continua opcional, mas a disciplina de dependencias ainda segue concentrada em requirements.txt
• Validacao executada:
  • python3 -m pytest tests/providers/test_tts.py -q
  • python3 -m pytest tests/adapters/test_azure_tts.py -q
• Proximo passo:
  • continuar removendo acoplamentos desnecessarios entre providers e entrypoints

Entrada 014 - Remocao de mocks e hardcodes dos pipelines de texto

• Data: 2026-04-06
• Objetivo: tirar codigo de demonstracao do caminho produtivo dos endpoints de texto
• Arquivos alterados:
  • src/app/services/session_context.py
  • src/app/services/text_pipeline.py
  • src/app/services/text_pipeline_stream.py
  • src/app/ws_gateway/main.py
  • tests/services/test_session_context.py
• Comportamento preservado:
  • os endpoints /ws/text e /ws/text_stream continuam aceitando a mesma sessao de entrada
  • os pipelines continuam recebendo mailing e intro
• Comportamento alterado:
  • remocao do uso de app.models.mock
  • remocao de protocolo e dados fixos hardcoded nos pipelines
  • introducao de extracao explicita de protocolo via session_context
• Risco conhecido:
  • se existiam fluxos de dev que dependiam dos mocks antigos, eles passam a precisar de payloads reais
• Validacao executada:
  • python3 -m pytest -q
  • resultado observado na etapa: 36 passed
• Proximo passo:
  • consolidar contratos duplicados entre gateway e runtime

Entrada 015 - Unificacao de call_config

• Data: 2026-04-06
• Objetivo: eliminar duplicacao entre as implementacoes de call_config do gateway e do runtime LiveKit
• Arquivos alterados:
  • src/app/common/call_config.py
  • src/app/ws_gateway/call_config.py
  • src/app/livekit/call_config.py
  • tests/config/test_call_config.py
• Comportamento preservado:
  • API publica de build_call_config(...)
  • API publica de normalize_call_config(...) e resolucao dos campos auxiliares
• Comportamento alterado:
  • a normalizacao passa a ter um nucleo compartilhado em src/app/common/call_config.py
  • ws_gateway e livekit viram wrappers leves para o mesmo contrato
• Risco conhecido:
  • qualquer evolucao futura de call_config passa a ter impacto compartilhado entre bridge e agent, o que e desejado, mas exige disciplina de compatibilidade
• Validacao executada:
  • python3 -m pytest tests/config/test_call_config.py -q
  • python3 -m pytest -q
  • resultado observado na etapa: 36 passed
• Proximo passo:
  • iniciar a quebra incremental do monolito em src/app/ws_gateway/main.py

Entrada 016 - Extracao do parsing inicial da sessao no bridge

• Data: 2026-04-06
• Objetivo: remover do ws_gateway/main.py a logica de parsing da mensagem start, resolucao de mailing e montagem de intro/nudge
• Arquivos alterados:
  • src/app/ws_gateway/session_start.py
  • src/app/ws_gateway/main.py
  • tests/ws_gateway/test_session_start.py
• Comportamento preservado:
  • contrato de primeira mensagem type=start
  • geracao de mailing, intro e nudge
  • construcao do contexto do agente remoto a partir de metadata + mailing
• Comportamento alterado:
  • criacao da dataclass StartSessionContext
  • centralizacao de parse_start_payload, recv_start_message e build_remote_agent_context em modulo proprio
  • /ws/agent, /ws/text e /ws/text_stream passam a consumir um contexto estruturado, e nao uma tuple solta
• Risco conhecido:
  • o contrato de entrada continua dependente do payload do cliente; a extracao melhora testabilidade, mas nao redefine o protocolo
• Validacao executada:
  • python3 -m compileall src/app/ws_gateway src/app/services tests/ws_gateway
  • python3 -m pytest tests/ws_gateway/test_session_start.py -q
  • python3 -m pytest -q
  • resultado observado na etapa: 39 passed
• Proximo passo:
  • extrair o bootstrap da chamada para reduzir ainda mais a responsabilidade do endpoint

Entrada 017 - Extracao do bootstrap da chamada do bridge

• Data: 2026-04-06
• Objetivo: separar a preparacao da chamada do runtime do endpoint /ws/agent
• Arquivos alterados:
  • src/app/ws_gateway/session_bootstrap.py
  • src/app/ws_gateway/main.py
  • tests/ws_gateway/test_session_bootstrap.py
• Comportamento preservado:
  • geracao de token de acesso ao LiveKit
  • montagem de call_config, remote_agent_context, timeline e dispatch_metadata
  • fallbacks de protocolo e telefone
• Comportamento alterado:
  • introducao da dataclass BridgeSessionBootstrap
  • centralizacao de room_name, identity, token, protocol, phone_number e dispatch_metadata em um builder dedicado
  • main.py passa a consumir um pacote pronto de bootstrap
• Risco conhecido:
  • o bootstrap ainda depende de envs e factories externas; a extracao organiza responsabilidade, mas nao muda a politica de configuracao
• Validacao executada:
  • python3 -m compileall src/app/ws_gateway tests/ws_gateway
  • python3 -m pytest tests/ws_gateway/test_session_bootstrap.py -q
  • python3 -m pytest -q
  • resultado observado na etapa: 41 passed
• Proximo passo:
  • extrair o ciclo de vida da sessao LiveKit do endpoint

Entrada 018 - Extracao do lifecycle da sessao LiveKit no bridge

• Data: 2026-04-06
• Objetivo: remover do endpoint os handlers de participante, o processamento do pacote DONE e o watcher de encerramento
• Arquivos alterados:
  • src/app/ws_gateway/session_lifecycle.py
  • src/app/ws_gateway/main.py
  • tests/ws_gateway/test_session_lifecycle.py
• Comportamento preservado:
  • deteccao de entrada e saida do agente remoto
  • processamento do pacote agent.stage com DONE
  • envio de stop para o cliente ao final da chamada
• Comportamento alterado:
  • criacao de RoomLifecycleState para concentrar agent_participant e done_payload
  • extracao de register_room_lifecycle_handlers(...)
  • extracao de watch_call_done(...)
• Risco conhecido:
  • o fluxo ainda depende de coordenacao concorrente entre tasks do bridge; a extracao reduz tamanho do endpoint, mas nao muda o modelo de concorrencia
• Validacao executada:
  • python3 -m compileall src/app/ws_gateway tests/ws_gateway
  • python3 -m pytest tests/ws_gateway/test_session_lifecycle.py -q
  • python3 -m pytest -q
  • resultado observado na etapa: 43 passed
• Proximo passo:
  • extrair a camada de intro/sinalizacao do bridge

Entrada 019 - Extracao da intro TTS e da sinalizacao de audio no bridge

• Data: 2026-04-07
• Objetivo: isolar do endpoint o trecho responsavel por intro TTS, liberacao do audio do cliente, sinalizacao client_audio_enabled e bootstrap do streaming do agente
• Arquivos alterados:
  • src/app/ws_gateway/session_audio.py
  • src/app/ws_gateway/main.py
  • tests/ws_gateway/test_session_audio.py
• Comportamento preservado:
  • intro sintetizada antes da liberacao do audio do cliente
  • emissao do controle client_audio_enabled para o agente
  • inicializacao do worker que consome audio do agente quando ele fica pronto
• Comportamento alterado:
  • extracao de play_intro_to_client(...)
  • extracao de notify_client_audio_enabled(...)
  • extracao de stream_agent_audio_when_ready(...)
  • main.py passa a gerenciar explicitamente a task t_control, em vez de disparar a notificacao como fire-and-forget
  • ajuste de typing para evitar import-time acidental de audioop em testes unitarios do modulo novo
• Risco conhecido:
  • o caminho quente de audio continua centralizado em main.py; ainda faltam as primitivas de transporte para o arquivo deixar de ser monolitico
• Validacao executada:
  • python3 -m compileall src/app/ws_gateway tests/ws_gateway
  • python3 -m pytest tests/ws_gateway/test_session_audio.py -q
  • python3 -m pytest -q
  • resultado observado na etapa: 46 passed
• Proximo passo:
  • extrair as primitivas de transporte de audio e LiveKit (ws_audio_receiver, publish_queue_to_livekit, connect_publish_livekit, stream_agent_audio_to_queue)

Entrada 020 - Validacao do Dockerfile para CI/CD

• Data: 2026-04-07
• Objetivo: revisar o Dockerfile frente ao layout atual do projeto e corrigir o principal risco de compatibilidade para pipeline
• Arquivos alterados:
  • Dockerfile
• Comportamento preservado:
  • execucao do bridge via uvicorn app.ws_gateway.main:app
  • exposicao da porta 8000
  • PYTHONPATH=/app/src
  • healthcheck em /health
• Comportamento alterado:
  • troca da base de python:3.13-slim para python:3.12-slim
  • o ajuste foi necessario porque o projeto ainda depende de audioop em src/app/ws_gateway/main.py e src/app/utils/background.py
• Risco conhecido:
  • o build real da imagem nao conseguiu ser concluido nesta maquina porque nem o daemon Docker nem a conexao efetiva do Podman estavam operacionais no momento da validacao
  • portanto, a validacao foi estrutural e de coerencia do arquivo, nao um smoke test completo de container
• Validacao executada:
  • revisao manual de Dockerfile, .dockerignore, requirements.txt, makefile e k8s/deployment.yaml
  • tentativa de docker build, bloqueada por daemon indisponivel
  • tentativa de podman build, bloqueada por conexao local com a VM do Podman
• Proximo passo:
  • executar um build real da imagem assim que houver runtime de containers disponivel no host ou direto no pipeline