atendentepro 0.3.0__py3-none-any.whl

atendentepro/README.md

@@ -0,0 +1,890 @@
+# AtendentePro 🤖
+
+**Sistema de Atendimento Inteligente com Múltiplos Agentes IA**
+
+Uma biblioteca Python modular e independente para criar sistemas de atendimento automatizado usando múltiplos agentes de IA especializados baseados no OpenAI Agents SDK.
+
+---
+
+## 📦 Instalação
+
+```bash
+# Ativar ambiente virtual
+source venv/bin/activate
+
+# Instalar a biblioteca
+pip install -e .
+```
+
+---
+
+## 🔑 Ativação (Obrigatório)
+
+A biblioteca AtendentePro **requer um token de licença** para funcionar. Sem ativação, a biblioteca lançará um erro ao tentar criar agentes ou redes.
+
+### Opção 1: Ativar via Código
+
+```python
+from atendentepro import activate
+
+# Ativar a biblioteca
+activate("ATP_seu-token-aqui")
+
+# ✅ Agora pode usar normalmente
+from atendentepro import create_standard_network
+```
+
+### Opção 2: Variável de Ambiente
+
+```bash
+# Definir no terminal ou no .env
+export ATENDENTEPRO_LICENSE_KEY="ATP_seu-token-aqui"
+```
+
+```python
+# A biblioteca ativa automaticamente se encontrar a variável
+from atendentepro import create_standard_network  # ✅ Funciona automaticamente
+```
+
+### Opção 3: Arquivo .env
+
+```bash
+# .env
+ATENDENTEPRO_LICENSE_KEY=ATP_seu-token-aqui
+OPENAI_API_KEY=sua-chave-openai
+```
+
+```python
+from dotenv import load_dotenv
+load_dotenv()
+
+from atendentepro import create_standard_network  # ✅ Funciona automaticamente
+```
+
+### Verificar Status da Licença
+
+```python
+from atendentepro import is_activated, get_license_info
+
+# Verificar se está ativado
+if is_activated():
+    info = get_license_info()
+    print(f"Organização: {info.organization}")
+    print(f"Expira em: {info.expiration or 'Sem expiração'}")
+    print(f"Features: {info.features}")
+```
+
+### Obter um Token
+
+Entre em contato para obter seu token de licença:
+- 📧 **Email:** contato@bemonkai.com
+- 🌐 **Site:** https://bemonkai.com
+
+---
+
+## ⚡ Início Rápido
+
+### 1. Ativar + Configurar Variáveis de Ambiente
+
+```bash
+# Token de licença
+export ATENDENTEPRO_LICENSE_KEY="ATP_seu-token"
+
+# Para OpenAI
+export OPENAI_API_KEY="sua-chave-openai"
+
+# Para Azure OpenAI (opcional)
+export OPENAI_PROVIDER="azure"
+export AZURE_API_KEY="sua-chave-azure"
+export AZURE_API_ENDPOINT="https://seu-endpoint.openai.azure.com"
+export AZURE_API_VERSION="2024-02-15-preview"
+```
+
+### 2. Uso Programático
+
+```python
+from pathlib import Path
+from atendentepro import activate, create_standard_network
+from agents import Runner
+import asyncio
+
+# 1. Ativar (ou use variável de ambiente)
+activate("ATP_seu-token")
+
+async def main():
+    # 2. Criar rede com template específico
+    network = create_standard_network(
+        templates_root=Path("./client_templates"),
+        client="meu_cliente"
+    )
+    
+    # 3. Executar conversa
+    result = await Runner.run(
+        network.triage,
+        [{"role": "user", "content": "Olá, preciso de ajuda"}]
+    )
+    
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+---
+
+## 🏗️ Arquitetura
+
+### Analogia: O Restaurante Inteligente 🍽️
+
+Imagine o **AtendentePro** como um **restaurante sofisticado** onde cada funcionário tem uma função específica:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    🍽️  RESTAURANTE ATENDENTEPRO                        │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                         │
+│   👤 CLIENTE chega e é recebido pelo:                                  │
+│                                                                         │
+│   🚪 RECEPCIONISTA (Triage Agent)                                      │
+│      └─ "Boa noite! Você quer jantar, fazer reserva ou tirar dúvida?"  │
+│         Ele IDENTIFICA a intenção e DIRECIONA para o setor certo.      │
+│                                                                         │
+│   ┌────────────────┬────────────────┬────────────────┬───────────────┐ │
+│   │                │                │                │               │ │
+│   ▼                ▼                ▼                ▼               ▼ │
+│                                                                         │
+│   📋 MAITRE        📚 SOMMELIER     ✅ CONFIRMA      ❓ CONCIERGE     │
+│   (Flow Agent)     (Knowledge)      (Confirmation)   (Usage)          │
+│   "Temos 3        "Nosso vinho     "Confirma a     "Deixa eu         │
+│   opções de       premiado é       reserva para    te explicar       │
+│   menu hoje"      o Malbec 2019"   2 pessoas?"     como funciona"    │
+│                                                                         │
+│   │                                                                     │
+│   ▼                                                                     │
+│                                                                         │
+│   📝 GARÇOM (Interview Agent)                                          │
+│      └─ Coleta as informações: "Quantas pessoas? Alguma alergia?"      │
+│                                                                         │
+│   │                                                                     │
+│   ▼                                                                     │
+│                                                                         │
+│   🍳 CHEF (Answer Agent)                                               │
+│      └─ Prepara a resposta final com todas as informações              │
+│                                                                         │
+│   │                                                                     │
+│   ▼                                                                     │
+│                                                                         │
+│   🎉 PRATO ENTREGUE (Resposta ao usuário)                              │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Traduzindo para o código:**
+
+| Restaurante | AtendentePro | Função |
+|-------------|--------------|--------|
+| 🚪 Recepcionista | **Triage Agent** | Identifica necessidade e direciona |
+| 📋 Maître | **Flow Agent** | Apresenta opções disponíveis |
+| 📝 Garçom | **Interview Agent** | Coleta informações necessárias |
+| 🍳 Chef | **Answer Agent** | Prepara a resposta final |
+| 📚 Sommelier | **Knowledge Agent** | Consulta base de conhecimento |
+| ✅ Confirmador | **Confirmation Agent** | Valida com sim/não |
+| ❓ Concierge | **Usage Agent** | Explica como funciona |
+| 🆕 Recepção VIP | **Onboarding Agent** | Cadastra novos clientes |
+| 🚫 Segurança | **Guardrails** | Define o que pode/não pode ser feito |
+| 📖 Menu/Cardápio | **YAML Configs** | Configurações de cada "funcionário" |
+
+**E os módulos do código?**
+
+```
+atendentepro/                    # 🍽️ O RESTAURANTE
+├── config/                      # ⚙️ Regras gerais (horário, API keys)
+├── agents/                      # 👥 Funcionários (fabricas de agentes)
+├── prompts/                     # 📜 Scripts de atendimento
+├── guardrails/                  # 🚫 Políticas de segurança
+├── templates/                   # 📋 Carrega cardápios personalizados
+├── models/                      # 📦 Formatos de dados
+├── utils/                       # 🔧 Utilitários
+└── network.py                   # 🔗 Como os funcionários se conectam
+
+client_templates/                # 📖 CARDÁPIOS DIFERENTES
+├── standard/                    # Menu básico
+├── restaurante_italiano/        # Menu italiano
+└── sushi_bar/                   # Menu japonês
+```
+
+**Fluxo típico de uma conversa:**
+
+```
+1. Cliente: "Quero fazer um pedido"
+   └─> Recepcionista (Triage) identifica: "É um pedido!"
+   
+2. Recepcionista passa para Maître (Flow)
+   └─> "Temos pizza, massa ou sobremesa. O que prefere?"
+   
+3. Cliente: "Pizza"
+   └─> Maître passa para Garçom (Interview)
+   
+4. Garçom: "Qual sabor? Borda recheada?"
+   └─> Cliente responde as perguntas
+   
+5. Garçom passa para Chef (Answer)
+   └─> "Perfeito! Sua pizza de calabresa com borda recheada
+       será entregue em 30 minutos. Valor: R$ 45,00"
+```
+
+---
+
+### Fluxograma Geral
+
+```mermaid
+flowchart TB
+    subgraph ENTRADA["ENTRADA"]
+        USER[("Usuario")]
+    end
+
+    subgraph CORE["ATENDENTEPRO CORE"]
+        subgraph CONFIG["Configuracao"]
+            ENV[".env"]
+            OPENAI["OpenAI Client"]
+        end
+        
+        subgraph TEMPLATES["Template Manager"]
+            YAML["Arquivos YAML"]
+        end
+    end
+
+    subgraph NETWORK["AGENT NETWORK"]
+        TRIAGE["Triage Agent<br/>Classificacao inicial"]
+        FLOW["Flow Agent<br/>Apresenta opcoes"]
+        INTERVIEW["Interview Agent<br/>Coleta informacoes"]
+        ANSWER["Answer Agent<br/>Resposta final"]
+        KNOWLEDGE["Knowledge Agent<br/>Consulta dados/RAG"]
+        CONFIRMATION["Confirmation Agent<br/>Validacao"]
+        USAGE["Usage Agent<br/>Ajuda"]
+        ONBOARDING["Onboarding Agent<br/>Cadastro"]
+    end
+
+    subgraph TOOLS["TOOLS"]
+        RAG["RAG/Embeddings"]
+        CSV["CSV/Database"]
+        CUSTOM["Custom Tools"]
+    end
+
+    subgraph GUARDRAILS["GUARDRAILS"]
+        SCOPE["Validacao Escopo"]
+    end
+
+    subgraph OUTPUT["SAIDA"]
+        RESPONSE[("Resposta")]
+    end
+
+    USER --> TRIAGE
+    ENV --> OPENAI --> NETWORK
+    YAML --> TEMPLATES --> NETWORK
+    
+    TRIAGE -->|"consulta"| KNOWLEDGE
+    TRIAGE -->|"opcoes"| FLOW
+    TRIAGE -->|"confirmacao"| CONFIRMATION
+    TRIAGE -->|"ajuda"| USAGE
+    TRIAGE -->|"cadastro"| ONBOARDING
+    
+    FLOW -->|"coletar"| INTERVIEW
+    FLOW -->|"voltar"| TRIAGE
+    INTERVIEW -->|"responder"| ANSWER
+    ANSWER -->|"nova pergunta"| TRIAGE
+    
+    KNOWLEDGE --> TRIAGE
+    CONFIRMATION --> TRIAGE
+    USAGE --> TRIAGE
+    ONBOARDING --> TRIAGE
+    
+    KNOWLEDGE --> RAG & CSV & CUSTOM
+    GUARDRAILS --> NETWORK
+    
+    ANSWER --> RESPONSE
+    KNOWLEDGE --> RESPONSE
+```
+
+### Fluxo de Handoffs
+
+```mermaid
+flowchart LR
+    T["Triage"]
+    F["Flow"]
+    I["Interview"]
+    A["Answer"]
+    K["Knowledge"]
+    C["Confirmation"]
+    U["Usage"]
+    O["Onboarding"]
+    
+    T --> F & K & C & U & O
+    F --> I & T
+    I --> A
+    A --> T & I
+    K --> T
+    C --> T
+    U --> T
+    O --> T
+```
+
+### Estrutura de Componentes
+
+```mermaid
+graph TB
+    subgraph LIB["atendentepro/"]
+        CFG["config/"]
+        AGENTS["agents/"]
+        MODELS["models/"]
+        PROMPTS["prompts/"]
+        GUARDS["guardrails/"]
+        TEMPS["templates/"]
+        UTILS["utils/"]
+        NET["network.py"]
+    end
+    
+    subgraph CLI["client_templates/"]
+        STD["standard/"]
+        CUSTOM["meu_cliente/"]
+    end
+    
+    subgraph EX["examples/"]
+        RUN["run_*.py"]
+    end
+    
+    LIB --> CLI --> EX
+    
+    CFG --> AGENTS
+    TEMPS --> AGENTS
+    GUARDS --> AGENTS
+    PROMPTS --> AGENTS
+    MODELS --> AGENTS
+    AGENTS --> NET
+```
+
+### Estrutura da Biblioteca
+
+```
+atendentepro/
+├── __init__.py          # API publica principal
+├── config/              # Configuracoes globais
+├── models/              # Modelos Pydantic
+├── agents/              # Fabricas de agentes
+├── prompts/             # Prompts modulares
+├── guardrails/          # Validacao de escopo
+├── templates/           # Gerenciamento de templates
+├── utils/               # Utilitarios
+└── network.py           # Configuracao de rede
+```
+
+### Templates de Clientes (Externos)
+
+Os templates de clientes ficam **fora** da biblioteca principal, na pasta `client_templates/`:
+
+```
+client_templates/
+├── standard/                # Template base/genérico
+│   ├── triage_config.yaml
+│   ├── flow_config.yaml
+│   ├── interview_config.yaml
+│   ├── answer_config.yaml
+│   ├── knowledge_config.yaml
+│   ├── confirmation_config.yaml
+│   ├── onboarding_config.yaml
+│   └── guardrails_config.yaml
+└── meu_cliente/             # Template específico
+    ├── __init__.py          # (Opcional) Pacote Python
+    ├── network.py           # (Opcional) Rede específica
+    ├── tools.py             # (Opcional) Tools customizadas
+    ├── *.yaml               # Configurações
+    └── data/                # (Opcional) Dados
+```
+
+> ⚠️ **Importante**: Configurações específicas de clientes (como `network.py`, `tools.py`) 
+> ficam SEMPRE na pasta do cliente, não na biblioteca principal `atendentepro`.
+
+---
+
+## 🔧 Agentes Disponíveis
+
+| Agente | Descrição |
+|--------|-----------|
+| **Triage** | Identifica necessidade e direciona para agente especializado |
+| **Flow** | Identifica tópicos e apresenta opções ao usuário |
+| **Interview** | Coleta informações através de perguntas estruturadas |
+| **Answer** | Sintetiza respostas finais com dados coletados |
+| **Knowledge** | Pesquisa em documentos (RAG) e dados estruturados |
+| **Confirmation** | Valida hipóteses com respostas sim/não |
+| **Usage** | Responde dúvidas sobre uso do sistema |
+| **Onboarding** | Acolhe novos usuários e guia cadastro |
+
+---
+
+## 📝 Criando Agentes Individuais
+
+```python
+from atendentepro import (
+    create_triage_agent,
+    create_flow_agent,
+    create_interview_agent,
+)
+
+# Criar agente de triagem customizado
+triage = create_triage_agent(
+    keywords_text="- vendas: 'preço', 'comprar'\n- suporte: 'problema', 'erro'",
+)
+
+# Criar agente de fluxo com tópicos específicos
+flow = create_flow_agent(
+    flow_template="1. Vendas\n2. Suporte\n3. Dúvidas",
+    flow_keywords="- Vendas: 'preço'\n- Suporte: 'erro'",
+)
+
+# Configurar handoffs
+triage.handoffs = [flow]
+```
+
+---
+
+## 🛠️ Criando Seu Próprio Client Template
+
+### Passo 1: Criar a Pasta do Cliente
+
+```bash
+mkdir -p client_templates/meu_cliente
+```
+
+### Passo 2: Criar os Arquivos de Configuração YAML
+
+Copie do `standard/` e customize:
+
+```bash
+cp client_templates/standard/*.yaml client_templates/meu_cliente/
+```
+
+### Passo 3: Configurar o Triage (triage_config.yaml)
+
+Define as palavras-chave para identificar a intenção do usuário:
+
+```yaml
+agent_name: "Triage Agent"
+
+keywords:
+  - agent: "Flow Agent"
+    keywords:
+      - "produto"
+      - "serviço"
+      - "preço"
+  
+  - agent: "Knowledge Agent"
+    keywords:
+      - "documentação"
+      - "manual"
+  
+  - agent: "Usage Agent"
+    keywords:
+      - "como usar"
+      - "ajuda"
+```
+
+### Passo 4: Configurar o Flow (flow_config.yaml)
+
+Define os tópicos/opções que o usuário pode escolher:
+
+```yaml
+agent_name: "Flow Agent"
+
+topics:
+  - id: 1
+    label: "Vendas"
+    keywords:
+      - "preço"
+      - "comprar"
+  
+  - id: 2
+    label: "Suporte Técnico"
+    keywords:
+      - "erro"
+      - "problema"
+  
+  - id: 3
+    label: "Financeiro"
+    keywords:
+      - "pagamento"
+      - "fatura"
+```
+
+### Passo 5: Configurar o Interview (interview_config.yaml)
+
+Define as perguntas para coletar informações:
+
+```yaml
+agent_name: "Interview Agent"
+
+questions:
+  Vendas:
+    - "Qual produto você tem interesse?"
+    - "Qual a quantidade desejada?"
+  
+  Suporte Técnico:
+    - "Qual o erro que está aparecendo?"
+    - "Em qual dispositivo ocorre o problema?"
+```
+
+### Passo 6: Configurar Guardrails (guardrails_config.yaml)
+
+Define limites de escopo para cada agente:
+
+```yaml
+global:
+  out_of_scope_message: "Desculpe, não posso ajudar com isso."
+
+agents:
+  Triage Agent:
+    scope:
+      - "vendas"
+      - "suporte"
+    forbidden:
+      - "política"
+      - "religião"
+```
+
+### Passo 7: Configurar Knowledge (Opcional)
+
+O Knowledge Agent suporta **múltiplas fontes de dados**:
+- 📄 **Documentos** - RAG com embeddings (PDF, TXT, MD)
+- 📊 **Dados Estruturados** - CSV, banco de dados, APIs
+
+#### Apenas Documentos (RAG)
+
+```yaml
+agent_name: "Knowledge Agent"
+
+about: "Base de conhecimento"
+
+embeddings_path: "knowledge_documentos/embedding/embeddings.pkl"
+
+documents:
+  - name: "Manual"
+    path: "docs/manual.pdf"
+  - name: "FAQ"
+    path: "docs/faq.md"
+```
+
+#### Apenas Dados Estruturados
+
+```yaml
+agent_name: "Knowledge Agent"
+
+about: "Consulta de dados"
+
+data_sources:
+  - type: "csv"
+    path: "data/produtos.csv"
+    columns:
+      - name: "codigo"
+        description: "Código do produto"
+      - name: "nome"
+        description: "Nome do produto"
+```
+
+#### Ambos (Documentos + Dados)
+
+```yaml
+agent_name: "Knowledge Agent"
+
+about: "Base de conhecimento e dados"
+
+# Documentos
+embeddings_path: "knowledge_documentos/embedding/embeddings.pkl"
+documents:
+  - name: "Manual"
+    path: "docs/manual.pdf"
+
+# Dados estruturados
+data_sources:
+  - type: "csv"
+    path: "data/produtos.csv"
+    columns:
+      - name: "codigo"
+        description: "Código do produto"
+```
+
+### Passo 8: Criar Tools Customizadas (Opcional)
+
+Se precisar de consultas a dados estruturados:
+
+```python
+# client_templates/meu_cliente/tools.py
+from agents import function_tool
+import csv
+from pathlib import Path
+
+@function_tool
+def buscar_produto(codigo: str = "", nome: str = "") -> str:
+    """Busca produto na base de dados."""
+    csv_path = Path(__file__).parent / "data" / "produtos.csv"
+    
+    resultados = []
+    with open(csv_path, "r", encoding="utf-8") as f:
+        reader = csv.DictReader(f)
+        for row in reader:
+            if codigo and row.get("codigo") == codigo:
+                resultados.append(row)
+            elif nome and nome.lower() in row.get("nome", "").lower():
+                resultados.append(row)
+    
+    if not resultados:
+        return "Nenhum produto encontrado."
+    
+    return "\n".join([f"- {r['nome']} (Cód: {r['codigo']})" for r in resultados])
+```
+
+### Passo 9: Criar Rede Específica (Opcional)
+
+Se precisar de lógica customizada:
+
+```python
+# client_templates/meu_cliente/network.py
+from pathlib import Path
+from atendentepro import AgentNetwork, create_standard_network
+
+from .tools import buscar_produto
+
+def create_meu_cliente_network(templates_root: Path) -> AgentNetwork:
+    """Rede específica para Meu Cliente."""
+    
+    return create_standard_network(
+        templates_root=templates_root,
+        client="meu_cliente",
+        custom_tools={
+            "knowledge": [buscar_produto],
+        },
+    )
+```
+
+```python
+# client_templates/meu_cliente/__init__.py
+from .network import create_meu_cliente_network
+__all__ = ["create_meu_cliente_network"]
+```
+
+### Passo 10: Usar o Template
+
+**Opção A - Rede Padrão:**
+
+```python
+from pathlib import Path
+from atendentepro import create_standard_network
+
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente"
+)
+```
+
+**Opção B - Rede Customizada (handoffs diferentes):**
+
+```python
+from atendentepro import create_custom_network
+
+network = create_custom_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    network_config={
+        "triage": ["flow", "knowledge"],
+        "flow": ["interview"],
+        "interview": ["answer"],
+        "answer": ["triage"],
+    },
+)
+```
+
+**Opção C - Rede Específica do Cliente:**
+
+```python
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path("./client_templates")))
+
+from meu_cliente import create_meu_cliente_network
+
+network = create_meu_cliente_network(
+    templates_root=Path("./client_templates")
+)
+```
+
+### Estrutura Final do Template
+
+```
+client_templates/meu_cliente/
+├── __init__.py              # (Opcional) Pacote Python
+├── network.py               # (Opcional) Rede específica
+├── tools.py                 # (Opcional) Tools customizadas
+├── triage_config.yaml       # ✅ Obrigatório
+├── flow_config.yaml         # ✅ Recomendado
+├── interview_config.yaml    # ✅ Recomendado
+├── answer_config.yaml       # Opcional
+├── knowledge_config.yaml    # Opcional
+├── confirmation_config.yaml # Opcional
+├── onboarding_config.yaml   # Opcional
+├── guardrails_config.yaml   # ✅ Recomendado
+├── data/                    # Opcional (dados estruturados)
+│   └── produtos.csv
+└── knowledge_documentos/    # Opcional (RAG)
+    ├── docs/
+    │   └── manual.pdf
+    └── embedding/
+        └── embeddings.pkl
+```
+
+---
+
+## 🌐 Redes Pré-configuradas
+
+### Rede Standard
+
+```python
+from atendentepro import create_standard_network
+
+network = create_standard_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente"
+)
+```
+
+Configuração padrão de handoffs:
+- Triage → Flow, Confirmation, Knowledge, Usage
+- Flow → Interview, Triage
+- Interview → Answer
+- Answer → Triage, Interview
+- Confirmation → Triage
+- Knowledge → Triage
+- Usage → Triage
+
+### Rede Customizada
+
+```python
+from atendentepro import create_custom_network
+
+network = create_custom_network(
+    templates_root=Path("./client_templates"),
+    client="meu_cliente",
+    network_config={
+        "triage": ["flow", "knowledge"],
+        "flow": ["interview"],
+        "interview": ["answer"],
+        "answer": ["triage"],
+    },
+)
+```
+
+---
+
+## 📚 Exemplo Completo
+
+```python
+import asyncio
+from pathlib import Path
+from atendentepro import create_standard_network
+from agents import Runner
+
+async def main():
+    # 1. Criar rede de agentes
+    network = create_standard_network(
+        templates_root=Path("./client_templates"),
+        client="meu_cliente"
+    )
+    
+    # 2. Conversa interativa
+    messages = []
+    
+    while True:
+        user_input = input("Você: ")
+        if user_input.lower() == "sair":
+            break
+        
+        messages.append({"role": "user", "content": user_input})
+        
+        result = await Runner.run(network.triage, messages)
+        
+        print(f"Assistente: {result.final_output}")
+        messages.append({"role": "assistant", "content": str(result.final_output)})
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+---
+
+## 🔒 Guardrails (Validação de Escopo)
+
+```python
+from atendentepro import get_guardrails_for_agent, set_guardrails_client
+from pathlib import Path
+
+# Configurar guardrails para um cliente
+set_guardrails_client(
+    client_key="meu_cliente",
+    templates_root=Path("./client_templates")
+)
+
+# Obter guardrails para um agente
+guardrails = get_guardrails_for_agent("Triage Agent")
+```
+
+---
+
+## 🔗 Dependências
+
+- `openai-agents>=0.3.3` - OpenAI Agents SDK
+- `openai>=1.107.1` - OpenAI Python SDK
+- `pydantic>=2.0.0` - Validação de dados
+- `PyYAML>=6.0` - Configurações YAML
+- `python-dotenv>=1.0.0` - Variáveis de ambiente
+- `numpy>=1.24.0` - Operações vetoriais (RAG)
+- `scikit-learn>=1.3.0` - Similaridade coseno (RAG)
+
+---
+
+## 📁 Estrutura do Projeto
+
+```
+monkai_atendentepro/
+├── atendentepro/           # Biblioteca principal (genérica)
+│   ├── __init__.py
+│   ├── agents/
+│   ├── config/
+│   ├── guardrails/
+│   ├── models/
+│   ├── prompts/
+│   ├── templates/
+│   ├── utils/
+│   ├── network.py
+│   └── README.md
+├── client_templates/       # Templates de clientes (específicos)
+│   ├── standard/           # Template base
+│   └── meu_cliente/        # Templates customizados
+├── examples/               # Exemplos de uso
+├── venv/                   # Ambiente virtual
+├── pyproject.toml
+├── requirements.txt
+└── setup.py
+```
+
+---
+
+## 📄 Licença
+
+MIT License - BeMonkAI
+
+---
+
+## 🤝 Contribuindo
+
+1. Fork o repositório
+2. Crie sua branch (`git checkout -b feature/nova-feature`)
+3. Commit suas mudanças (`git commit -m 'Adiciona nova feature'`)
+4. Push para a branch (`git push origin feature/nova-feature`)
+5. Abra um Pull Request