🤖 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..."

---

🛠️ Stack Tecnológico

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 deploy consistente
Orquestração	Google Cloud Build	Pipeline automatizado de build e deploy
Computação	Google Cloud Run	Plataforma serverless escalável
Runtime	Python 3.11+	Linguagem principal da aplicação

---

🏗️ Arquitetura do Projeto

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
├── cloudbuild.yaml                          # Configuração CI/CD (Cloud Build)
├── docker-compose.yml                       # Stack local com PostgreSQL
├── deploy.sh                                # Script de deploy no Cloud Run
├── requirements.txt                         # Dependências Python
├── .env.example                             # Exemplo de configuração
└── README.md                                # Esta documentação

---

🛠️ Ferramentas Disponíveis

O sistema possui as seguintes ferramentas pré-configuradas:

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

---

🚀 Tecnologias em Detalhes

FastAPI

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.

Google Vertex AI + Gemini

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.

PostgreSQL

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.

Docker

Containerização da aplicação garantindo consistência entre ambientes de desenvolvimento, teste e produção.

Google Cloud Build + Cloud Run

Pipeline CI/CD totalmente gerenciado que faz build da imagem, realiza testes e faz deploy automático no Cloud Run (plataforma serverless que escala automaticamente conforme a demanda).

---

📊 Fluxograma de Funcionamento

┌─────────────┐
│   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
└──────────────────┘

---

🔐 Segurança

O sistema foi construído com foco em boas práticas de segurança:

• Variáveis sensíveis: Armazenadas em .env e variáveis de ambiente, nunca commitadas
• Autenticação Google Cloud: Utiliza credenciais de serviço (service account) com roles específicas
• 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
• Cloud Run: Ambiente gerenciado com certificados SSL automáticos

---

📝 Como Usar

Para mais detalhes sobre instalação, configuração e uso, consulte os documentos:

• GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md - Setup completo do Google Cloud
• CLOUD_SQL_PROXY.md - Configuração de Cloud SQL Proxy
• TEST_CASES.md - Casos de teste e exemplos

---

📚 Estrutura de Dados

Tabela: tools

Armazena metadados das ferramentas disponíveis:

• Nome e descrição
• Parâmetros obrigatórios e opcionais
• Endpoint correspondente
• Estado (ativa/inativa)

Histórico de Interações

Logs de todas as chamadas para fins de auditoria e análise.

---

🌐 APIs Disponíveis

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

---

📈 Monitoramento na Produção

Quando implantado no Google Cloud Run, o sistema aproveita:

• Cloud Logging: Logs centralizados e estruturados
• Cloud Monitoring: Métricas de CPU, memória, latência e requisições
• Cloud Trace: Rastreamento distribuído para análise de performance

---

🔄 Próximas Melhorias

O projeto está em evolução contínua com planos para:

• 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

---

📧 Contato

Para dúvidas, sugestões ou contribuições, entre em contato com o time de desenvolvimento.

---

Telegram Satellite Service

Foi adicionado um servico satelite dedicado ao Telegram.

Arquivos principais:

• app/integrations/telegram_satellite_service.py: interface Telegram via long polling, chamando o OrquestradorService

Como executar:

python -m app.integrations.telegram_satellite_service

Variaveis necessarias:

• TELEGRAM_BOT_TOKEN
• TELEGRAM_POLLING_TIMEOUT (opcional, padrao 30)
• TELEGRAM_REQUEST_TIMEOUT (opcional, padrao 45)