first commit

README_BACKOFFICE_CONVERTIDO_100.md

@@ -0,0 +1,156 @@
+# Backoffice TIM/ANATEL convertido para o Agent Framework — versão 100% de paridade
+
+Esta versão foi gerada a partir de dois insumos:
+
+- `tim-ai-atend-agnt-backoffice(3).zip`: branch `develop` do backoffice original.
+- `backoffice_convertido_framework(2).zip`: primeira versão convertida para o framework.
+
+## O que mudou
+
+A versão anterior tinha uma implementação genérica de `BackofficeAgent` com MCP tools e endpoints de compatibilidade simplificados. Esta versão preserva os fluxos reais da branch `develop` como workflows de domínio dentro da aplicação do framework.
+
+## Camadas mantidas pelo framework
+
+O framework continua responsável por:
+
+- `/gateway/message` e `/gateway/events/{session_id}`.
+- Normalização de canais.
+- `AgentIdentity` e `BusinessContext`.
+- Sessão, memória, checkpoint e uso.
+- `EnterpriseRouter` e modo supervisor.
+- Guardrails de entrada e saída.
+- OutputSupervisor.
+- Judges.
+- Telemetria, IC, NOC e GRL.
+- MCP Tool Router.
+
+## Fluxos originais preservados
+
+O pacote `src/` foi copiado da branch `develop` e preserva os grafos originais:
+
+### Checklist ANATEL
+
+Arquivo: `src/agent/graphs/main_graph.py`
+
+Fluxo preservado:
+
+```text
+fetch_ticket
+ -> validation
+ -> bypass_rules
+ -> cache_check
+ -> imdb_enrichment
+ -> identity_verification
+ -> speech_enrichment
+ -> knowledge_base_enrichment
+ -> canceling_analysis
+ -> tim_complaint_analysis
+ -> tim_complaint / different_complaint_operator / undefined_complaint_operator
+ -> reclassification_analysis
+ -> treatment_decision
+ -> siebel_sr_opening
+```
+
+### Response Emulator
+
+Arquivo: `src/agent/graphs/emulator_graph.py`
+
+Fluxo preservado:
+
+```text
+start_response_emulation
+ -> fetch_case
+ -> validate_actions
+ -> router
+ -> retrieve_templates
+ -> retrieve_history
+ -> generate_response
+ -> validate_response
+ -> persist_draft
+ -> approve_draft / close_case
+```
+
+## Rotas preservadas do backoffice original
+
+Registradas em `app/main.py`:
+
+```text
+POST /agent/execute
+POST /agent/process-ticket
+POST /agent/process-and-stream
+GET  /agent/search-tais-kb
+POST /case/{transaction_id}/response-emulator/generate
+POST /case/{transaction_id}/response-emulator/finalize
+GET  /case/{transaction_id}/response-emulator
+GET  /emulator-rag/search
+GET  /health/live
+GET  /health/ready
+```
+
+## Serviços TIM preservados
+
+Os clients originais foram preservados em `src/components/clients/`:
+
+```text
+imdb_client.py
+siebel_client.py
+speech_analytics_client.py
+tais_kb_client.py
+abrt_client.py
+portability_client.py
+emulator_rag_client.py
+rag/history_rag_client.py
+rag/templates_rag_client.py
+```
+
+## Prompts preservados
+
+Os prompts originais foram preservados em `src/agent/local_prompts/`:
+
+```text
+canceling_analysis.py
+duplicate_analysis.py
+tim_complaint_analysis.py
+ticket_reclassification.py
+treatment_decision_prompt.py
+speech_history_analysis.py
+preprocess_tais_kb_query.py
+postprocess_tais_kb_query.py
+emulator/response_emulator_generation.py
+anatel_motives/anatel_motives.py
+```
+
+## Guardrails e judges
+
+A configuração do agente backoffice foi reforçada em:
+
+```text
+config/agents/backoffice_anatel/guardrails.yaml
+config/agents/backoffice_anatel/judges.yaml
+config/agents/backoffice_anatel/prompt_policy.yaml
+```
+
+A lógica de domínio original continua fazendo validações operacionais por nó, e o framework envolve a execução com guardrails, OutputSupervisor e judges.
+
+## Como subir localmente
+
+```bash
+cp .env.example .env
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+```
+
+## Como validar rapidamente
+
+```bash
+curl http://localhost:8000/health
+curl http://localhost:8000/debug/backoffice/parity
+curl http://localhost:8000/health/live
+curl http://localhost:8000/health/ready
+```
+
+## Observação importante
+
+O arquivo `.env` real foi removido do pacote gerado. Configure credenciais reais somente localmente ou via secret manager. Não versionar chaves OCI, Autonomous Database, Langfuse, Siebel, IMDB, Speech Analytics ou qualquer segredo TIM.