vitor
/
orquestrador
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

📝 docs(readme): atualizar documentacao do orquestrador

Browse Source 
- descreve vendas, revisao e aluguel como dominios atuais

- alinha arquitetura, tools, bootstrap, deploy e estado conversacional

- adiciona instrucoes de stress smoke e observacoes de Redis em producao
main
Vitor Hugo Belorio Simão 3 weeks ago
parent 74e83adc66
commit 5448259ef9
1 changed files with 113 additions and 46 deletions
Show Stats Download Patch File Download Diff File

159
README.md
Unescape Escape View File

@ -1,6 +1,6 @@
# AI Orquestrador # AI Orquestrador
Orquestrador conversacional para concessionaria, focado em combinar: Orquestrador conversacional para operacao automotiva, focado em combinar:
- interpretacao semantica via Vertex AI - interpretacao semantica via Vertex AI
- execucao deterministica de tools de negocio - execucao deterministica de tools de negocio
- normalizacao tecnica na aplicacao - normalizacao tecnica na aplicacao
@ -11,18 +11,19 @@ Orquestrador conversacional para concessionaria, focado em combinar:
A ideia central do sistema e: A ideia central do sistema e:
- o usuario conversa em linguagem natural - o usuario conversa em linguagem natural
- o modelo entende intencao, contexto e proximo passo - o modelo entende intencao, contexto e proximo passo
- a aplicacao normaliza dados, protege regras e executa tools - a aplicacao protege regras, normaliza dados e executa tools de negocio
- a resposta final volta para o usuario pelo canal de atendimento - a resposta final volta ao usuario no canal de atendimento
Hoje o projeto esta mais proximo de um orquestrador conversacional do que de uma API tradicional. O FastAPI continua no repositorio como apoio legado/bootstrap, mas o fluxo operacional principal e o satelite do Telegram. Hoje o projeto esta mais proximo de um orquestrador conversacional do que de uma API tradicional. O FastAPI continua no repositorio como apoio legado e operacional, mas o fluxo principal roda no satelite do Telegram.
## Estado Atual ## Estado Atual
O dominio atual cobre dois grupos principais: O dominio atual cobre tres frentes principais:
- vendas - vendas
- revisao e pos-venda - revisao e pos-venda
- aluguel de veiculos
Capacidades ja implementadas: Capacidades de negocio ja implementadas:
- consultar estoque de veiculos - consultar estoque de veiculos
- validar cliente para compra - validar cliente para compra
- avaliar veiculo para troca - avaliar veiculo para troca
@ -30,28 +31,38 @@ Capacidades ja implementadas:
- listar pedidos - listar pedidos
- cancelar pedido - cancelar pedido
- agendar revisao - agendar revisao
- listar revisoes - listar agendamentos de revisao
- cancelar revisao - cancelar agendamento de revisao
- remarcar revisao - remarcar revisao
- consultar frota de aluguel
- abrir locacao
- registrar pagamento de aluguel
- registrar multa de aluguel
- registrar devolucao de aluguel
- responder consultas informativas sobre o aluguel atual, como contrato, placa, diaria, pagamento e data de devolucao
Capacidades conversacionais ja tratadas: Capacidades conversacionais ja tratadas:
- multiplos pedidos na mesma mensagem - multiplos pedidos na mesma mensagem
- fila de pedidos - fila de pedidos pendentes
- escolha explicita de qual assunto iniciar primeiro
- refinamento implicito de uma opcao ja detectada
- troca de contexto entre dominios - troca de contexto entre dominios
- coleta incremental de campos - coleta incremental de campos
- reaproveitamento de contexto temporario - reaproveitamento de contexto temporario
- confirmacao antes de mudar de assunto - reidratacao do ultimo contrato de locacao quando o estado em memoria nao existe mais
- confirmacao antes de mudar de assunto em fluxos abertos
- sugestao de horario alternativo em conflito de agenda - sugestao de horario alternativo em conflito de agenda
- retries defensivos no envio de respostas ao Telegram
## Arquitetura Atual ## Arquitetura Atual
| Componente | Tecnologia | Papel atual | | Componente | Tecnologia | Papel atual |
| --- | --- | --- | | --- | --- | --- |
| LLM | Vertex AI / Gemini | interpretacao e apoio a decisao | | LLM | Vertex AI / Gemini | interpretacao e apoio a decisao |
| Orquestracao | Python | coordena contexto, fluxo e tools | | Orquestracao | Python | coordena contexto, fluxo, tools e resposta |
| Metadados de tools | MySQL | catalogo das tools disponiveis | | Metadados de tools | MySQL | catalogo das tools disponiveis |
| Dados mock de negocio | MySQL | veiculos, clientes, usuarios, pedidos e revisoes | | Dados mock de negocio | MySQL | veiculos, clientes, usuarios, pedidos, revisoes e locacoes |
| Estado conversacional | Redis ou memoria | rascunhos, fila e contexto temporario | | Estado conversacional | Redis ou memoria | rascunhos, fila, snapshots e contexto temporario |
| Canal | Telegram Bot API | atendimento principal via long polling | | Canal | Telegram Bot API | atendimento principal via long polling |
| Containerizacao | Docker Compose | ambiente local e deploy simples | | Containerizacao | Docker Compose | ambiente local e deploy simples |
@ -61,16 +72,17 @@ Fluxo principal do atendimento pelo Telegram:
1. O usuario envia uma mensagem ao bot. 1. O usuario envia uma mensagem ao bot.
2. O `TelegramSatelliteService` identifica ou cria o usuario interno. 2. O `TelegramSatelliteService` identifica ou cria o usuario interno.
3. O `OrquestradorService` recupera o contexto conversacional. 3. O `OrquestradorService` recupera contexto, fila e fluxos abertos.
4. O `MessagePlanner` e o Vertex ajudam a estruturar a intencao do turno. 4. O sistema tenta resolver atalhos deterministas antes de consultar o LLM, como continuidade de fluxo, selecao pendente, pagamento de aluguel e consulta do contrato atual.
5. A aplicacao continua fluxos abertos ou decide a proxima tool. 5. O `MessagePlanner` e o Vertex ajudam a estruturar o turno quando necessario.
6. A tool e executada com validacoes e normalizacoes deterministicas. 6. A tool e executada com validacoes e normalizacoes deterministicas.
7. O sistema devolve a resposta ao usuario no Telegram. 7. O sistema persiste a trilha do turno e devolve a resposta ao usuario no Telegram.
Importante: Importante:
- o historico completo da conversa ainda nao e persistido como trilha audivel; - a trilha de turnos fica registrada em `conversation_turns` para auditoria operacional;
- o estado de trabalho pode ficar em memoria ou Redis; - o estado de trabalho pode ficar em memoria ou Redis;
- em producao, Redis e o backend recomendado para continuidade real. - em producao com Telegram, o backend esperado para estado conversacional e Redis;
- o bootstrap de banco e seed e uma rotina separada do servico principal.
## Estrutura do Projeto ## Estrutura do Projeto
@ -81,12 +93,15 @@ app/
schemas.py schemas.py
core/ core/
settings.py settings.py
time_utils.py
db/ db/
bootstrap.py
database.py database.py
mock_database.py
init_db.py init_db.py
tool_seed.py mock_database.py
mock_models.py
mock_seed.py mock_seed.py
tool_seed.py
models/ models/
tool.py tool.py
integrations/ integrations/
@ -103,20 +118,31 @@ app/
credit_service.py credit_service.py
inventory_service.py inventory_service.py
order_service.py order_service.py
rental_service.py
review_service.py review_service.py
flows/ flows/
flow_state_support.py
order_flow.py order_flow.py
order_flow_support.py
rental_flow.py
rental_flow_support.py
review_flow.py review_flow.py
review_flow_support.py
orchestration/ orchestration/
conversation_history_service.py
conversation_policy.py conversation_policy.py
conversation_state_repository.py conversation_state_repository.py
conversation_state_store.py conversation_state_store.py
entity_normalizer.py entity_normalizer.py
message_planner.py message_planner.py
orchestrator_context_manager.py
orchestrator_execution_manager.py
orquestrador_service.py orquestrador_service.py
prompt_builders.py prompt_builders.py
redis_state_repository.py redis_state_repository.py
response_formatter.py response_formatter.py
sensitive_data.py
state_repository_factory.py
tool_executor.py tool_executor.py
turn_decision.py turn_decision.py
tools/ tools/
@ -125,26 +151,33 @@ app/
user/ user/
mock_customer_service.py mock_customer_service.py
user_service.py user_service.py
scripts/
stress_smoke.py
tests/ tests/
... ...
``` ```
## Tools Disponiveis ## Tools Disponiveis
As definicoes padrao ficam em [app/db/tool_seed.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/tool_seed.py): As definicoes padrao ficam em [app/db/tool_seed.py](app/db/tool_seed.py):
| Tool | Finalidade | | Tool | Finalidade |
| --- | --- | | --- | --- |
| `consultar_estoque` | consulta veiculos por preco, categoria e ordenacao | | `consultar_estoque` | consulta veiculos por preco, categoria e ordenacao |
| `validar_cliente_venda` | valida elegibilidade de compra por CPF e valor | | `validar_cliente_venda` | valida elegibilidade de compra por CPF e valor |
| `avaliar_veiculo_troca` | estima valor de troca do veiculo do cliente | | `avaliar_veiculo_troca` | estima valor de troca do veiculo do cliente |
| `realizar_pedido` | cria pedido de compra |
| `listar_pedidos` | lista pedidos do usuario |
| `cancelar_pedido` | cancela pedido existente |
| `agendar_revisao` | agenda revisao com calculo de valor | | `agendar_revisao` | agenda revisao com calculo de valor |
| `listar_agendamentos_revisao` | lista revisoes do usuario | | `listar_agendamentos_revisao` | lista revisoes do usuario |
| `cancelar_agendamento_revisao` | cancela revisao por protocolo | | `cancelar_agendamento_revisao` | cancela revisao por protocolo |
| `editar_data_revisao` | remarca revisao existente | | `editar_data_revisao` | remarca revisao existente |
| `realizar_pedido` | cria pedido de compra | | `consultar_frota_aluguel` | lista frota disponivel para locacao |
| `listar_pedidos` | lista pedidos do usuario | | `abrir_locacao_aluguel` | abre contrato de locacao |
| `cancelar_pedido` | cancela pedido existente | | `registrar_pagamento_aluguel` | registra pagamento vinculado ao contrato |
| `registrar_multa_aluguel` | registra multa vinculada ao contrato |
| `registrar_devolucao_aluguel` | encerra locacao e calcula valor final |
| `limpar_contexto_conversa` | zera contexto e fila | | `limpar_contexto_conversa` | zera contexto e fila |
| `continuar_proximo_pedido` | retoma o proximo item da fila | | `continuar_proximo_pedido` | retoma o proximo item da fila |
| `descartar_pedidos_pendentes` | limpa apenas a fila pendente | | `descartar_pedidos_pendentes` | limpa apenas a fila pendente |
@ -156,21 +189,21 @@ O projeto usa duas conexoes MySQL:
- banco de tools - banco de tools
- banco mock de negocio - banco mock de negocio
O bootstrap agora e uma rotina dedicada e explicita: O bootstrap e uma rotina dedicada e explicita:
- [app/db/bootstrap.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/bootstrap.py) - [app/db/bootstrap.py](app/db/bootstrap.py)
- [app/db/init_db.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/init_db.py) como alias legado de compatibilidade - [app/db/init_db.py](app/db/init_db.py) como alias legado de compatibilidade
Importante: Importante:
- o container principal nao executa bootstrap automaticamente; - o container principal nao executa bootstrap automaticamente;
- o app HTTP legado nao executa bootstrap no startup; - o app HTTP legado nao executa bootstrap no startup;
- a preparacao de schema e seed deve ser rodada de forma explicita antes do servico principal quando necessario. - schema e seed devem ser preparados de forma explicita quando necessario.
## Execucao Local ## Execucao Local
### Sem Docker ### Sem Docker
1. Configure as variaveis de ambiente com base em `.env.example`. 1. Configure as variaveis de ambiente com base em `.env.example`, `.env.local` ou `.env.prod`, conforme o ambiente.
2. Inicialize banco e seed com a rotina dedicada: 2. Rode bootstrap quando precisar preparar schema e seeds:
```bash ```bash
python -m app.db.bootstrap python -m app.db.bootstrap
@ -188,6 +221,19 @@ python -m app.db.init_db
python -m app.integrations.telegram_satellite_service python -m app.integrations.telegram_satellite_service
``` ```
Se estiver usando um arquivo dedicado, como `.env.local`, voce pode executar com `python-dotenv`:
```bash
python -m dotenv -f .env.local run -- python -m app.db.bootstrap
python -m dotenv -f .env.local run -- python -m app.integrations.telegram_satellite_service
```
O app HTTP legado continua disponivel quando necessario:
```bash
python -m uvicorn app.main:app --reload
```
### Com Docker Compose ### Com Docker Compose
O compose atual sobe: O compose atual sobe:
@ -264,13 +310,14 @@ Principais variaveis:
- `ENVIRONMENT` - `ENVIRONMENT`
- `DEBUG` - `DEBUG`
Observacao: Observacoes:
- para producao com Telegram, prefira `CONVERSATION_STATE_BACKEND=redis`; - para producao com Telegram, use `CONVERSATION_STATE_BACKEND=redis`;
- `memory` e util para desenvolvimento local e alguns smoke tests;
- evite valores nao booleanos em `DEBUG`. - evite valores nao booleanos em `DEBUG`.
## Docker ## Docker
O [Dockerfile](/d:/vitor/Pessoal/PJ/Orquestrador/Dockerfile) agora sobe apenas o servico principal do projeto: O [Dockerfile](Dockerfile) sobe apenas o servico principal do projeto:
```bash ```bash
python -m app.integrations.telegram_satellite_service python -m app.integrations.telegram_satellite_service
@ -284,9 +331,9 @@ python -m app.db.bootstrap
Isso evita que um restart do container recrie schema ou rode seed de forma implicita. Isso evita que um restart do container recrie schema ou rode seed de forma implicita.
## Testes ## Testes e Stress
Suite automatizada atual: Suite automatizada:
```bash ```bash
python -m unittest discover -s tests -v python -m unittest discover -s tests -v
@ -298,19 +345,39 @@ Se o ambiente local tiver `DEBUG` com valor invalido, force antes da execucao:
DEBUG=false python -m unittest discover -s tests -v DEBUG=false python -m unittest discover -s tests -v
``` ```
Stress smoke local para estado, ciclos de pedido e corrida de reserva:
```bash
python scripts/stress_smoke.py --backend memory --state-iterations 200 --order-cycles 30 --race-attempts 8 --user-base 995000 --cpf 11144477735
```
Se voce estiver usando um arquivo de ambiente dedicado:
```bash
python -m dotenv -f .env.local run -- python scripts/stress_smoke.py --backend memory --state-iterations 200 --order-cycles 30 --race-attempts 8 --user-base 995000 --cpf 11144477735
```
## Deploy
O deploy de servidor fica documentado em [DEPLOY_SERVIDOR.md](DEPLOY_SERVIDOR.md).
No modelo atual:
- o servico `orquestrador` do `systemd` executa o `telegram_satellite_service`;
- o bootstrap pode ser rodado manualmente ou por uma unit separada;
- em producao, Redis deve estar disponivel para o estado conversacional.
## Arquivos Uteis ## Arquivos Uteis
- [TEST_CASES.md](/d:/vitor/Pessoal/PJ/Orquestrador/TEST_CASES.md) - [TEST_CASES.md](TEST_CASES.md)
- [DEPLOY_SERVIDOR.md](/d:/vitor/Pessoal/PJ/Orquestrador/DEPLOY_SERVIDOR.md) - [DEPLOY_SERVIDOR.md](DEPLOY_SERVIDOR.md)
- [.env.example](/d:/vitor/Pessoal/PJ/Orquestrador/.env.example) - [.env.example](.env.example)
- [scripts/stress_smoke.py](scripts/stress_smoke.py)
## Proximos Passos Naturais ## Proximos Passos Naturais
Os proximos ganhos mais valiosos para o projeto sao: Os proximos ganhos mais valiosos para o projeto sao:
- persistir trilha de conversa e decisoes - introduzir migracoes de banco de dados
- consolidar observabilidade por turno e por tool com baixo acoplamento operacional - ampliar observabilidade por turno, tool e canal
- aumentar observabilidade por turno e por tool - evoluir a trilha de auditoria e consultas operacionais
- reduzir o tamanho do `OrquestradorService` - criar uma camada de avaliacao semantica e replay de conversas
- consolidar documentacao operacional Telegram-first - integrar o orquestrador com sistemas reais de operacao

Write Preview
Loading…
Cancel
Save