diff --git a/README.md b/README.md index e69de29..180e479 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,256 @@ +# 🤖 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** | PostgreSQL | Banco relacional robusto para dados estruturados | +| **Dados de Teste** | Mockaroo | Geração de dados fictícios para simulação | +| **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 +│ │ └── mockaroo_client.py # Cliente para gerar dados fictícios +│ │ +│ ├── 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 PostgreSQL │ +└──────┬───────────────────────────┘ + │ + ▼ +┌──────────────────────────────────┐ +│ 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](GUIA_COMPLETO_CONFIGURE_E_DEPLOY.md) - Setup completo do Google Cloud +- [CLOUD_SQL_PROXY.md](CLOUD_SQL_PROXY.md) - Configuração de Cloud SQL Proxy +- [TEST_CASES.md](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.