atendentepro 0.6.3__tar.gz → 0.6.4__tar.gz

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

@@ -5,6 +5,26 @@ 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.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 +33,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.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.6.3
+Version: 0.6.4
 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,7 @@ 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)
 - [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
 
@@ -712,80 +713,328 @@ 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
+# Configuração por agente (sobrescreve global)
 agents:
-  # Agentes que respondem uma vez
-  knowledge: true
-  confirmation: true
-  answer: true
+  # 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
   
-  # Agentes que precisam de múltiplas interações
-  interview: false
-  flow: false
-  onboarding: false
+  # Opcionais
+  flow: true           # Menu: apresenta e volta
+  escalation: true     # Registra e volta
+  feedback: true       # Coleta feedback e volta
 ```
 
-### Comportamento
+### Fluxo Visual
 
-Quando `single_reply=True`:
+**Com single_reply=True:**
 
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (responde uma vez)
-                            ↓
-                       [Triage] ← (retorno automático)
+[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
+
+agents:
+  knowledge: true      # FAQ
+  answer: true         # Perguntas gerais
+  confirmation: true   # Confirmações
+  
+  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
 
-Quando `single_reply=False` (padrão):
+### Fluxo Visual
 
 ```
-[Usuário] → [Triage] → [Knowledge]
-                            ↓
-                    (pode continuar)
-                            ↕
-                       [Usuário]
+┌────────────────────────────────────────────────┐
+│         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)              │
+└────────────────────────────────────────────────┘
 ```
 
 ---