From e955d64306630884840b01a1ae103ff58947aca5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Vitor=20Hugo=20Belorio=20Sim=C3=A3o?= Date: Fri, 6 Mar 2026 09:18:49 -0300 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs(readme):=20alinhar=20docume?= =?UTF-8?q?ntacao=20com=20a=20arquitetura=20atual=20do=20orquestrador?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reescreve o README para refletir o estado real do projeto, incluindo stack atual, estrutura reorganizada de services, fluxo conversacional do /chat, tools implementadas, bancos utilizados, endpoints disponiveis e integracao com Telegram. Tambem documenta limitacoes atuais do sistema, como memoria conversacional volatil e ausencia de persistencia de historico entre reinicializacoes, mantendo a documentacao coerente com a implementacao atual. --- README.md | 452 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 255 insertions(+), 197 deletions(-) diff --git a/README.md b/README.md index f52aeae..eebd950 100644 --- a/README.md +++ b/README.md @@ -1,256 +1,314 @@ -# 🤖 AI Orquestrador - -Um sistema inteligente de orquestração de ferramentas que utiliza inteligência artificial para processar pedidos de clientes e executar ações automaticamente. Utilizando o poder do Google Vertex AI e Gemini, o sistema compreende intenções naturais e chama as ferramentas apropriadas para resolver cada solicitação. - ---- - -## 📖 Visão Geral - -AI Orquestrador é um MVP (Produto Mínimo Viável) que demonstra como integrar um modelo de linguagem avançado com um conjunto de ferramentas específicas do domínio para criar uma experiência conversacional inteligente. - -**Fluxo de funcionamento:** - -1. Cliente envia uma mensagem descrevendo uma ação desejada -2. O sistema envia a mensagem e lista de ferramentas disponíveis ao modelo de IA -3. A IA analisa a solicitação e decide qual ferramenta chamar (se necessário) -4. O sistema extrai parâmetros da mensagem e executa a ferramenta -5. Resultado é formatado e retornado ao cliente de forma natural - -**Exemplo prático:** - -``` -Cliente: "Gostaria de comprar um carro de até 50000 reais que seja sedan" -↓ -IA decide: chamar ferramenta "consultar_estoque" -↓ -Sistema busca no banco de dados -↓ -Retorna: "Encontrei 5 veículos sedans disponíveis até R$ 50.000..." +# AI Orquestrador + +Backend conversacional para concessionária, focado em orquestrar ferramentas de negócio com apoio de LLM. + +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 + +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. + +## Visão Geral + +O domínio atual do projeto cobre dois fluxos principais: +- vendas +- revisão/pós-venda + +O sistema consegue: +- consultar estoque de veículos +- validar cliente para compra +- avaliar veículo para troca +- criar pedido de compra +- cancelar pedido +- agendar revisão +- listar revisões agendadas +- cancelar revisão +- remarcar revisão + +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 + +## Stack Atual + +| Componente | Tecnologia | Observação | +| --- | --- | --- | +| 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. + +Importante: +- a memória de conversa atual é volátil e fica em memória do processo +- o sistema ainda não persiste histórico conversacional entre reinícios +- o `response_formatter` responde direto ao usuário; ele não devolve o resultado para o modelo + +## Estrutura do Projeto + +```text +app/ + main.py + api/ + routes/ + chat.py + mock.py + tools.py + dependencies.py + schemas.py + core/ + settings.py + db/ + database.py + mock_database.py + init_db.py + tool_seed.py + mock_seed.py + models/ + tool.py + repositories/ + tool_repository.py + user_repository.py + integrations/ + telegram_satellite_service.py + services/ + ai/ + llm_service.py + flows/ + order_flow.py + review_flow.py + orchestration/ + orquestrador_service.py + orchestrator_config.py + conversation_state_store.py + prompt_builders.py + response_formatter.py + tools/ + handlers.py + tool_registry.py + user/ + user_service.py ``` ---- +## Organização das Camadas -## 🛠️ Stack Tecnológico +### `services/orchestration` -| Componente | Tecnologia | Descrição | -| ------------------- | ------------------ | ------------------------------------------------ | -| **Backend** | FastAPI | Framework web moderno e rápido para APIs Python | -| **IA/LLM** | Google Vertex AI | Plataforma de IA empresarial com Gemini 1.5 Pro | -| **Banco de Dados (Tools)** | PostgreSQL | Banco relacional para metadados de ferramentas | -| **Banco Fictício (Mock)** | MySQL | Dados de negócio simulados usados pelos handlers | -| **Containerização** | Docker | Isolamento e execução consistente | -| **Runtime** | Python 3.11+ | Linguagem principal da aplicação | +Núcleo do orquestrador: +- coordenação do fluxo conversacional +- controle de contexto ativo +- fila de pedidos +- construção de prompts +- fallback de resposta ---- +### `services/flows` -## 🏗️ Arquitetura do Projeto +Fluxos incrementais de negócio: +- criação e cancelamento de pedido +- agendamento, listagem, cancelamento e remarcação de revisão -``` -Orquestrador/ -├── app/ -│ ├── main.py # Ponto de entrada da aplicação FastAPI -│ │ -│ ├── api/ -│ │ ├── routes.py # Endpoints principais (Chat, Health) -│ │ ├── tool_routes.py # Endpoints de gerenciamento de ferramentas -│ │ └── schemas.py # Modelos Pydantic para validação -│ │ -│ ├── core/ -│ │ └── settings.py # Configurações e variáveis de ambiente -│ │ -│ ├── db/ -│ │ ├── database.py # Conexão e declaração SQLAlchemy -│ │ ├── models.py # Modelos ORM do banco de dados -│ │ ├── init_db.py # Inicialização de banco -│ │ └── tool_seed.py # Dados iniciais de ferramentas -│ │ -│ ├── services/ -│ │ ├── orquestrador_service.py # Lógica principal de orquestração -│ │ ├── llm_service.py # Integração com Vertex AI / Gemini -│ │ ├── tool_registry.py # Registro e descoberta de ferramentas -│ │ ├── handlers.py # Handlers de execução de tools -│ │ └── handlers.py # Handlers consultando MySQL fictício -│ │ -│ ├── repositories/ -│ │ └── tool_repository.py # Acesso a dados de ferramentas -│ │ -│ └── integrations/ # Integrações externas -│ -├── Dockerfile # Imagem Docker da aplicação -├── docker-compose.yml # Stack local com PostgreSQL -├── requirements.txt # Dependências Python -├── .env.example # Exemplo de configuração -└── README.md # Esta documentação -``` +### `services/ai` ---- +Integração com Vertex AI e Gemini. -## 🛠️ Ferramentas Disponíveis +### `services/tools` -O sistema possui as seguintes ferramentas pré-configuradas: +Registro das tools e implementação dos handlers que executam as ações reais. -| Ferramenta | Descrição | -| ------------------------- | ------------------------------------------------- | -| **consultar_estoque** | Busca veículos por critérios de preço e categoria | -| **validar_cliente_venda** | Verifica aprovação de crédito do cliente | -| **avaliar_veiculo_troca** | Calcula valor estimado de troca de veículo | -| **agendar_revisao** | Agenda manutenção e revisão de veículo | -| **cancelar_pedido** | Cancela pedido existente do cliente | +### `services/user` ---- +Serviços ligados à identificação e persistência de usuários de canal, como Telegram. -## 🚀 Tecnologias em Detalhes +## Ferramentas Disponíveis -### FastAPI +As tools padrão são semeadas a partir de [app/db/tool_seed.py](app/db/tool_seed.py): -Framework web de alto desempenho construído sobre Starlette. Oferece validação automática de dados com Pydantic, documentação interativa (Swagger/OpenAPI) e tipagem forte em Python. +| Tool | Finalidade | +| --- | --- | +| `consultar_estoque` | Consulta veículos por preço, categoria e ordenação | +| `validar_cliente_venda` | Valida elegibilidade de compra por CPF e valor | +| `avaliar_veiculo_troca` | Estima valor de troca do veículo do cliente | +| `agendar_revisao` | Agenda revisão com cálculo de valor | +| `listar_agendamentos_revisao` | Lista revisões do usuário | +| `cancelar_agendamento_revisao` | Cancela uma revisão por protocolo | +| `editar_data_revisao` | Remarca revisão existente | +| `realizar_pedido` | Cria pedido de compra | +| `cancelar_pedido` | Cancela pedido existente | -### Google Vertex AI + Gemini +## Bancos e Seeds -Plataforma de IA gerenciada do Google Cloud que permite usar modelos de linguagem avançados como o Gemini 1.5 Pro. Oferece segurança, escalabilidade e integração nativa com o ecossistema Google Cloud. +O projeto usa duas conexões distintas: -### PostgreSQL +### Banco de tools -Banco de dados relacional de código aberto com suporte a JSON, transações ACID e extensibilidade. Ideal para estruturar dados de ferramentas e histórico de interações. +Responsável por armazenar: +- nome da tool +- descrição +- schema de parâmetros -### Docker +Arquivos principais: +- `app/db/database.py` +- `app/db/models/tool.py` +- `app/db/tool_seed.py` -Containerização da aplicação garantindo consistência entre ambientes de desenvolvimento, teste e produção. +### Banco mock de negócio -## 📊 Fluxograma de Funcionamento +Responsável por armazenar dados fictícios de: +- veículos +- clientes +- usuários +- pedidos +- agendamentos de revisão -``` -┌─────────────┐ -│ Cliente │ "Comprar carro por até 50mil" -└──────┬──────┘ - │ - ▼ -┌──────────────────────────┐ -│ Endpoint /chat (POST) │ -└──────┬───────────────────┘ - │ - ▼ -┌──────────────────────────────────┐ -│ OrquestradorService │ -│ - Processa mensagem │ -│ - Busca ferramentas disponíveis │ -└──────┬───────────────────────────┘ - │ - ▼ -┌──────────────────────────────────┐ -│ LLMService (Vertex AI) │ -│ - Envia ao Gemini 1.5 Pro │ -│ - Recebe decisão de tool │ -└──────┬───────────────────────────┘ - │ - ▼ -┌──────────────────────────────────┐ -│ Tool Handlers │ -│ - Executa: consultar_estoque │ -│ - Busca no MySQL fictício │ -└──────┬───────────────────────────┘ - │ - ▼ -┌──────────────────────────────────┐ -│ Formata Resposta │ -│ - Estrutura resultado │ -│ - Retorna ao cliente │ -└──────┬───────────────────────────┘ - │ - ▼ -┌──────────────────┐ -│ Cliente │ Resultado formatado -└──────────────────┘ -``` +Arquivos principais: +- `app/db/mock_database.py` +- `app/db/mock_models.py` +- `app/db/mock_seed.py` ---- +No startup, a aplicação tenta: +- criar as tabelas dos dois bancos +- popular tools +- popular dados mock +- fazer warmup do LLM -## 🔐 Segurança +## Endpoints -O sistema foi construído com foco em boas práticas de segurança: +### Chat -- **Variáveis sensíveis**: Armazenadas em `.env` e variáveis de ambiente, nunca commitadas -- **Autenticação do Vertex AI**: Utilize credenciais com permissão para uso do Vertex AI -- **Isolamento de banco de dados**: Credenciais separadas por ambiente -- **Validação de dados**: Pydantic garante tipagem e validação em todos os endpoints -- **CORS**: Configurável para ambientes específicos +- `POST /chat` + - entrada principal do orquestrador ---- +### Tools -## 📝 Como Usar +- `GET /tools/` +- `POST /tools/` +- `GET /tools/{tool_id}` +- `DELETE /tools/{tool_id}` -Para mais detalhes sobre instalação, configuração e uso, consulte os documentos: +### Mock -- [DEPLOY_SERVIDOR.md](DEPLOY_SERVIDOR.md) - Deploy em servidor Linux (systemd + Nginx) -- [TEST_CASES.md](TEST_CASES.md) - Casos de teste e exemplos +Endpoints diretos para depuração e testes manuais dos handlers: ---- +- `POST /mock/consultar-estoque` +- `POST /mock/validar-cliente-venda` +- `POST /mock/avaliar-veiculo-troca` +- `POST /mock/agendar-revisao` +- `POST /mock/listar-agendamentos-revisao` +- `POST /mock/cancelar-agendamento-revisao` +- `POST /mock/editar-data-revisao` +- `POST /mock/realizar-pedido` +- `POST /mock/cancelar-pedido` -## 📚 Estrutura de Dados +Documentação interativa: +- `GET /docs` -### Tabela: tools +## Execução Local -Armazena metadados das ferramentas disponíveis: +### Sem Docker -- Nome e descrição -- Parâmetros obrigatórios e opcionais -- Endpoint correspondente -- Estado (ativa/inativa) +```bash +uvicorn app.main:app --reload +``` -### Histórico de Interações +### Com Docker Compose -Logs de todas as chamadas para fins de auditoria e análise. +```bash +docker-compose up +``` ---- +Arquivos úteis: +- `TEST_CASES.md` +- `DEPLOY_SERVIDOR.md` +- `.env.example` -## 🌐 APIs Disponíveis +## Variáveis de Ambiente -| Método | Endpoint | Descrição | -| ------ | --------- | ---------------------------------- | -| POST | `/chat` | Enviar mensagem e processar com IA | -| GET | `/docs` | Documentação interativa (Swagger) | -| GET | `/health` | Status da aplicação | -| GET | `/tools` | Listar ferramentas disponíveis | -| POST | `/tools` | Registrar nova ferramenta | +Principais variáveis: ---- +### Vertex AI -## 🔄 Próximas Melhorias +- `GOOGLE_PROJECT_ID` +- `GOOGLE_LOCATION` +- `VERTEX_MODEL_NAME` -O projeto está em evolução contínua com planos para: +### Banco de tools -- Autenticação e autorização de usuários -- Rate limiting e proteção contra abuso -- Persistência de histórico de conversa -- Analytics de uso de ferramentas -- Testes end-to-end automatizados -- Suporte a múltiplos modelos de IA -- Dashboard de administração +- `DB_HOST` +- `DB_PORT` +- `DB_USER` +- `DB_PASSWORD` +- `DB_NAME` +- `DB_CLOUD_SQL_CONNECTION_NAME` ---- +### Banco mock -## 📧 Contato +- `MOCK_DB_HOST` +- `MOCK_DB_PORT` +- `MOCK_DB_USER` +- `MOCK_DB_PASSWORD` +- `MOCK_DB_NAME` +- `MOCK_DB_CLOUD_SQL_CONNECTION_NAME` +- `MOCK_SEED_ENABLED` +- `AUTO_SEED_TOOLS` +- `AUTO_SEED_MOCK` -Para dúvidas, sugestões ou contribuições, entre em contato com o time de desenvolvimento. +### Telegram ---- +- `TELEGRAM_BOT_TOKEN` +- `TELEGRAM_POLLING_TIMEOUT` +- `TELEGRAM_REQUEST_TIMEOUT` ## Telegram Satellite Service -Foi adicionado um servico satelite dedicado ao Telegram. - -Arquivos principais: +Existe um serviço satélite para atendimento via Telegram em long polling. -- `app/integrations/telegram_satellite_service.py`: interface Telegram via long polling, chamando o `OrquestradorService` +Arquivo principal: +- `app/integrations/telegram_satellite_service.py` -Como executar: +Execução: ```bash python -m app.integrations.telegram_satellite_service ``` -Variaveis necessarias: - -- `TELEGRAM_BOT_TOKEN` -- `TELEGRAM_POLLING_TIMEOUT` (opcional, padrao `30`) -- `TELEGRAM_REQUEST_TIMEOUT` (opcional, padrao `45`) +Esse serviço: +- consome mensagens do Telegram +- cria ou recupera o usuário interno +- encaminha a mensagem para o `OrquestradorService` +- envia a resposta de volta ao chat + +## Estado Atual do Projeto + +O sistema já está além de um MVP simples de tool calling. Hoje ele combina: +- decisão assistida por modelo +- execução determinística de tools +- memória volátil por usuário +- fluxos multi-etapas +- múltiplos pedidos na mesma conversa + +Pontos que ainda permanecem em aberto: +- persistência real de histórico conversacional +- suíte automatizada de testes +- evolução da autonomia do modelo +- alinhamento contínuo entre prompts, fluxo e regras de negócio