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

📝 docs(readme): alinhar documentacao com a arquitetura atual do orquestrador

Browse Source 
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.
main
Vitor Hugo Belorio Simão 1 month ago
parent a412f9c674
commit e955d64306
1 changed files with 255 additions and 197 deletions
Show Stats Download Patch File Download Diff File

452
README.md
Unescape Escape View File

@ -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

Write Preview
Loading…
Cancel
Save