🤖 AI Sales Agent

Um agente de vendas autônomo baseado em IA que analisa mensagens de prospects, utiliza conhecimento externo e decide sobre as melhores respostas e ações internas. Este projeto demonstra orquestração avançada de LLM, engenharia de prompts sofisticada e uma estratégia robusta de avaliação.

📋 Índice

• 🎯 Visão Geral
• 🏗️ Arquitetura
• 🚀 Quick Start
• ⚙️ Configuração Detalhada
• 📡 API Endpoints
• 🧪 Testes
• 📊 Monitoramento
• 🔧 Desenvolvimento
• 📈 Avaliação e Métricas

🎯 Visão Geral

Funcionalidades Principais

• 🧠 Orquestração Inteligente de LLM: Análise contextual de mensagens, reconhecimento de intenções e síntese de respostas
• 🔧 Sistema de Ferramentas: KnowledgeAugmentationTool com capacidades de CRM e RAG
• 📚 Pipeline RAG: Busca semântica em base de conhecimento de produtos e playbooks de vendas
• 📊 Monitoramento Completo: Dashboard profissional com métricas de performance do LLM
• 🧪 Framework de Avaliação: Métricas offline e online para melhoria contínua

Tecnologias Utilizadas

• Backend: FastAPI, Python 3.11+
• LLM: OpenAI GPT-4o-mini com function calling
• Vector DB: FAISS para busca semântica
• Embeddings: SentenceTransformers (all-MiniLM-L6-v2)
• Monitoramento: Prometheus + Grafana
• Testes: pytest (251 testes unitários, 100% sucesso)
• Containerização: Docker + Docker Compose

🏗️ Arquitetura

┌─────────────────────────────────────────────────────────────┐
│                     API Layer (FastAPI)                     │
├─────────────────────────────────────────────────────────────┤
│                    Service Layer                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌──────────────┐ │
│  │ OrchestratorSvc │  │ EvaluationSvc   │  │ MemoryService│ │
│  └─────────────────┘  └─────────────────┘  └──────────────┘ │
├─────────────────────────────────────────────────────────────┤
│                   Adapter Layer                             │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ LLM Client  │  │ RAG Client  │  │ KnowledgeAugTool    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                Infrastructure Layer                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  Logging    │  │ Monitoring  │  │    Observability    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

Fluxo de Processamento

1. Análise Inicial: Extração de intenção, entidades e sentimento
2. Decisão de Ferramentas: LLM decide quais ferramentas usar
3. Execução de Ferramentas: CRM lookup e/ou busca RAG
4. Síntese: Geração de resposta estruturada com ações internas

🚀 Quick Start

Pré-requisitos

• Python 3.11+
• Docker e Docker Compose
• Git

Instalação Rápida

# 1. Clone o repositório
git clone https://github.com/seu-usuario/AI-Sales-Agent.git
cd AI-Sales-Agent

# 2. Configure as variáveis de ambiente
cp .env.example .env
# Edite .env com suas configurações

# 3. Execute com Docker
docker-compose up -d

# 4. Acesse a aplicação
# API: http://localhost:8000
# Docs: http://localhost:8000/docs
# Monitoring: http://localhost:3000 (admin/admin123)

Teste Rápido

# Teste o endpoint principal
curl -X POST "http://localhost:8000/api/process_message" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer seu-token" \
  -d '{
    "conversation_history": [
      {"sender": "prospect", "content": "Olá, gostaria de saber sobre seus planos", "timestamp": "2024-01-15T10:00:00Z"}
    ],
    "current_prospect_message": "Qual é o preço do plano profissional?",
    "prospect_id": "prospect-123"
  }'

⚙️ Configuração Detalhada

Desenvolvimento Local

# 1. Clone e setup
git clone https://github.com/seu-usuario/AI-Sales-Agent.git
cd AI-Sales-Agent

# 2. Ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# venv\Scripts\activate     # Windows

# 3. Dependências
pip install -r requirements.txt

# 4. Configuração
cp .env.example .env
# Configure suas variáveis no .env

# 5. Preparar dados
python scripts/setup_embeddings.py

# 6. Executar
uvicorn app.main:app --reload

Configuração com Docker

# Desenvolvimento
docker-compose -f docker-compose.dev.yml up -d

# Produção
docker-compose up -d

# Apenas monitoramento
cd monitoring && docker-compose up -d

Variáveis de Ambiente

Veja .env.example para todas as configurações disponíveis.

Variáveis Obrigatórias:

• OPENAI_API_KEY: Sua chave da OpenAI
• JWT_SECRET_KEY: Chave secreta para JWT
• ENVIRONMENT: development/production

📡 API Endpoints

Core Endpoints

Endpoint	Método	Descrição
/api/process_message	POST	Principal: Processa mensagem do prospect
/health	GET	Health check da aplicação
/metrics	GET	Métricas do Prometheus

Metrics & Evaluation

Endpoint	Método	Descrição
/api/metrics/kpis	GET	KPIs do sistema
/api/metrics/generate_sample_data	GET	Público: Gera dados para dashboard
/api/metrics/user_feedback	POST	Submete feedback do usuário
/api/metrics/evaluate_prompts	POST	Compara variações de prompts

Documentação

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

🧪 Testes

Executar Todos os Testes

# Executar todos os testes
pytest

# Com output limpo
pytest -q

# Com output detalhado
pytest -v

# Com coverage
pytest --cov=app

# Com coverage detalhada + HTML
pytest --cov=app --cov-report=html

Estrutura de Testes

tests/
├── adapters/           # Testes dos adapters (83 testes)
├── core/               # Testes dos services (126 testes)
├── infrastructure/     # Testes de infraestrutura (42 testes)
└── __init__.py         # Configurações básicas

Resultado: ✅ 251 testes passando, 100% sucesso, ~14.5s execução

Testes por Categoria

# Apenas Core Services
pytest tests/core/

# Apenas Adapters
pytest tests/adapters/

# Apenas Infrastructure
pytest tests/infrastructure/

# Parar no primeiro erro
pytest -x

# Executar apenas testes que falharam
pytest --lf

Comandos Úteis

# Ver estatísticas sem executar
pytest --collect-only -q

# Executar testes específicos por nome
pytest -k "test_openai"

# Com cobertura mínima obrigatória
pytest --cov=app --cov-fail-under=80

📊 Monitoramento

Dashboard Profissional

Acesse: http://localhost:3000 (admin/admin123)

Métricas Disponíveis:

• 🧠 Performance Score do LLM (78.5%)
• 🎯 Confidence Score (P95: 79%)
• ⚡ Tempo de Resposta (P95: 2.3s)
• 📩 Taxa de Mensagens (req/s)
• ⚙️ Ações Internas (UPDATE_CRM, SCHEDULE_FOLLOW_UP)
• 🛠️ Performance de Ferramentas (CRM: 100%, RAG: 87%)

Gerar Dados para Dashboard

# Popular todas as métricas
cd monitoring
python generate_test_metrics.py

# Ou via API
curl http://localhost:8000/api/metrics/generate_sample_data

Prometheus Metrics

• URL: http://localhost:9090
• Targets: http://localhost:9090/targets
• Config: monitoring/prometheus/prometheus.yml

🔧 Desenvolvimento

Estrutura do Projeto

app/
├── api/                    # Camada de API
│   ├── dependencies/       # Dependências (auth, etc.)
│   ├── models/            # Modelos Pydantic
│   └── routes/            # Rotas da API
├── core/                  # Lógica de negócio
│   ├── models/            # Modelos de domínio
│   ├── services/          # Serviços principais
│   └── tools/             # KnowledgeAugmentationTool
├── adapters/              # Integrações externas
│   ├── llm/               # Cliente OpenAI
│   ├── rag/               # Pipeline RAG
│   └── crm/               # Mock CRM
├── infrastructure/        # Infraestrutura
│   ├── logging/           # Sistema de logs
│   └── observability/     # Métricas e monitoring
└── data/                  # Dados estáticos
    ├── knowledge_base/    # Documentos para RAG
    ├── golden_set.json    # Dataset de avaliação
    └── crm_mock.json      # Dados mock do CRM

Design Patterns Utilizados

• Strategy Pattern: Diferentes estratégias de análise
• Factory Pattern: Criação de ferramentas
• Repository Pattern: Acesso a dados
• Dependency Injection: Inversão de controle

Adicionando Novas Funcionalidades

1. Nova Ferramenta: Implemente BaseTool em app/core/tools/
2. Novo Serviço: Adicione em app/core/services/
3. Nova Rota: Crie em app/api/routes/
4. Testes: Sempre adicione testes correspondentes

📈 Avaliação e Métricas

Golden Dataset

Localização: app/data/golden_set.json

Estrutura:

• 20 exemplos de conversas diversas
• Ground truth para cada exemplo
• Métricas esperadas definidas

Métricas Offline

• Intent Classification: F1 Score
• Entity Extraction: Precision/Recall
• Response Quality: ROUGE, BLEU, Semantic Similarity
• Tool Usage: Precision para decisões de tool calling

Métricas Online

• LLM Performance Score: Métrica composta (0-1)
• Confidence Score: Média dos confidence scores
• Human Review Rate: % de casos flagged para revisão
• Tool Success Rate: % de chamadas de ferramenta bem-sucedidas
• Response Time: Latência P95

Avaliação de Prompts

# Comparar variações de prompts
curl -X POST "http://localhost:8000/api/metrics/evaluate_prompts" \
  -H "Content-Type: application/json" \
  -d '{
    "variation1": {"name": "Prompt A", "responses": [...]},
    "variation2": {"name": "Prompt B", "responses": [...]}
  }'

KPIs Principais

1. Performance Score: >75% (Atual: 78.5%)
2. Confidence Score: >70% (Atual: 79%)
3. Human Review Rate: <20% (Atual: 15%)
4. Tool Success Rate: >85% (Atual: 87%)
5. Response Time P95: <5s (Atual: 2.3s)

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch (git checkout -b feature/nova-funcionalidade)
3. Commit suas mudanças (git commit -am 'Adiciona nova funcionalidade')
4. Push para a branch (git push origin feature/nova-funcionalidade)
5. Abra um Pull Request

📄 Licença

Este projeto está sob a licença Apache 2.0. Veja o arquivo LICENSE para detalhes.

📞 Contato

Desenvolvedor: Lucas Gabriel
Email: lucasgabriel.vr@gmail.com LinkedIn: linkedin

---

🎯 Desafio Técnico - Backend/AI Engineer
Desenvolvido para demonstrar expertise em LLM Orchestration, System Design e AI Evaluation