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 # 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. 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
## 📖 Visão Geral - deixar o modelo interpretar a intenção do usuário
- usar ferramentas do sistema quando precisar consultar dados ou executar ações
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. - devolver uma resposta objetiva ao usuário
**Fluxo de funcionamento:** 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.
1. Cliente envia uma mensagem descrevendo uma ação desejada ## Visão Geral
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) O domínio atual do projeto cobre dois fluxos principais:
4. O sistema extrai parâmetros da mensagem e executa a ferramenta - vendas
5. Resultado é formatado e retornado ao cliente de forma natural - revisão/pós-venda
**Exemplo prático:** O sistema consegue:
- consultar estoque de veículos
``` - validar cliente para compra
Cliente: "Gostaria de comprar um carro de até 50000 reais que seja sedan" - avaliar veículo para troca
↓ - criar pedido de compra
IA decide: chamar ferramenta "consultar_estoque" - cancelar pedido
↓ - agendar revisão
Sistema busca no banco de dados - listar revisões agendadas
↓ - cancelar revisão
Retorna: "Encontrei 5 veículos sedans disponíveis até R$ 50.000..." - 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 | Núcleo do orquestrador:
| ------------------- | ------------------ | ------------------------------------------------ | - coordenação do fluxo conversacional
| **Backend** | FastAPI | Framework web moderno e rápido para APIs Python | - controle de contexto ativo
| **IA/LLM** | Google Vertex AI | Plataforma de IA empresarial com Gemini 1.5 Pro | - fila de pedidos
| **Banco de Dados (Tools)** | PostgreSQL | Banco relacional para metadados de ferramentas | - construção de prompts
| **Banco Fictício (Mock)** | MySQL | Dados de negócio simulados usados pelos handlers | - fallback de resposta
| **Containerização** | Docker | Isolamento e execução consistente |
| **Runtime** | Python 3.11+ | Linguagem principal da aplicação |
--- ### `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
``` ### `services/ai`
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
```
--- 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 | ### `services/user`
| ------------------------- | ------------------------------------------------- |
| **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 |
--- 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
``` Arquivos principais:
┌─────────────┐ - `app/db/mock_database.py`
│ Cliente │ "Comprar carro por até 50mil" - `app/db/mock_models.py`
└──────┬──────┘ - `app/db/mock_seed.py`
│
▼
┌──────────────────────────┐
│ 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
└──────────────────┘
```
--- 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 - `POST /chat`
- **Autenticação do Vertex AI**: Utilize credenciais com permissão para uso do Vertex AI - entrada principal do orquestrador
- **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
--- ### 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) Endpoints diretos para depuração e testes manuais dos handlers:
- [TEST_CASES.md](TEST_CASES.md) - Casos de teste e exemplos
--- - `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 ```bash
- Parâmetros obrigatórios e opcionais uvicorn app.main:app --reload
- Endpoint correspondente ```
- Estado (ativa/inativa)
### 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 | Principais variáveis:
| ------ | --------- | ---------------------------------- |
| 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 |
--- ### 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 - `DB_HOST`
- Rate limiting e proteção contra abuso - `DB_PORT`
- Persistência de histórico de conversa - `DB_USER`
- Analytics de uso de ferramentas - `DB_PASSWORD`
- Testes end-to-end automatizados - `DB_NAME`
- Suporte a múltiplos modelos de IA - `DB_CLOUD_SQL_CONNECTION_NAME`
- Dashboard de administração
--- ### 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 ## Telegram Satellite Service
Foi adicionado um servico satelite dedicado ao Telegram. Existe um serviço satélite para atendimento via Telegram em long polling.
Arquivos principais:
- `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 ```bash
python -m app.integrations.telegram_satellite_service python -m app.integrations.telegram_satellite_service
``` ```
Variaveis necessarias: Esse serviço:
- consome mensagens do Telegram
- `TELEGRAM_BOT_TOKEN` - cria ou recupera o usuário interno
- `TELEGRAM_POLLING_TIMEOUT` (opcional, padrao `30`) - encaminha a mensagem para o `OrquestradorService`
- `TELEGRAM_REQUEST_TIMEOUT` (opcional, padrao `45`) - 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