atendentepro 0.6.3__tar.gz → 0.6.5__tar.gz

{atendentepro-0.6.3 → atendentepro-0.6.5}/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to AtendentePro will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.6.5] - 2025-01-21
+
+### Added
+- **Scripts de teste de licença**: Novos scripts em `scripts/` para testar o comportamento da biblioteca sem credencial
+  - `scripts/test_without_license.py`: Script para verificar se a biblioteca bloqueia corretamente o uso sem licença
+  - `scripts/TESTE_SEM_CREDENCIAL.md`: Documentação do teste de licença
+
+### Documentation
+- Documentação sobre verificação de licença e comportamento sem credencial
+
+## [0.6.4] - 2025-01-14
+
+### Added
+- **Filtros de Acesso (Role/User)**: Novo sistema de controle de acesso baseado em roles e usuários
+  - `UserContext`: Contexto do usuário com user_id, role e metadata
+  - `AccessFilter`: Filtros whitelist/blacklist para roles e users
+  - `FilteredPromptSection`: Seções de prompt condicionais por role/user
+  - `FilteredTool`: Tools com filtro de acesso
+- **Novos parâmetros em `create_standard_network`**:
+  - `user_context`: Contexto do usuário para filtragem
+  - `agent_filters`: Filtros de agente por role/user
+  - `conditional_prompts`: Prompts condicionais por role/user
+  - `filtered_tools`: Tools filtradas por role/user
+- **Configuração via YAML** (`access_config.yaml`): Suporte a configuração de filtros via arquivo
+- **Exemplos completos**: Pasta `docs/examples/access_filters/` com casos de uso
+
+### Documentation
+- README atualizado com seção completa de Filtros de Acesso
+- Exemplos de código e YAML para diferentes cenários
+
 ## [0.6.3] - 2025-01-12
 
 ### Changed
@@ -13,6 +43,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CI mais rápido**: Cache de pip adicionado e matriz reduzida para Python 3.9 e 3.12
 - Instalação base reduzida de ~300MB para ~50MB
 
+### Added
+- **Exemplos de Single Reply Mode**: Pasta `docs/examples/single_reply/` com exemplos completos
+- Documentação expandida no README com casos de uso práticos (FAQ Bot, Bot de Leads)
+
 ### Fixed
 - Warnings de instalação eliminados com pinagem de versões
 - Tempo de deploy reduzido de ~40min para ~8-10min

{atendentepro-0.6.3 → atendentepro-0.6.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.6.3
+Version: 0.6.5
 Summary: Framework de orquestração de agentes IA com tom e estilo customizáveis. Integra documentos (RAG), APIs e bancos de dados em uma plataforma inteligente multi-agente.
 Author-email: BeMonkAI <contato@monkai.com.br>
 Maintainer-email: BeMonkAI <contato@monkai.com.br>
@@ -95,6 +95,8 @@ Plataforma que unifica múltiplos agentes especializados para resolver demandas
 - [Fluxo de Handoffs](#-fluxo-de-handoffs)
 - [Estilo de Comunicação](#-estilo-de-comunicação-agentstyle)
 - [Single Reply Mode](#-single-reply-mode)
+- [Filtros de Acesso](#-filtros-de-acesso-roleuser)
+- [Múltiplos Agentes](#-múltiplos-agentes-multi-interview--knowledge)
 - [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
 
@@ -712,82 +714,466 @@ agents:
 
 O **Single Reply Mode** permite configurar agentes para responderem apenas uma vez e automaticamente transferirem de volta para o Triage. Isso evita que a conversa fique "presa" em um agente específico.
 
+📂 **Exemplos completos**: [docs/examples/single_reply/](docs/examples/single_reply/)
+
 ### Quando Usar
 
-- **Chatbots de alto volume**: Respostas rápidas e independentes
-- **Consultas simples**: Uma pergunta = uma resposta
-- **Evitar loops**: Impedir que usuários fiquem presos em um agente
+| Cenário | Recomendação |
+|---------|--------------|
+| **Chatbots de alto volume** | ✅ Ativar para respostas rápidas |
+| **FAQ simples** | ✅ Knowledge com single_reply |
+| **Coleta de dados** | ❌ Interview precisa múltiplas interações |
+| **Onboarding** | ❌ Precisa guiar o usuário em etapas |
+| **Confirmações** | ✅ Confirma e volta ao Triage |
 
-### Via Código
+### Exemplo 1: FAQ Bot (Via Código)
+
+Chatbot otimizado para perguntas frequentes:
 
 ```python
 from pathlib import Path
 from atendentepro import create_standard_network
 
-# Ativar para TODOS os agentes
+# FAQ Bot: Knowledge e Answer respondem uma vez
 network = create_standard_network(
     templates_root=Path("./meu_cliente"),
     client="config",
-    global_single_reply=True,  # Todos respondem uma vez
+    global_single_reply=False,
+    single_reply_agents={
+        "knowledge": True,  # FAQ: responde e volta
+        "answer": True,     # Perguntas gerais: responde e volta
+        "flow": True,       # Menu: apresenta e volta
+    },
 )
+```
+
+### Exemplo 2: Bot de Leads (Via Código)
 
-# Ativar apenas para agentes específicos
+Bot que coleta dados mas responde dúvidas rapidamente:
+
+```python
 network = create_standard_network(
     templates_root=Path("./meu_cliente"),
     client="config",
     global_single_reply=False,
     single_reply_agents={
-        "knowledge": True,      # Knowledge responde uma vez
-        "confirmation": True,   # Confirmation responde uma vez
-        "answer": True,         # Answer responde uma vez
-        # interview: False      # Interview pode ter múltiplas interações
+        # Interview PRECISA de múltiplas interações para coletar dados
+        "interview": False,
+        
+        # Outros agentes podem ser rápidos
+        "knowledge": True,    # Tira dúvidas sobre produto
+        "answer": True,       # Responde perguntas
+        "confirmation": True, # Confirma cadastro
     },
 )
 ```
 
+### Exemplo 3: Ativar para TODOS os agentes
+
+```python
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    global_single_reply=True,  # Todos respondem uma vez
+)
+```
+
 ### Via YAML (single_reply_config.yaml)
 
 Crie o arquivo `single_reply_config.yaml` na pasta do cliente:
 
 ```yaml
-# Global: aplica a todos os agentes
+# Global: se true, TODOS os agentes respondem apenas uma vez
+global: false
+
+# Configuração por agente (sobrescreve global)
+agents:
+  # Agentes de consulta: respondem uma vez
+  knowledge: true      # FAQ: responde e volta
+  answer: true         # Perguntas: responde e volta
+  confirmation: true   # Confirma e volta
+  usage: true          # Explica uso e volta
+  
+  # Agentes de coleta: múltiplas interações
+  interview: false     # Precisa coletar dados
+  onboarding: false    # Precisa guiar usuário
+  
+  # Opcionais
+  flow: true           # Menu: apresenta e volta
+  escalation: true     # Registra e volta
+  feedback: true       # Coleta feedback e volta
+```
+
+### Fluxo Visual
+
+**Com single_reply=True:**
+
+```
+[Usuário: "Qual o preço?"]
+         ↓
+    [Triage] → detecta consulta
+         ↓
+  [Knowledge] → responde: "R$ 99,90"
+         ↓
+    [Triage] ← retorno AUTOMÁTICO
+         ↓
+[Usuário: "E a entrega?"]
+         ↓
+    [Triage] → nova análise (ciclo reinicia)
+```
+
+**Com single_reply=False (padrão):**
+
+```
+[Usuário: "Qual o preço?"]
+         ↓
+    [Triage] → detecta consulta
+         ↓
+  [Knowledge] → responde: "R$ 99,90"
+         ↓
+[Usuário: "E a entrega?"]
+         ↓
+  [Knowledge] → continua no mesmo agente
+         ↓
+[Usuário: "Quero falar com humano"]
+         ↓
+  [Knowledge] → handoff para Escalation
+```
+
+### Configuração Recomendada
+
+Para a maioria dos casos de uso:
+
+```yaml
 global: false
 
-# Configuração por agente
 agents:
-  # Agentes que respondem uma vez
-  knowledge: true
-  confirmation: true
-  answer: true
+  knowledge: true      # FAQ
+  answer: true         # Perguntas gerais
+  confirmation: true   # Confirmações
   
-  # Agentes que precisam de múltiplas interações
-  interview: false
-  flow: false
-  onboarding: false
+  interview: false     # Coleta de dados
+  onboarding: false    # Guia de usuário
+```
+
+---
+
+## 🔐 Filtros de Acesso (Role/User)
+
+O sistema de **Filtros de Acesso** permite controlar quais agentes, prompts e tools estão disponíveis para cada usuário ou role (função).
+
+📂 **Exemplos completos**: [docs/examples/access_filters/](docs/examples/access_filters/)
+
+### Quando Usar
+
+| Cenário | Solução |
+|---------|---------|
+| **Multi-tenant** | Diferentes clientes veem diferentes agentes |
+| **Níveis de acesso** | Admin vê mais opções que cliente |
+| **Segurança** | Dados sensíveis só para roles específicas |
+| **Personalização** | Diferentes instruções por departamento |
+
+### Níveis de Filtragem
+
+1. **Agentes**: Habilitar/desabilitar agentes inteiros
+2. **Prompts**: Adicionar seções condicionais aos prompts
+3. **Tools**: Habilitar/desabilitar tools específicas
+
+### Exemplo 1: Filtros de Agente (Via Código)
+
+```python
+from pathlib import Path
+from atendentepro import (
+    create_standard_network,
+    UserContext,
+    AccessFilter,
+)
+
+# Usuário com role de vendedor
+user = UserContext(user_id="vendedor_123", role="vendedor")
+
+# Filtros de agente
+agent_filters = {
+    # Feedback só para admin
+    "feedback": AccessFilter(allowed_roles=["admin"]),
+    # Escalation para todos exceto clientes
+    "escalation": AccessFilter(denied_roles=["cliente"]),
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    agent_filters=agent_filters,
+)
+```
+
+### Exemplo 2: Prompts Condicionais
+
+Adicione instruções específicas baseadas na role:
+
+```python
+from atendentepro import FilteredPromptSection
+
+conditional_prompts = {
+    "knowledge": [
+        # Seção para vendedores
+        FilteredPromptSection(
+            content="\\n## Descontos\\nVocê pode oferecer até 15% de desconto.",
+            filter=AccessFilter(allowed_roles=["vendedor"]),
+        ),
+        # Seção para admin
+        FilteredPromptSection(
+            content="\\n## Admin\\nVocê tem acesso total ao sistema.",
+            filter=AccessFilter(allowed_roles=["admin"]),
+        ),
+    ],
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    conditional_prompts=conditional_prompts,
+)
+```
+
+### Exemplo 3: Tools Filtradas
+
+```python
+from atendentepro import FilteredTool
+from agents import function_tool
+
+@function_tool
+def deletar_cliente(cliente_id: str) -> str:
+    """Remove um cliente do sistema."""
+    return f"Cliente {cliente_id} removido"
+
+filtered_tools = {
+    "knowledge": [
+        FilteredTool(
+            tool=deletar_cliente,
+            filter=AccessFilter(allowed_roles=["admin"]),  # Só admin
+        ),
+    ],
+}
+
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    user_context=user,
+    filtered_tools=filtered_tools,
+)
+```
+
+### Via YAML (access_config.yaml)
+
+```yaml
+# Filtros de agente
+agent_filters:
+  feedback:
+    allowed_roles: ["admin"]
+  escalation:
+    denied_roles: ["cliente"]
+
+# Prompts condicionais
+conditional_prompts:
+  knowledge:
+    - content: |
+        ## Capacidades de Vendedor
+        Você pode oferecer até 15% de desconto.
+      filter:
+        allowed_roles: ["vendedor"]
+
+# Acesso a tools
+tool_access:
+  deletar_cliente:
+    allowed_roles: ["admin"]
+```
+
+### Tipos de Filtro
+
+| Tipo | Descrição | Exemplo |
+|------|-----------|---------|
+| `allowed_roles` | Whitelist de roles | `["admin", "gerente"]` |
+| `denied_roles` | Blacklist de roles | `["cliente"]` |
+| `allowed_users` | Whitelist de usuários | `["user_vip_1"]` |
+| `denied_users` | Blacklist de usuários | `["user_bloqueado"]` |
+
+### Prioridade de Avaliação
+
+1. `denied_users` - Se usuário está negado, **bloqueia**
+2. `allowed_users` - Se lista existe e usuário está nela, **permite**
+3. `denied_roles` - Se role está negada, **bloqueia**
+4. `allowed_roles` - Se lista existe e role não está nela, **bloqueia**
+5. **Permite por padrão** - Se nenhum filtro matched
+
+### Fluxo Visual
+
+```
+┌────────────────────────────────────────────────┐
+│         Requisição: role="vendedor"            │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│              FILTRO DE AGENTES                 │
+│  Knowledge: ✅ (vendedor allowed)              │
+│  Escalation: ✅ (vendedor not denied)          │
+│  Feedback: ❌ (only admin)                     │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│             FILTRO DE PROMPTS                  │
+│  Knowledge recebe: "## Descontos..."           │
+│  (seção condicional para vendedor)             │
+└────────────────────────────────────────────────┘
+                        │
+                        ▼
+┌────────────────────────────────────────────────┐
+│              FILTRO DE TOOLS                   │
+│  consultar_comissao: ✅                        │
+│  deletar_cliente: ❌ (only admin)              │
+└────────────────────────────────────────────────┘
 ```
 
-### Comportamento
+---
+
+## 🔀 Múltiplos Agentes (Multi Interview + Knowledge)
+
+O AtendentePro suporta criar **múltiplas instâncias** de Interview e Knowledge agents, cada um especializado em um domínio diferente.
+
+📂 **Exemplo completo**: [docs/examples/multi_agents/](docs/examples/multi_agents/)
+
+### Caso de Uso
 
-Quando `single_reply=True`:
+Empresa que atende diferentes tipos de clientes:
+- **Pessoa Física (PF)**: Produtos de consumo
+- **Pessoa Jurídica (PJ)**: Soluções empresariais
 
+### Arquitetura
+
+```
+                    ┌─────────────────┐
+                    │     Triage      │
+                    │  (entry point)  │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┼──────────────┐
+              │              │              │
+              ▼              ▼              ▼
+    ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+    │  Interview  │  │  Interview  │  │    Flow     │
+    │     PF      │  │     PJ      │  │   (comum)   │
+    └──────┬──────┘  └──────┬──────┘  └─────────────┘
+           │                │
+           ▼                ▼
+    ┌─────────────┐  ┌─────────────┐
+    │  Knowledge  │  │  Knowledge  │
+    │     PF      │  │     PJ      │
+    └─────────────┘  └─────────────┘
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (responde uma vez)
-                            ↓
-                       [Triage] ← (retorno automático)
+
+### Implementação
+
+```python
+from atendentepro import (
+    create_custom_network,
+    create_triage_agent,
+    create_interview_agent,
+    create_knowledge_agent,
+)
+
+# 1. Criar agentes especializados
+interview_pf = create_interview_agent(
+    interview_questions="CPF, data de nascimento, renda mensal",
+    name="interview_pf",  # Nome único!
+)
+
+interview_pj = create_interview_agent(
+    interview_questions="CNPJ, razão social, faturamento",
+    name="interview_pj",  # Nome único!
+)
+
+knowledge_pf = create_knowledge_agent(
+    knowledge_about="Produtos para consumidor final",
+    name="knowledge_pf",
+    single_reply=True,
+)
+
+knowledge_pj = create_knowledge_agent(
+    knowledge_about="Soluções empresariais B2B",
+    name="knowledge_pj",
+    single_reply=True,
+)
+
+# 2. Criar Triage
+triage = create_triage_agent(
+    keywords_text="PF: CPF, pessoal, minha conta | PJ: CNPJ, empresa, MEI",
+    name="triage_agent",
+)
+
+# 3. Configurar handoffs
+triage.handoffs = [interview_pf, interview_pj, knowledge_pf, knowledge_pj]
+interview_pf.handoffs = [knowledge_pf, triage]
+interview_pj.handoffs = [knowledge_pj, triage]
+knowledge_pf.handoffs = [triage]
+knowledge_pj.handoffs = [triage]
+
+# 4. Criar network customizada
+network = create_custom_network(
+    triage=triage,
+    custom_agents={
+        "interview_pf": interview_pf,
+        "interview_pj": interview_pj,
+        "knowledge_pf": knowledge_pf,
+        "knowledge_pj": knowledge_pj,
+    },
+)
 ```
 
-Quando `single_reply=False` (padrão):
+### Cenários de Roteamento
+
+| Mensagem do Usuário | Rota |
+|---------------------|------|
+| "Quero abrir conta para mim" | Triage → Interview PF → Knowledge PF |
+| "Preciso de maquininha para minha loja" | Triage → Interview PJ → Knowledge PJ |
+| "Quanto custa o cartão gold?" | Triage → Knowledge PF (direto) |
+| "Capital de giro para empresa" | Triage → Knowledge PJ (direto) |
+
+### Padrão: 1 Interview → 2 Knowledge
+
+Outro padrão comum é ter um único Interview que pode direcionar para múltiplos Knowledge:
 
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (pode continuar)
-                            ↕
-                       [Usuário]
+        ┌───────────────┐
+        │   Interview   │
+        │ (coleta dados)│
+        └───────┬───────┘
+                │
+        ┌───────┴───────┐
+        ▼               ▼
+┌───────────────┐ ┌───────────────┐
+│   Knowledge   │ │   Knowledge   │
+│   Produtos    │ │Troubleshooting│
+└───────────────┘ └───────────────┘
+```
+
+```python
+# Um interview que direciona para múltiplos knowledge
+interview.handoffs = [knowledge_produtos, knowledge_troubleshooting, triage]
 ```
 
+📂 **Exemplo completo**: [example_one_interview_two_knowledge.py](docs/examples/multi_agents/example_one_interview_two_knowledge.py)
+
+### Dicas
+
+1. **Nomes únicos**: Cada agente precisa de um `name` distinto
+2. **Handoffs claros**: Configure quais agentes cada um pode chamar
+3. **Keywords no Triage**: Inclua palavras-chave para direcionar corretamente
+4. **single_reply**: Use em Knowledge para evitar loops
+
 ---
 
 ## 📊 Tracing e Monitoramento