cristiano.hoshikawa/tia_regional_xai_tts_pool
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
Cristiano Hoshikawa
2026-08-21 08:37:51 -03:00
commit 881a99b0a8
214 changed files with 61407 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

728
docs/api-overview.md Normal file
View File

@@ -0,0 +1,728 @@
# API Overview
## Status
Documento vivo. Descreve o estado atual da API e sera atualizado ao longo do refactor.
## O que esta API faz
Esta API implementa um fluxo de voz-to-voz para TIA:
- recebe conexao websocket do cliente
- recebe audio PCM do cliente
- encaminha audio para o agent via LiveKit
- transcreve, processa a pipeline de negocio e sintetiza resposta
- devolve audio para o cliente
- finaliza a chamada e exporta resultado
## Componentes principais
### Bridge
Arquivo principal:
- `app/ws_gateway/main.py`
- `app/ws_gateway/voice_client.html`
Responsabilidades:
- aceitar conexao em `/ws/agent`
- receber `start`
- montar contexto da chamada
- despachar agent para uma room LiveKit
- mandar audio do cliente para LiveKit
- devolver audio do agent para o cliente
- encerrar websocket ao receber `DONE`
- servir um cliente web de teste em `/voice-client`
### Agent
Arquivos principais:
- `app/livekit/main.py`
- `app/livekit/runtime/call_runtime.py`
- `app/livekit/runtime/state.py`
- `app/livekit/runtime/commands.py`
- `app/livekit/runtime/command_executor.py`
- `app/livekit/runtime/scheduler.py`
- `app/livekit/policies/`
- `app/livekit/adapters/`
Responsabilidades:
- entrar na room do LiveKit
- configurar STT, VAD e TTS
- receber transcricao final do usuario
- chamar o backend de IA configurado
- vocalizar resposta
- tratar interrupcao, idle nudge e finalizacao
Organizacao atual:
- `main.py` faz o wiring do agent e das dependencias
- `CallRuntime` coordena o ciclo de vida da chamada
- `CallState` concentra o estado mutavel da sessao
- `commands.py` define os comandos internos para side effects
- `RuntimeCommandExecutor` executa bridge, export, speech, pipeline e start da sessao
- `TimerScheduler` concentra os timers nomeados do runtime
- `InterruptPolicy`, `IdlePolicy` e `FinalizationPolicy` concentram regras operacionais da chamada
- adapters encapsulam acesso ao backend de IA, speech, bridge e export
### Pipeline de negocio
Backends disponiveis no runtime websocket:
- `remote_ws`:
- `app/livekit/adapters/remote_agent_ws_adapter.py`
- `remote_sse`:
- `app/livekit/adapters/remote_agent_sse_adapter.py`
Responsabilidades:
- preparar dados de atendimento
- controlar os estagios da chamada ou delegar esse controle ao agent remoto
- gerar a resposta textual por etapa
- registrar metadados e finalizar a conversa
Selecao atual:
- `AGENT_BACKEND=remote_ws` envia cada turno transcrito para `REMOTE_AGENT_WS_URL`
- `AGENT_BACKEND=remote_sse` usa contratos especificos por agente:
- `conta` usa `GET /agent/sse` para inicializar a sessao e `POST /agent/sse` para executar cada acao
- `oferta` usa `POST /agent/execute` por turno e consome os eventos SSE `schedule_message`, `message` e `done`
- `AGENT_BACKEND=remote_ws_fake` usa um fake interno no proprio processo, sem abrir websocket local
- o fluxo do runtime local continua o mesmo: STT produz texto, o backend de IA devolve texto e o TTS vocaliza
- o roteamento entre agentes acontece pelo campo `data.agent`
- quando `AGENT_BACKEND=remote_ws`, o adapter escolhe a URL por `agent` se existirem:
- `REMOTE_AGENT_WS_URL_CONTA`
- `REMOTE_AGENT_WS_URL_OFERTA`
- `REMOTE_AGENT_WS_URL_COBRANCA` ou `REMOTE_AGENT_WS_URL_COBRA`
- quando `AGENT_BACKEND=remote_sse`, o adapter exige a URL especifica do `agent`, sem fallback generico:
- `REMOTE_AGENT_SSE_URL_CONTA`
- `REMOTE_AGENT_SSE_URL_OFERTA`
- `REMOTE_AGENT_SSE_URL_COBRANCA` ou `REMOTE_AGENT_SSE_URL_COBRA`
Contrato remoto atual por turno:
- `timestamp`
- `agent`
- `RouterCallKeyDay`
- `RouterCallKey`
- `ANI`
- `GSM`
- `callIdGed`
- `ID_FATURA` somente para `agent=conta`
- `text`
- `protocol`
- `stage`
Contrato especifico atual de `conta`:
- request:
- na abertura da sessao, o transporte envia query string com `ani`, `channelId` e `uraCallId`
- `action: "chat"`
- `payload.message`
- `payload.message_id` no transporte SSE de `conta`, com o mesmo UUID enviado na query string
- `payload.channel` no transporte websocket
- `payload.interruption` e `payload.events` quando existirem
- response:
- `type: "ready"` para a primeira fala ou fala que abre uma janela de resposta do cliente
- a fala de `ready` nao e interrompivel; se o cliente falar enquanto o audio do `ready` ainda estiver tocando, a transcricao e descartada e registrada em log
- apos o fim do audio de `ready`, o runtime mantem uma janela protegida de 750ms para absorver atraso de playback do cliente; fala iniciada nessa janela tambem e descartada
- depois dessa janela protegida, o runtime passa a esperar resposta do cliente
- `type: "result"`
- `action: "chat"`
- `result.type: "final"` para respostas intermediarias
- `result.content` como texto para TTS
- `type: "feedback"` ou `result.type: "feedback"` para mensagens de acompanhamento enquanto o backend continua processando o turno atual
- a fala de `feedback` nao e interrompivel, nao abre novo turno, nao espera resposta do cliente e nao arma timeout de silencio do cliente
- se o cliente falar durante `feedback`, o runtime descarta a transcricao, registra a tentativa em log e continua aguardando a resposta final do backend
- `feedback` nao dispara `metadata.wait_retry_messages`, como mensagens do tipo "Voce esta ai?"
- para finalizacoes esperadas, o runtime aguarda uma janela curta de silencio estavel do cliente, fala o `result.content` e depois envia `stop`; se uma nova transcricao final chegar durante a espera, a finalizacao anterior e descartada em favor do novo turno
- falas de finalizacao esperada (`resolvido`, `nao_resolvido`, `erro_no_match` etc.) nao sao interrompiveis; qualquer fala do cliente durante a finalizacao e descartada
- nesses casos o runtime nao chama finalizacao remota adicional (`end`/`end_service_once`)
- quando o `ready` vier com `metadata.wait_timeout_seconds`, o runtime aguarda esse tempo apos falar a mensagem de `ready`
- se tambem vier `metadata.wait_retry_messages`, o runtime fala cada item do array a cada novo estouro de `wait_timeout_seconds`; depois do ultimo item, aguarda mais um intervalo igual e envia
`stop_silencio_longo` com `reason: "no_user_response"`
- sem `metadata.wait_retry_messages`, o comportamento continua sendo encerrar direto no primeiro estouro de `wait_timeout_seconds`
- enquanto aguarda processamento depois do fim de fala do usuario, o runtime toca somente o audio local longo de conforto; no padrao atual, usa intervalo de 12s e no maximo 6 vezes
- se a resposta do backend remoto nao chegar em 300s, o runtime encerra com `stop_agent_backend_unavailable`
- se o participante do agent LiveKit desconectar sem `DONE`, o bridge tenta redispatch na mesma room; se o agent nao voltar, encerra com `stop_agent_runtime_unavailable`
Mapeamento de finalizacoes esperadas de `conta`:
- `result.type: "resolvido"` -> `stop_resolvido_e_finalizado`
- `result.type: "nao_resolvido"` -> `stop_nao_resolvido`
- `result.type: "resolvido_outros_assuntos"` -> `stop_outro_assunto`
- `result.type: "outros_assuntos"` -> `stop_outro_assunto`
- `result.type: "erro_falha_sistema"` -> `stop_falha_sistema`
- `result.type: "erro_no_match"` -> `stop_no_match`
Contrato SSE atual de `conta`:
- o runtime guarda o `session_id` retornado pelo backend nos eventos `ready`
- abre `GET /agent/sse?msisdn=...&invoice_id=...&ani=...&protocol_id=...&session_id=...&message_id=...&channelId=ura&uraCallId=...` no `prepare`
- consome o stream de inicializacao ate `ready` e ate o termino do prefetch (`prefetch_done`, `prefetch_skipped` ou `prefetch_failed`) ou fechamento da resposta
- envia cada turno com `POST /agent/sse?session_id=...&ani=...&protocol_id=...&message_id=...&channelId=ura&uraCallId=...`
- `message_id` e um UUID gerado por turno e independente de `session_id`; nos turnos de acao, `session_id` continua sendo o identificador de sessao retornado pelo backend de contas
- body do `POST`:
- `action: "chat"`
- `payload.message`
- `payload.message_id` com o mesmo UUID do parametro `message_id` da query string
- `payload.interruption` e `payload.events` quando existirem
- a resposta do proprio `POST` e `text/event-stream`; o runtime consome `ready`, `progress`, `result` e `error` ate receber o resultado da acao
Contrato SSE atual de `oferta`:
- `prepare` nao abre stream remoto; o primeiro turno do agente chama `POST /agent/execute`
- o turno inicial envia `message: "inicio_atendimento"` para o backend remoto produzir a primeira fala
- cada turno usa body:
- `messageId` gerado por turno como UUID
- `message` com `inicio_atendimento` no primeiro turno ou a transcricao do cliente nos demais
- `context.protocolNumber` e `context.protocolo` vindos de `data.protocolo`
- `context.gsm` vindo de `data.gsm`
- `context.uraId` vindo de `data.callIdGed`
- `context.callIdGed`, `context.ani`, `context.routerCallKey`, `context.routerCallKeyDay`, `context.agent` e `context.assetId` quando existirem
- `context.sessionId` e enviado a partir de `data.session_id`/`data.sessionId` recebido no `start`; protocolo, `callIdGed` e `routerCallKey` nao sao usados como fallback de `sessionId`
- headers enviados: `Accept: text/event-stream`, `Content-Type: application/json` e `Channel-id` vindo de `channelId` ou `ura`
- eventos recebidos:
- `schedule_message`: fala imediatamente `scheduledMessage.message`
- `message`: fala `response`
- `done`: encerra o stream do turno; a chamada so e finalizada quando o status recebido indicar encerramento terminal
- de/para do `done.additionalInformations.service_status`:
- `RESOLVED` -> `stop_resolvido_e_finalizado`
- `UNRESOLVED` ou ausente -> `stop_nao_resolvido`
- `RESOLVED_WITH_NEW_REQUEST` -> nao envia `stop`; a conversa permanece aberta para o novo assunto
- `done.status=transferred` e reconhecido, mas ainda nao orquestra transferencia; nesta versao encerra como nao resolvido e preserva metadados de handover para evolucao futura
Endpoint dev fornecido para `oferta`:
- host: `https://agt-ai-atendimento-ofertas-dev.internal.timbrasil.com.br`
- execute: `https://agt-ai-atendimento-ofertas-dev.internal.timbrasil.com.br/agent/execute`
- health: nao configurado por enquanto; a readiness nao deve derivar nem chamar `/health` para oferta ate essa rota ser fornecida
- enquanto o certificado interno nao estiver confiavel no ambiente local, `REMOTE_AGENT_SSE_TLS_VERIFY_OFERTA=0` permite testar o fluxo ignorando a validacao TLS do `httpx`
- pod de referencia: `tim-ai-atend-agnt-sales-65764fcf8d-xpzmb`
- IP de referencia: `http://10.153.35.23`
- portas: `80:31332/TCP`, `443:30635/TCP`
Origem desses campos:
- o bridge extrai esses valores do `data` recebido em `WS /ws/agent`
- o agent local apenas reaproveita esse contexto para chamar o websocket remoto
- `protocol`/`protocolo` e identificador de negocio; `session_id` e identificador explicito de sessao recebido no `start`. O runtime nao preenche `session_id` com protocolo, `callIdGed` ou `routerCallKey`.
Configuracao opcional por chamada:
- o cliente pode enviar `callConfig` no `start`, mas esse bloco e opcional
- objetivo atual: testes, homologacao e overrides tecnicos por sessao
- `callConfig.agentBackend` faz override do backend websocket para aquela chamada
- `callConfig.agentBackend` tambem pode selecionar o transporte SSE para a sessao
- `callConfig.stt` pode ajustar `provider`, `initialPrompt`, `configOverride` e `minProbSingleWord`
- `callConfig.tts` pode ajustar `provider`, `voiceId` e `modelId`
- valores aceitos hoje em `callConfig.agentBackend`:
- `remote_ws`
- `remote_sse`
- `remote_ws_fake`
- hoje os providers suportados no agent local sao:
- STT: `internal_http` (`Sofya Batch` no cliente de teste), `fake`
- TTS: `elevenlabs`, `azure`, `xai`, `fake`
## Endpoints atuais
### `GET /health`
Retorna status simples de saude do bridge.
### `GET /health/resources`
Retorna o deep health do bridge com validacao dos recursos usados pelo `WS /ws/agent`.
Comportamento:
- `200` quando os checks obrigatorios estao saudaveis
- `503` quando algum recurso obrigatorio falha
- inclui `active_connections`, `max_connections`, `cached`, `failed_resources` e `checks`
- os checks atuais cobrem:
- `agent_runtime`
- `agent_backend`
- `stt`
- `tts`
### `GET /health/services`
Retorna o health consolidado dos servicos do TIA no formato consumido pela esteira de operacao.
Comportamento:
- `200` quando todos os servicos monitorados estao saudaveis
- `503` quando algum servico monitorado falha
- `status` no corpo retorna `ok` ou `fail`
- `htp_cod_status` preserva o status HTTP retornado pelo health do servico quando houver resposta HTTP
- `hhtp_cod_desc` preserva a descricao retornada pelo health quando houver; se nao houver descricao no corpo, usa a reason phrase HTTP
- ignora `AGENT_BACKEND=remote_ws_fake` e usa as rotas reais configuradas nos envs dos servicos
- `checks` cobre apenas os servicos atualmente monitorados:
- `agent_runtime`
- `agent_backend.contas`: `REMOTE_AGENT_HEALTH_URL_CONTA`, `REMOTE_AGENT_HEALTH_URL_CONTAS` ou `REMOTE_AGENT_HEALTH_URL`
- `agent_backend.oferta`: `REMOTE_AGENT_HEALTH_URL_OFERTA`, `REMOTE_AGENT_HEALTH_URL_OFERTAS` ou health derivado de `REMOTE_AGENT_SSE_URL_OFERTA`
- `stt.sofya`: `STT_HEALTH_URL` ou health derivado de `STT_URL`
- `tts.xAI`: provider xAI com `XAI_WEBSOCKET_URL`/`XAI_API_KEY`
Para checks sem resposta HTTP, como falha de conexao ou probe por WebSocket, a rota usa fallback `200`/`500` e a mensagem interna do erro ou sucesso.
Formato:
```json
{
"status": "ok",
"checks": {
"agent_runtime": {
"htp_cod_status": 200,
"hhtp_cod_desc": "SUCCESS"
},
"agent_backend": {
"contas": {
"htp_cod_status": 200,
"hhtp_cod_desc": "SUCCESS"
},
"oferta": {
"htp_cod_status": 200,
"hhtp_cod_desc": "SUCCESS"
}
},
"stt": {
"sofya": {
"htp_cod_status": 200,
"hhtp_cod_desc": "SUCCESS"
}
},
"tts": {
"xAI": {
"htp_cod_status": 200,
"hhtp_cod_desc": "SUCCESS"
}
}
}
}
```
### `GET /voice-client`
Cliente web de teste para capturar microfone, enviar audio para `WS /ws/agent`,
reproduzir o audio do agent e configurar `STT`, `TTS` e `AGENT` por chamada.
### `WS /fake-agent/ws`
Websocket fake para homologacao local do backend remoto.
Uso esperado:
- usar apenas para homologacao manual do contrato websocket fake
- manter `agent=conta|oferta|cobranca`
- deixar um cliente websocket externo chamar o fake diretamente quando precisar testar esse endpoint
Comportamento:
- suporta o contrato `conta` com `action/payload`
- suporta o contrato generico com `text/stage`
- responde com progressao simples de stages
- encerra quando recebe textos como `encerrar`, `obrigado` ou `tchau`
### `WS /ws/agent`
Fluxo principal de voz:
1. cliente conecta
2. envia mensagem `start`
3. bridge valida capacidade e readiness dos recursos obrigatorios
4. recebe `ready` ou `stop`
5. se receber `ready`, envia audio binario
6. recebe audio binario de resposta
7. recebe `stop` ao fim da chamada ou em falha terminal
Contrato de inicio da chamada `type=start`:
- a primeira mensagem de inicio deve ser um JSON textual com `type: "start"`; opcionalmente, `transferencia_session_id` pode chegar antes dela para informar somente o `session_id`
- os campos de negocio devem ser enviados em `data`
- chaves canonicas obrigatorias em `data`:
- `agent`
- `ani`
- `gsm`
- `session_id`
- `routerCallKey`
- `routerCallKeyDay`
- `callIdGed`
- chaves obrigatorias por agente:
- `agentData.idFatura` quando `agent=conta`
- `protocolo` quando `agent=oferta`
- valores canonicos recomendados para `agent`:
- `conta`
- `oferta`
- `cobranca`
Exemplo recomendado de `start` para `conta`:
```json
{
"type": "start",
"data": {
"agent": "conta",
"ani": "5511999990000",
"gsm": "5511999990000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"routerCallKeyDay": "20260409",
"routerCallKey": "RCK-001",
"callIdGed": "GED-123456",
"agentData": {
"idFatura": "FAT-123"
}
},
"audioFormat": {
"encoding": "linear16",
"sampleRateHz": 16000,
"channels": 1
},
"callConfig": {
"agentBackend": "remote_ws"
}
}
```
Exemplo recomendado de `start` para `oferta`:
```json
{
"type": "start",
"data": {
"agent": "oferta",
"ani": "5511999990000",
"gsm": "5511999990000",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"routerCallKeyDay": "20260409",
"routerCallKey": "RCK-001",
"callIdGed": "GED-123456",
"protocolo": "PRT-20260409-0001"
},
"audioFormat": {
"encoding": "linear16",
"sampleRateHz": 16000,
"channels": 1
},
"callConfig": {
"agentBackend": "remote_sse"
}
}
```
Mensagem opcional aceita antes do `start` em cenarios de transferencia:
```json
{
"type": "transferencia_session_id",
"data": {
"session_id": "550e8400-e29b-41d4-a716-446655440000"
}
}
```
Se essa mensagem chegar antes do `start`, o bridge usa esse valor apenas para preencher `data.session_id` quando o `start` ainda nao trouxer o campo. Em producao, o caminho recomendado e enviar `session_id` diretamente dentro de `data` no `start`.
Contrato de audio:
- apos o `ready`, o cliente deve enviar audio binario bruto em `PCM16/LINEAR16`, `16000 Hz`, `1 canal`
- o `ready` informa os parametros operacionais atuais do bridge:
- `session_id`: eco do `data.session_id` aceito para a chamada
- `sample_rate: 16000`
- `channels: 1`
- `frame_ms: 20`
- `bytes_per_frame: 640`
- no contrato atual, `ready` significa que o bridge esta pronto para receber os bytes de audio do cliente
- quando `agent_starts_conversation` esta habilitado, o agent mantem a entrada do usuario desativada no `RoomIO` desde antes do `StartSession` ate o fim da primeira mensagem; esse gate impede que fala ou backlog vindo da URA alcance VAD/STT durante o setup e a saudacao
- o gate e liberado no fim do primeiro turno do agent e tambem em falha do pipeline, finalizacao ou timeout de setup; chamadas em que o usuario inicia a conversa nao usam esse bloqueio
- `audioFormat` no `start` e opcional e hoje funciona como campo informativo/reservado
- enviar outro codec, sample rate ou numero de canais nesse campo nao reconfigura o bridge atualmente
- se houver necessidade de outro formato, homologar com a equipe de desenvolvimento antes da integracao
Mensagens devolvidas pelo servidor:
- `ready` quando a sessao foi aceita e o bridge esta pronto para receber audio
- audio binario PCM16 durante a resposta do agent
- `stop` como mensagem terminal em qualquer encerramento do `WS /ws/agent`
Recuperacao do participante LiveKit do agent:
- quando o participant identificado como agent desconecta e a chamada ainda nao terminou, o bridge faz redispatch do mesmo `AGENT_NAME` na mesma room
- quando o novo participant entra, o bridge reenvia o controle `client_audio_enabled` e passa a consumir o audio desse novo participant
- se o redispatch nao trouxer um novo agent dentro do timeout configurado, o bridge envia `stop_agent_runtime_unavailable` com `reason: "agent_disconnected"`
Contrato de `stop`:
- toda mensagem terminal em `WS /ws/agent` usa:
```json
{
"type": "stop",
"data": {}
}
```
- bloqueio antes do `ready`:
```json
{
"type": "stop",
"data": {
"status": "stop_stt_unavailable",
"reason": "resource_unhealthy",
"resource": "stt",
"failed_resources": ["stt"],
"phase": "pre_ready"
}
}
```
- falha de recurso durante a sessao:
```json
{
"type": "stop",
"data": {
"status": "stop_agent_backend_unavailable",
"reason": "resource_unhealthy",
"resource": "agent_backend",
"failed_resources": ["agent_backend"],
"phase": "in_session"
}
}
```
- fim normal da chamada:
```json
{
"type": "stop",
"data": {
"status": "stop_resolvido_e_finalizado",
"reason": "stage_done",
"phase": "in_session"
}
}
```
- falha terminal durante a sessao:
```json
{
"type": "stop",
"data": {
"status": "stop_bridge_failed",
"reason": "bridge_failed",
"resource": "bridge",
"phase": "in_session"
}
}
```
Status terminais atualmente usados em `WS /ws/agent`:
- `stop_capacity_tia`
- `stop_agent_runtime_unavailable`
- `stop_agent_backend_unavailable`
- `stop_stt_unavailable`
- `stop_tts_unavailable`
- `stop_resolvido_e_finalizado`
- `stop_nao_resolvido`
- `stop_falha_sistema`
- `stop_no_match`
- `stop_outro_assunto`
- `stop_silencio_longo`
- `stop_bridge_failed`
Regra de interpretacao:
- `phase: "pre_ready"` indica bloqueio antes de a sessao aceitar audio
- `phase: "in_session"` indica falha terminal ou encerramento depois do `ready`
- os status de recurso podem aparecer nas duas fases, dependendo de quando a indisponibilidade foi detectada
Campos opcionais de testes e homologacao:
- `audioFormat` pode ser enviado no `start`, mas hoje nao altera o pipeline de audio
- `callConfig` e opcional e existe para testes, smoke test local e homologacao tecnica
- para integracao produtiva com cliente externo, o contrato pode omitir `callConfig`
Configuracao de chamada para teste de carga com STT Sofya, agente fake e TTS xAI:
```json
{
"debugEvents": true,
"callConfig": {
"agentBackend": "remote_ws_fake",
"agentFake": {
"delayMs": 2500,
"responses": "Primeira resposta simulada com tamanho intermediario;Segunda resposta simulada com tamanho intermediario;Resposta final encerrando o atendimento simulado"
},
"stt": {
"provider": "internal_http",
"disableVosk": true
},
"tts": {
"provider": "xai"
}
}
}
```
Regras desse modo:
- `agentFake.responses` contem de 2 a 10 frases separadas por `;`; espacos laterais sao removidos e cada frase deve ter de 40 a 180 caracteres
- `agentFake.delayMs` e aplicado antes de cada resposta, usa `2500` por padrao e aceita valores de `0` a `180000`
- a saudacao inicial continua sendo o `intro` normal; cada fala posterior reconhecida pelo STT consome uma resposta fake, sem usar o texto transcrito para escolher a resposta
- respostas anteriores as duas ultimas usam `ARGUMENTATION`, a penultima usa `FORMALIZATION` e a ultima usa `DONE`; chamadas posteriores ao fim recebem novamente o mesmo resultado terminal
- a sequencia e isolada por sessao
- `debugEvents=true` publica pelo websocket somente eventos tecnicos e valores agregados de fala, STT Sofya, TTS xAI e sheds do Bridge; o conteudo integral da conversa nao e incluido nas metricas
- o endpoint nao possui uma autorizacao adicional especifica para o fake: qualquer cliente ja autorizado a abrir `/ws/agent` pode selecionar `remote_ws_fake` por `callConfig`
### `WS /ws/text`
Fluxo de texto sem audio para testes e integracao basica.
### `WS /ws/text_stream`
Fluxo textual com resposta em streaming.
## Fluxo ponta a ponta atual
1. Cliente abre websocket em `/ws/agent`
2. Bridge recebe `start` e faz parse do contexto da chamada
3. Bridge valida capacidade e readiness dos recursos
4. Bridge cria room/token e envia `ready`
5. Cliente envia audio para o bridge
6. Bridge publica audio no LiveKit
7. Agent recebe audio, STT produz texto
8. Agent chama o backend de IA configurado
9. Agent usa TTS para vocalizar resposta
10. Bridge devolve audio ao cliente
11. Agent sinaliza `DONE` ou ocorre erro terminal
12. Bridge envia `stop` e fecha a chamada
## Dependencias externas relevantes
- LiveKit
- STT interno HTTP
- Vosk
- ElevenLabs
- modelo LLM da pipeline
- API de fidelizacao
## Timeline de chamada
O projeto agora gera uma timeline estruturada por chamada em formato `jsonl`.
Configuracao:
- `CALL_TIMELINE_ENABLED=1` ativa a escrita da timeline
- `CALL_TIMELINE_CONSOLE=1` replica os eventos tambem no stdout
- `CALL_TIMELINE_DIR=./timeline` define o diretorio dos arquivos
- `CALL_TIMELINE_QUEUE_MAX=10000` limita eventos pendentes para escrita assincrona
- `CALL_LOG_QUEUE_MAX=20000` limita registros pendentes dos arquivos por chamada
- `ASYNC_IO_WARNING_INTERVAL_S=60` limita a frequencia dos avisos de descarte/erro
A timeline e o arquivo de log por chamada sao gravados por threads de fundo para
nao executar I/O de disco no event loop de audio. Quando uma fila atinge o limite,
o evento e descartado em vez de bloquear o audio e um warning rate-limited registra
o total acumulado. Os limites aceitos ficam entre `1` e `1000000`.
Os spans estruturados usam `BatchSpanProcessor`: `span.end()` apenas enfileira o
span, enquanto o envio OTLP acontece em lote fora da thread chamadora. O provider
faz flush e shutdown no encerramento normal do processo.
Fake remoto:
- `remote_ws_fake` usa um fake interno em memoria e nao depende de `REMOTE_AGENT_WS_FAKE_URL`
- o endpoint `ws://127.0.0.1:8000/fake-agent/ws` continua disponivel apenas para testes manuais do contrato websocket
Logs de websocket remoto:
- o adapter `remote_ws` agora registra no stdout eventos `REMOTE_AGENT_WS_CONNECT_OPEN`, `REMOTE_AGENT_WS_CONNECT_OK`, `REMOTE_AGENT_WS_REQUEST`, `REMOTE_AGENT_WS_RESPONSE` e falhas `*_FAIL`
- os logs incluem `instance` (hostname/pod), `agent`, `url`, `host`, `stage`, `protocol` e metadados do payload para facilitar comparar pods com erro de DNS/host
Mock de encerramento apos primeiro audio:
- `MOCK_STOP_AFTER_FIRST_AUDIO_ENABLED=1` faz o bridge enviar o `stop` terminal configurado para o `reason` depois que o primeiro audio real do agente for entregue ao cliente e a saida ficar em silencio pelo intervalo configurado
- `MOCK_STOP_AFTER_FIRST_AUDIO_SILENCE_S=0.35` controla quanto tempo de silencio o bridge espera antes de disparar o `stop`
- `MOCK_STOP_AFTER_FIRST_AUDIO_REASON=stage_done` define o `reason` exato enviado no `stop`
Status terminais configuraveis por env:
- `FINAL_STOP_STATUS_RESOLVED=stop_resolvido_e_finalizado`
- `FINAL_STOP_STATUS_UNRESOLVED=stop_nao_resolvido`
- `FINAL_STOP_STATUS_OTHER_SUBJECT=stop_outro_assunto`
- `FINAL_STOP_STATUS_LONG_SILENCE=stop_silencio_longo`
- `FINAL_STOP_DEFAULT_KIND=resolved` define o fallback quando o `reason` nao bater em nenhum valor configurado
- `FINAL_STOP_REASON_RESOLVED=stage_done`
- `FINAL_STOP_REASON_UNRESOLVED=nao_resolvido`
- `FINAL_STOP_REASON_OTHER_SUBJECT=outro_assunto`
- `FINAL_STOP_REASON_LONG_SILENCE=no_user_response`
- o mapeamento agora usa comparacao exata do `reason`, sem aliases
Espera de resposta do backend remoto:
- `REMOTE_AGENT_INFLIGHT_WAIT_INTERVAL_S=12`
- `REMOTE_AGENT_INFLIGHT_WAIT_SHORT_AUDIO_DIR=src/app/livekit/assets/comfort/short`
- `REMOTE_AGENT_INFLIGHT_WAIT_LONG_AUDIO_DIR=src/app/livekit/assets/comfort/long`
- o primeiro audio de conforto usa um WAV aleatorio da pasta `short`; a partir do segundo, usa WAVs aleatorios da pasta `long`
- o intervalo dos audios de conforto conta a partir do fim do audio anterior
- `REMOTE_AGENT_INFLIGHT_WAIT_TIMEOUT_S=180`
- `REMOTE_AGENT_INFLIGHT_WAIT_MAX_NOTICES=0` (`0` mantém os confortos sem limite de quantidade até o timeout)
- `REMOTE_AGENT_INFLIGHT_WAIT_TEXT=Um momento, ainda estou consultando para te ajudar.`
- este timeout e tecnico: limita quanto tempo o runtime aguarda o backend remoto processar um turno
- ele e diferente do timeout de resposta do cliente configurado por `metadata.wait_timeout_seconds`
- mensagens `feedback`, tanto top-level quanto `result.type: "feedback"`, usam a espera tecnica do backend, mas nao contam silencio do cliente nem disparam `metadata.wait_retry_messages`
- em um turno normal, depois que o agent termina de falar e o cliente responde, o fim de fala detectado pelo VAD pode antecipar o primeiro conforto curto enquanto o STT conclui a transcricao
- o conforto antecipado do VAD nao e agendado enquanto o agent esta falando; se outra fala do agent ocupar o `say_lock` depois do agendamento, o conforto tambem e abortado para nao sair colado ao fim da mensagem
- se o cliente interromper uma fala interrompivel do agent, o VAD nao enfileira conforto atras dessa fala; o novo pipeline ainda pode usar os confortos normais caso o processamento demore
- se o cliente falar por mais de `800ms` enquanto o backend ja processa outro turno e o agent esta em silencio, o conforto curto especulativo do VAD e suprimido e a transcricao abre uma interrupcao diferida
- cada interrupcao diferida toca `src/app/livekit/assets/comfort/interruption/01.wav`, correspondente a "Ouvi o que voce falou, um instante", e invalida a resposta anterior quando ela chegar
- no pipeline substituto, o conforto dedicado conta como o primeiro aviso ja consumido: o audio `short` normal nao toca logo depois; se o processamento continuar, o proximo aviso permitido e `long` e respeita o intervalo configurado
- o estado de interrupcao e rearmado antes de iniciar o pipeline substituto: cada nova fala valida durante o novo processamento repete o conforto dedicado e substitui novamente a resposta em voo, sem descartar a nova transcricao nem deixar silencio na chamada
- falas de ate `800ms` durante processamento sao tratadas como ruido ou backchannel curto e nao abrem interrupcao diferida
- os logs principais desse fluxo sao `pre_backend_wait_notice_skipped` (`agent_speaking` ou `backend_processing`), `deferred_interruption_accumulated`, `deferred_interruption_dispatched` e os estagios TTS `AGENT_BACKEND_WAIT`/`INTERRUPTION_COMFORT`
Recuperacao do participant LiveKit do agent:
- `AGENT_RECONNECT_ENABLED=1`
- `AGENT_RECONNECT_MAX_ATTEMPTS=1`
- `AGENT_RECONNECT_TIMEOUT_S=10`
Protecao de reenvio TTS:
- `TTS_EMPTY_FRAME_RETRY_TIMEOUT_S=3` interrompe uma tentativa de TTS sem primeiro frame de audio ou com gap entre frames no meio da fala apos o timeout e reenvia o mesmo texto uma vez
- antes do reenvio, toca `src/app/livekit/assets/comfort/fails/tts_fail_recovery.wav`
- quando o reenvio tem sucesso, registra um unico `envio msg` com `http_cod_status=200` e `erro_msg=TTS_regerado`
STT fake:
- `STT_PROVIDER=fake` dispensa `STT_URL`
- usa `FAKE_STT_TRANSCRIPTS` como fila de falas por turno
- `FAKE_STT_MODE=repeat_last|cycle` controla o comportamento ao consumir a fila
TTS fake:
- `TTS_PROVIDER=fake` dispensa credenciais externas
- gera audio PCM sintetico local para smoke tests do pipeline
Formato:
- um arquivo por chamada
- nome do arquivo baseado no `room`
- eventos do `bridge` e do `agent` entram no mesmo arquivo
- cada linha contem:
- `ts`
- `t_rel_ms`
- `component`
- `event`
- `protocol`
- `room`
- campos especificos do evento
Eventos relevantes:
- `bridge`:
- `call_start`
- `ready_sent`
- `dispatch_started`
- `livekit_room_connected`
- `agent_join`
- `client_audio_first_frame_received`
- `client_audio_first_frame_published`
- `client_audio_enabled`
- `done_packet_received`
- `stop_sent`
- `call_end`
- `agent`:
- `call_start`
- `room_enter`
- `session_start_requested`
- `stt_recognize_started`
- `stt_http_completed`
- `user_transcript_final`
- `pipeline_run_started`
- `pipeline_run_completed`
- `remote_agent_request`
- `remote_agent_response`
- `tts_stage_started`
- `tts_stage_result`
- `interrupt_marked`
- `finalize_started`
- `finalize_completed`
Uso pratico:
1. iniciar a chamada normalmente
2. identificar no terminal o `room` ou o `protocol`
3. abrir o arquivo correspondente em `./timeline`
4. ler os eventos em ordem de `t_rel_ms`
## Ponto de atencao
Durante o refactor, este documento deve continuar descrevendo:
- comportamento publico
- contrato do websocket
- responsabilidades de cada camada
Na versao final, ele deve evoluir para a documentacao oficial da API.