- 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
Orquestrador conversacional para concessionaria, focado em combinar:
Orquestrador conversacional para operacao automotiva, focado em combinar:
- interpretacao semantica via Vertex AI
- execucao deterministica de tools de negocio
- normalizacao tecnica na aplicacao
@ -11,18 +11,19 @@ Orquestrador conversacional para concessionaria, focado em combinar:
A ideia central do sistema e:
- o usuario conversa em linguagem natural
- o modelo entende intencao, contexto e proximo passo
- a aplicacao normaliza dados, protege regras e executa tools
- a resposta final volta para o usuario pelo canal de atendimento
- a aplicacao protege regras, normaliza dados e executa tools de negocio
- 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
O dominio atual cobre dois grupos principais:
O dominio atual cobre tres frentes principais:
- vendas
- revisao e pos-venda
- aluguel de veiculos
Capacidades ja implementadas:
Capacidades de negocio ja implementadas:
- consultar estoque de veiculos
- validar cliente para compra
- avaliar veiculo para troca
@ -30,28 +31,38 @@ Capacidades ja implementadas:
- listar pedidos
- cancelar pedido
- agendar revisao
- listar revisoes
- cancelar revisao
- listar agendamentos de revisao
- cancelar agendamento de 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:
- 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
- coleta incremental de campos
- 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
- retries defensivos no envio de respostas ao Telegram
## Arquitetura Atual
| Componente | Tecnologia | Papel atual |
| --- | --- | --- |
| LLM | Vertex AI / Gemini | interpretacao e apoio a decisao |
| Metadados de tools | MySQL | catalogo das tools disponiveis |
| Dados mock de negocio | MySQL | veiculos, clientes, usuarios, pedidos e revisoes |
| Estado conversacional | Redis ou memoria | rascunhos, fila e contexto temporario |
| Dados mock de negocio | MySQL | veiculos, clientes, usuarios, pedidos, revisoes e locacoes |
| Estado conversacional | Redis ou memoria | rascunhos, fila, snapshots e contexto temporario |
| Canal | Telegram Bot API | atendimento principal via long polling |
| 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.
2. O `TelegramSatelliteService` identifica ou cria o usuario interno.
3. O `OrquestradorService` recupera o contexto conversacional.
4. O `MessagePlanner` e o Vertex ajudam a estruturar a intencao do turno.
5. A aplicacao continua fluxos abertos ou decide a proxima tool.
3. O `OrquestradorService` recupera contexto, fila e fluxos abertos.
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. O `MessagePlanner` e o Vertex ajudam a estruturar o turno quando necessario.
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:
- 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;
- 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
@ -81,12 +93,15 @@ app/
schemas.py
core/
settings.py
time_utils.py
db/
bootstrap.py
database.py
mock_database.py
init_db.py
tool_seed.py
mock_database.py
mock_models.py
mock_seed.py
tool_seed.py
models/
tool.py
integrations/
@ -103,20 +118,31 @@ app/
credit_service.py
inventory_service.py
order_service.py
rental_service.py
review_service.py
flows/
flow_state_support.py
order_flow.py
order_flow_support.py
rental_flow.py
rental_flow_support.py
review_flow.py
review_flow_support.py
orchestration/
conversation_history_service.py
conversation_policy.py
conversation_state_repository.py
conversation_state_store.py
entity_normalizer.py
message_planner.py
orchestrator_context_manager.py
orchestrator_execution_manager.py
orquestrador_service.py
prompt_builders.py
redis_state_repository.py
response_formatter.py
sensitive_data.py
state_repository_factory.py
tool_executor.py
turn_decision.py
tools/
@ -125,26 +151,33 @@ app/
user/
mock_customer_service.py
user_service.py
scripts/
stress_smoke.py
tests/
...
```
## 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 |
| --- | --- |
| `consultar_estoque` | consulta veiculos por preco, categoria e ordenacao |
| `validar_cliente_venda` | valida elegibilidade de compra por CPF e valor |
| `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 |
| `listar_agendamentos_revisao` | lista revisoes do usuario |
| `cancelar_agendamento_revisao` | cancela revisao por protocolo |
