diff --git a/README.md b/README.md index 3d7e9d9..3ebe62d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AI Orquestrador -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 | -| Orquestracao | Python | coordena contexto, fluxo e tools | +| Orquestracao | Python | coordena contexto, fluxo, tools e resposta | | 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 | | `editar_data_revisao` | remarca revisao existente | -| `realizar_pedido` | cria pedido de compra | -| `listar_pedidos` | lista pedidos do usuario | -| `cancelar_pedido` | cancela pedido existente | +| `consultar_frota_aluguel` | lista frota disponivel para locacao | +| `abrir_locacao_aluguel` | abre contrato de locacao | +| `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 | | `continuar_proximo_pedido` | retoma o proximo item da fila | | `descartar_pedidos_pendentes` | limpa apenas a fila pendente | @@ -156,21 +189,21 @@ O projeto usa duas conexoes MySQL: - banco de tools - banco mock de negocio -O bootstrap agora e uma rotina dedicada e explicita: -- [app/db/bootstrap.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/bootstrap.py) -- [app/db/init_db.py](/d:/vitor/Pessoal/PJ/Orquestrador/app/db/init_db.py) como alias legado de compatibilidade +O bootstrap e uma rotina dedicada e explicita: +- [app/db/bootstrap.py](app/db/bootstrap.py) +- [app/db/init_db.py](app/db/init_db.py) como alias legado de compatibilidade Importante: - o container principal nao executa bootstrap automaticamente; - 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 ### Sem Docker -1. Configure as variaveis de ambiente com base em `.env.example`. -2. Inicialize banco e seed com a rotina dedicada: +1. Configure as variaveis de ambiente com base em `.env.example`, `.env.local` ou `.env.prod`, conforme o ambiente. +2. Rode bootstrap quando precisar preparar schema e seeds: ```bash python -m app.db.bootstrap @@ -188,6 +221,19 @@ python -m app.db.init_db 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 O compose atual sobe: @@ -264,13 +310,14 @@ Principais variaveis: - `ENVIRONMENT` - `DEBUG` -Observacao: -- para producao com Telegram, prefira `CONVERSATION_STATE_BACKEND=redis`; +Observacoes: +- 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`. ## 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 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. -## Testes +## Testes e Stress -Suite automatizada atual: +Suite automatizada: ```bash 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 ``` +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 -- [TEST_CASES.md](/d:/vitor/Pessoal/PJ/Orquestrador/TEST_CASES.md) -- [DEPLOY_SERVIDOR.md](/d:/vitor/Pessoal/PJ/Orquestrador/DEPLOY_SERVIDOR.md) -- [.env.example](/d:/vitor/Pessoal/PJ/Orquestrador/.env.example) +- [TEST_CASES.md](TEST_CASES.md) +- [DEPLOY_SERVIDOR.md](DEPLOY_SERVIDOR.md) +- [.env.example](.env.example) +- [scripts/stress_smoke.py](scripts/stress_smoke.py) ## Proximos Passos Naturais Os proximos ganhos mais valiosos para o projeto sao: -- persistir trilha de conversa e decisoes -- consolidar observabilidade por turno e por tool com baixo acoplamento operacional -- aumentar observabilidade por turno e por tool -- reduzir o tamanho do `OrquestradorService` -- consolidar documentacao operacional Telegram-first - - +- introduzir migracoes de banco de dados +- ampliar observabilidade por turno, tool e canal +- evoluir a trilha de auditoria e consultas operacionais +- criar uma camada de avaliacao semantica e replay de conversas +- integrar o orquestrador com sistemas reais de operacao