- atualiza docker-compose, Dockerfile e service do systemd para subir o bootstrap de banco e o Telegram satellite como runtime principal do projeto\n- revisa .env.example, README, TEST_CASES e guia de deploy para refletir a arquitetura atual com MySQL, Redis, Vertex AI e canal Telegram\n- endurece o parsing de configuracao com aliases controlados para DEBUG e normalizacao de ENVIRONMENT e CONVERSATION_STATE_BACKEND\n- centraliza a inicializacao legada do app HTTP em app.db.init_db e faz o bootstrap respeitar flags de seed e falhar explicitamente quando algum backend nao sobe\n- adiciona cobertura dedicada para parsing de settings e para o bootstrap de banco do runtime
Backend conversacional para concessionária, focado em orquestrar ferramentas de negócio com apoio de LLM.
Orquestrador conversacional para concessionaria, focado em combinar:
- interpretacao semantica via Vertex AI
- execucao deterministica de tools de negocio
- normalizacao tecnica na aplicacao
- atendimento pelo Telegram como canal principal
A proposta do sistema é:
- receber uma mensagem em linguagem natural
- deixar o modelo interpretar a intenção do usuário
- usar ferramentas do sistema quando precisar consultar dados ou executar ações
- devolver uma resposta objetiva ao usuário
## Proposta
Hoje o projeto já implementa esse fluxo, mas ainda inclui camadas de suporte ao modelo, como extração estruturada, memória temporária por usuário, coleta incremental de dados e fallback determinístico de resposta.
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
## Visão Geral
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.
O domínio atual do projeto cobre dois fluxos principais:
## Estado Atual
O dominio atual cobre dois grupos principais:
- vendas
- revisão/pós-venda
- revisao e pos-venda
O sistema consegue:
- consultar estoque de veículos
Capacidades ja implementadas:
- consultar estoque de veiculos
- validar cliente para compra
- avaliar veículo para troca
- criar pedido de compra
- avaliar veiculo para troca
- criar pedido
- listar pedidos
- cancelar pedido
- agendar revisão
- listar revisões agendadas
- cancelar revisão
- remarcar revisão
- agendar revisao
- listar revisoes
- cancelar revisao
- remarcar revisao
Além do roteamento por tool, o orquestrador também trata cenários conversacionais como:
- mensagens com mais de um pedido na mesma entrada
- coleta de parâmetros em múltiplas mensagens
- reaproveitamento de contexto temporário
- confirmação antes de trocar de assunto
- sugestão de próximo horário quando uma revisão entra em conflito
Capacidades conversacionais ja tratadas:
- multiplos pedidos na mesma mensagem
- fila de pedidos
- troca de contexto entre dominios
- coleta incremental de campos
- reaproveitamento de contexto temporario
- confirmacao antes de mudar de assunto
- sugestao de horario alternativo em conflito de agenda
## Stack Atual
## Arquitetura Atual
| Componente | Tecnologia | Observação |
| Componente | Tecnologia | Papel atual |
| --- | --- | --- |
| Backend | FastAPI | API principal |
| LLM | Google Vertex AI | Modelos Gemini |
| Banco de tools | MySQL | Metadados das ferramentas |
| Banco mock de negócio | MySQL | Veículos, clientes, usuários, pedidos e revisões |
| ORM | SQLAlchemy | Acesso aos dois bancos |
| Runtime | Python 3.11+ | Aplicação principal |
| Integração de canal | Telegram Bot API | Long polling via serviço satélite |
| Containerização | Docker | Ambiente local e deploy |
## Como o Sistema Funciona
Fluxo principal do `/chat`:
1. O usuário envia uma mensagem.
2. O `OrquestradorService` inicializa ou atualiza o contexto temporário do usuário.
3. O sistema tenta separar múltiplos pedidos contidos na mesma mensagem.
4. O LLM ajuda a extrair intenções e entidades estruturadas.
5. Se houver fluxo em aberto, o orquestrador continua a coleta dos dados faltantes.
6. Quando necessário, o modelo escolhe uma tool.
7. A tool é executada pelos handlers do sistema.
8. O resultado é devolvido ao usuário, usando resposta do modelo ou fallback determinístico.
| LLM | Vertex AI / Gemini | interpretacao e apoio a decisao |
