atendentepro 0.6.5__tar.gz → 0.6.7__tar.gz

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

@@ -5,6 +5,63 @@ 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.7] - 2025-02-03
+
+### Fixed
+- **Feedback Agent**: Correção crítica - configuração YAML agora é carregada e aplicada
+  - Removida validação hardcoded de tipos de ticket (agora configurável via YAML)
+  - Adicionada persistência de tickets em arquivo JSON (`feedback_tickets.json`)
+  - Tipos de ticket agora são validados contra `feedback_config.yaml`
+  - Configurações de email (brand_color, brand_name, sla_message) agora vêm do YAML
+- **Escalation Agent**: Correção crítica - configuração YAML agora é carregada e aplicada
+  - Business hours agora configurável via `escalation_config.yaml`
+  - Keywords de prioridade (urgent/high) agora configuráveis via YAML
+  - Conversão automática de dias da semana (monday, tuesday, etc.) para números
+- **Answer Agent**: Correção crítica - `answer_config.yaml` agora é carregado e usado
+  - Template de resposta agora vem do arquivo de configuração
+
+### Added
+- **Novos modelos de configuração em TemplateManager**:
+  - `FeedbackConfig`: Modelo Pydantic para `feedback_config.yaml`
+  - `EscalationConfig`: Modelo Pydantic para `escalation_config.yaml`
+  - `AnswerConfig`: Modelo Pydantic para `answer_config.yaml`
+- **Métodos de carregamento**:
+  - `load_feedback_config()`: Carrega configuração do Feedback Agent
+  - `load_escalation_config()`: Carrega configuração do Escalation Agent
+  - `load_answer_config()`: Carrega configuração do Answer Agent
+- **Persistência de tickets**: Sistema de armazenamento em JSON para tickets do Feedback Agent
+  - Configurável via variável de ambiente `FEEDBACK_STORAGE_PATH`
+  - Carregamento automático ao iniciar
+  - Salvamento automático após cada criação/atualização
+
+### Changed
+- **Feedback Agent**: `create_feedback_agent()` agora aceita `ticket_types` da configuração YAML
+- **Escalation Agent**: `create_escalation_agent()` agora aceita `business_hours` e `priority_keywords` da configuração
+- **Network**: `create_standard_network()` agora carrega e aplica configurações YAML automaticamente
+
+## [0.6.6] - 2025-01-21
+
+### Added
+- **User Loader Module**: Sistema de carregamento automático de usuários cadastrados
+  - `create_user_loader()`: Factory para criar loaders customizados
+  - `run_with_user_context()`: Função helper para executar agentes com carregamento automático
+  - `extract_phone_from_messages()`: Extrai telefone das mensagens
+  - `extract_email_from_messages()`: Extrai email das mensagens
+  - `extract_user_id_from_messages()`: Extrai user_id/CPF das mensagens
+  - `load_user_from_csv()`: Helper para carregar usuários de CSV
+- **Novos parâmetros em `create_standard_network`**:
+  - `user_loader`: Função para carregar dados do usuário das mensagens
+  - `auto_load_user`: Flag para carregar usuário automaticamente
+- **Atributos em `AgentNetwork`**:
+  - `user_loader`: Loader configurado na network
+  - `loaded_user_context`: Contexto do usuário carregado
+- **Exemplos completos**: Pasta `docs/examples/user_loader/` com exemplos de CSV e banco de dados
+
+### Documentation
+- README atualizado com seção completa de Carregamento de Usuários
+- Exemplos práticos de uso com CSV, banco de dados e múltiplos identificadores
+- Documentação de integração com onboarding
+
 ## [0.6.5] - 2025-01-21
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.6.5
+Version: 0.6.7
 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>
@@ -96,6 +96,7 @@ Plataforma que unifica múltiplos agentes especializados para resolver demandas
 - [Estilo de Comunicação](#-estilo-de-comunicação-agentstyle)
 - [Single Reply Mode](#-single-reply-mode)
 - [Filtros de Acesso](#-filtros-de-acesso-roleuser)
+- [Carregamento de Usuários](#-carregamento-de-usuários-user-loader)
 - [Múltiplos Agentes](#-múltiplos-agentes-multi-interview--knowledge)
 - [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
@@ -1040,6 +1041,181 @@ tool_access:
 
 ---
 
+## 👤 Carregamento de Usuários (User Loader)
+
+O **User Loader** identifica automaticamente usuários cadastrados nas conversas e carrega suas informações para enriquecer o contexto, permitindo personalização e evitando onboarding desnecessário.
+
+📂 **Exemplos completos**: [docs/examples/user_loader/](docs/examples/user_loader/)
+
+### Quando Usar
+
+| Cenário | Solução |
+|---------|---------|
+| **Usuário existente** | Identifica automaticamente e pula onboarding |
+| **Personalização** | Carrega dados do usuário para respostas personalizadas |
+| **Contexto enriquecido** | Todos os agentes têm acesso a informações do usuário |
+| **Múltiplas fontes** | Suporta CSV, banco de dados, APIs REST, etc. |
+
+### Funcionalidades
+
+1. **Extração automática** de identificadores (telefone, email, CPF, etc.)
+2. **Carregamento de dados** de múltiplas fontes
+3. **Criação automática** de `UserContext`
+4. **Integração transparente** com a rede de agentes
+
+### Exemplo 1: Carregamento de CSV
+
+```python
+from pathlib import Path
+from atendentepro import (
+    create_standard_network,
+    create_user_loader,
+    load_user_from_csv,
+    extract_email_from_messages,
+    run_with_user_context,
+)
+
+# Função para carregar do CSV
+def load_user(identifier: str):
+    return load_user_from_csv(
+        csv_path=Path("users.csv"),
+        identifier_field="email",
+        identifier_value=identifier
+    )
+
+# Criar loader
+loader = create_user_loader(
+    loader_func=load_user,
+    identifier_extractor=extract_email_from_messages
+)
+
+# Criar network com loader
+network = create_standard_network(
+    templates_root=Path("./templates"),
+    user_loader=loader,
+    include_onboarding=True,
+)
+
+# Executar com carregamento automático
+messages = [{"role": "user", "content": "Meu email é joao@example.com"}]
+result = await run_with_user_context(network, network.triage, messages)
+
+# Verificar se usuário foi carregado
+if network.loaded_user_context:
+    print(f"Usuário: {network.loaded_user_context.metadata.get('nome')}")
+```
+
+### Exemplo 2: Carregamento de Banco de Dados
+
+```python
+import sqlite3
+from atendentepro import create_user_loader, extract_email_from_messages
+
+def load_from_db(identifier: str):
+    conn = sqlite3.connect("users.db")
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM users WHERE email = ?", (identifier,))
+    row = cursor.fetchone()
+    conn.close()
+    
+    if row:
+        return {
+            "user_id": row[0],
+            "role": row[1],
+            "nome": row[2],
+            "email": row[3],
+        }
+    return None
+
+loader = create_user_loader(load_from_db, extract_email_from_messages)
+
+network = create_standard_network(
+    templates_root=Path("./templates"),
+    user_loader=loader,
+)
+```
+
+### Exemplo 3: Múltiplos Identificadores
+
+```python
+from atendentepro import (
+    create_user_loader,
+    extract_email_from_messages,
+    extract_phone_from_messages,
+)
+
+def extract_identifier(messages):
+    # Tenta email primeiro
+    email = extract_email_from_messages(messages)
+    if email:
+        return email
+    
+    # Se não encontrou, tenta telefone
+    phone = extract_phone_from_messages(messages)
+    if phone:
+        return phone
+    
+    return None
+
+loader = create_user_loader(
+    loader_func=load_user,
+    identifier_extractor=extract_identifier
+)
+```
+
+### Funções Disponíveis
+
+#### Extratores de Identificador
+
+```python
+from atendentepro import (
+    extract_phone_from_messages,    # Extrai telefone
+    extract_email_from_messages,     # Extrai email
+    extract_user_id_from_messages,  # Extrai CPF/user_id
+)
+```
+
+#### Criar Loader
+
+```python
+from atendentepro import create_user_loader
+
+loader = create_user_loader(
+    loader_func=load_user_function,
+    identifier_extractor=extract_email_from_messages  # Opcional
+)
+```
+
+#### Executar com Contexto
+
+```python
+from atendentepro import run_with_user_context
+
+result = await run_with_user_context(
+    network,
+    network.triage,
+    messages
+)
+```
+
+### Integração com Onboarding
+
+Quando um `user_loader` está configurado:
+
+- ✅ **Usuário encontrado**: Vai direto para o triage, sem passar pelo onboarding
+- ✅ **Usuário não encontrado**: É direcionado para o onboarding normalmente
+- ✅ **Contexto disponível**: Todos os agentes têm acesso a `network.loaded_user_context`
+
+### Benefícios
+
+1. ✅ **Experiência personalizada** - Respostas baseadas em dados do usuário
+2. ✅ **Menos fricção** - Usuários conhecidos não precisam fazer onboarding
+3. ✅ **Contexto rico** - Todos os agentes têm acesso a informações do usuário
+4. ✅ **Flexível** - Suporta múltiplas fontes de dados
+5. ✅ **Automático** - Funciona transparentemente durante a conversa
+
+---
+
 ## 🔀 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.

{atendentepro-0.6.5 → atendentepro-0.6.7}/README.md

@@ -38,6 +38,7 @@ Plataforma que unifica múltiplos agentes especializados para resolver demandas
 - [Estilo de Comunicação](#-estilo-de-comunicação-agentstyle)
 - [Single Reply Mode](#-single-reply-mode)
 - [Filtros de Acesso](#-filtros-de-acesso-roleuser)
+- [Carregamento de Usuários](#-carregamento-de-usuários-user-loader)
 - [Múltiplos Agentes](#-múltiplos-agentes-multi-interview--knowledge)
 - [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
@@ -982,6 +983,181 @@ tool_access:
 
 ---
 
+## 👤 Carregamento de Usuários (User Loader)
+
+O **User Loader** identifica automaticamente usuários cadastrados nas conversas e carrega suas informações para enriquecer o contexto, permitindo personalização e evitando onboarding desnecessário.
+
+📂 **Exemplos completos**: [docs/examples/user_loader/](docs/examples/user_loader/)
+
+### Quando Usar
+
+| Cenário | Solução |
+|---------|---------|
+| **Usuário existente** | Identifica automaticamente e pula onboarding |
+| **Personalização** | Carrega dados do usuário para respostas personalizadas |
+| **Contexto enriquecido** | Todos os agentes têm acesso a informações do usuário |
+| **Múltiplas fontes** | Suporta CSV, banco de dados, APIs REST, etc. |
+
+### Funcionalidades
+
+1. **Extração automática** de identificadores (telefone, email, CPF, etc.)
+2. **Carregamento de dados** de múltiplas fontes
+3. **Criação automática** de `UserContext`
+4. **Integração transparente** com a rede de agentes
+
+### Exemplo 1: Carregamento de CSV
+
+```python
+from pathlib import Path
+from atendentepro import (
+    create_standard_network,
+    create_user_loader,
+    load_user_from_csv,
+    extract_email_from_messages,
+    run_with_user_context,
+)
+
+# Função para carregar do CSV
+def load_user(identifier: str):
+    return load_user_from_csv(
+        csv_path=Path("users.csv"),
+        identifier_field="email",
+        identifier_value=identifier
+    )
+
+# Criar loader
+loader = create_user_loader(
+    loader_func=load_user,
+    identifier_extractor=extract_email_from_messages
+)
+
+# Criar network com loader
+network = create_standard_network(
+    templates_root=Path("./templates"),
+    user_loader=loader,
+    include_onboarding=True,
+)
+
+# Executar com carregamento automático
+messages = [{"role": "user", "content": "Meu email é joao@example.com"}]
+result = await run_with_user_context(network, network.triage, messages)
+
+# Verificar se usuário foi carregado
+if network.loaded_user_context:
+    print(f"Usuário: {network.loaded_user_context.metadata.get('nome')}")
+```
+
+### Exemplo 2: Carregamento de Banco de Dados
+
+```python
+import sqlite3
+from atendentepro import create_user_loader, extract_email_from_messages
+
+def load_from_db(identifier: str):
+    conn = sqlite3.connect("users.db")
+    cursor = conn.cursor()
+    cursor.execute("SELECT * FROM users WHERE email = ?", (identifier,))
+    row = cursor.fetchone()
+    conn.close()
+    
+    if row:
+        return {
+            "user_id": row[0],
+            "role": row[1],
+            "nome": row[2],
+            "email": row[3],
+        }
+    return None
+
+loader = create_user_loader(load_from_db, extract_email_from_messages)
+
+network = create_standard_network(
+    templates_root=Path("./templates"),
+    user_loader=loader,
+)
+```
+
+### Exemplo 3: Múltiplos Identificadores
+
+```python
+from atendentepro import (
+    create_user_loader,
+    extract_email_from_messages,
+    extract_phone_from_messages,
+)
+
+def extract_identifier(messages):
+    # Tenta email primeiro
+    email = extract_email_from_messages(messages)
+    if email:
+        return email
+    
+    # Se não encontrou, tenta telefone
+    phone = extract_phone_from_messages(messages)
+    if phone:
+        return phone
+    
+    return None
+
+loader = create_user_loader(
+    loader_func=load_user,
+    identifier_extractor=extract_identifier
+)
+```
+
+### Funções Disponíveis
+
+#### Extratores de Identificador
+
+```python
+from atendentepro import (
+    extract_phone_from_messages,    # Extrai telefone
+    extract_email_from_messages,     # Extrai email
+    extract_user_id_from_messages,  # Extrai CPF/user_id
+)
+```
+
+#### Criar Loader
+
+```python
+from atendentepro import create_user_loader
+
+loader = create_user_loader(
+    loader_func=load_user_function,
+    identifier_extractor=extract_email_from_messages  # Opcional
+)
+```
+
+#### Executar com Contexto
+
+```python
+from atendentepro import run_with_user_context
+
+result = await run_with_user_context(
+    network,
+    network.triage,
+    messages
+)
+```
+
+### Integração com Onboarding
+
+Quando um `user_loader` está configurado:
+
+- ✅ **Usuário encontrado**: Vai direto para o triage, sem passar pelo onboarding
+- ✅ **Usuário não encontrado**: É direcionado para o onboarding normalmente
+- ✅ **Contexto disponível**: Todos os agentes têm acesso a `network.loaded_user_context`
+
+### Benefícios
+
+1. ✅ **Experiência personalizada** - Respostas baseadas em dados do usuário
+2. ✅ **Menos fricção** - Usuários conhecidos não precisam fazer onboarding
+3. ✅ **Contexto rico** - Todos os agentes têm acesso a informações do usuário
+4. ✅ **Flexível** - Suporta múltiplas fontes de dados
+5. ✅ **Automático** - Funciona transparentemente durante a conversa
+
+---
+
 ## 🔀 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.

{atendentepro-0.6.5 → atendentepro-0.6.7}/atendentepro/__init__.py

@@ -158,6 +158,13 @@ from atendentepro.utils import (
     run_with_monkai_tracking,
     # Application Insights
     configure_application_insights,
+    # User Loader
+    create_user_loader,
+    run_with_user_context,
+    extract_phone_from_messages,
+    extract_email_from_messages,
+    extract_user_id_from_messages,
+    load_user_from_csv,
 )
 
 __all__ = [
@@ -253,5 +260,12 @@ __all__ = [
     "run_with_monkai_tracking",
     # Application Insights
     "configure_application_insights",
+    # User Loader
+    "create_user_loader",
+    "run_with_user_context",
+    "extract_phone_from_messages",
+    "extract_email_from_messages",
+    "extract_user_id_from_messages",
+    "load_user_from_csv",
 ]
 

{atendentepro-0.6.5 → atendentepro-0.6.7}/atendentepro/agents/escalation.py

@@ -47,6 +47,13 @@ DEFAULT_BUSINESS_HOURS = {
     "days": [0, 1, 2, 3, 4],  # Seg-Sex
 }
 
+# Configurable business hours (None = use DEFAULT_BUSINESS_HOURS)
+_configured_business_hours: Optional[Dict[str, Any]] = None
+
+# Configurable priority keywords (None = use defaults)
+_priority_keywords_urgent: Optional[List[str]] = None
+_priority_keywords_high: Optional[List[str]] = None
+
 
 # =============================================================================
 # Storage de Escalações (em memória - substituir por DB em produção)
@@ -139,22 +146,46 @@ def _notificar_equipe(escalation: Escalation) -> bool:
 
 def _verificar_disponibilidade() -> Dict[str, Any]:
     """Verifica se atendimento humano está disponível."""
+    global _configured_business_hours
     agora = datetime.now()
     hora = agora.hour
     dia = agora.weekday()
     
-    # Verificar variáveis de ambiente para horário customizado
-    hora_inicio = int(os.getenv("ESCALATION_HOUR_START", DEFAULT_BUSINESS_HOURS["start"]))
-    hora_fim = int(os.getenv("ESCALATION_HOUR_END", DEFAULT_BUSINESS_HOURS["end"]))
+    # Use configured business hours or fall back to defaults
+    if _configured_business_hours:
+        business_hours = _configured_business_hours
+        hora_inicio = business_hours.get("start", DEFAULT_BUSINESS_HOURS["start"])
+        hora_fim = business_hours.get("end", DEFAULT_BUSINESS_HOURS["end"])
+        days = business_hours.get("days", DEFAULT_BUSINESS_HOURS["days"])
+    else:
+        # Verificar variáveis de ambiente para horário customizado
+        hora_inicio = int(os.getenv("ESCALATION_HOUR_START", DEFAULT_BUSINESS_HOURS["start"]))
+        hora_fim = int(os.getenv("ESCALATION_HOUR_END", DEFAULT_BUSINESS_HOURS["end"]))
+        days = DEFAULT_BUSINESS_HOURS["days"]
+    
+    # Ensure days is a list of integers
+    if isinstance(days, list):
+        days_int = [d if isinstance(d, int) else int(d) for d in days]
+    else:
+        days_int = DEFAULT_BUSINESS_HOURS["days"]
+    
+    disponivel = dia in days_int and hora_inicio <= hora < hora_fim
     
-    disponivel = dia in DEFAULT_BUSINESS_HOURS["days"] and hora_inicio <= hora < hora_fim
+    # Format days for display
+    day_names = ["Segunda", "Terça", "Quarta", "Quinta", "Sexta", "Sábado", "Domingo"]
+    if len(days_int) == 1:
+        dias_atendimento = day_names[days_int[0]]
+    elif len(days_int) == 5 and days_int == [0, 1, 2, 3, 4]:
+        dias_atendimento = "Segunda a Sexta"
+    else:
+        dias_atendimento = ", ".join(day_names[d] for d in sorted(days_int))
     
     return {
         "disponivel": disponivel,
         "hora_atual": agora.strftime("%H:%M"),
-        "dia_semana": ["Segunda", "Terça", "Quarta", "Quinta", "Sexta", "Sábado", "Domingo"][dia],
+        "dia_semana": day_names[dia],
         "horario_atendimento": f"{hora_inicio:02d}:00 - {hora_fim:02d}:00",
-        "dias_atendimento": "Segunda a Sexta",
+        "dias_atendimento": dias_atendimento,
     }
 
 
@@ -166,15 +197,16 @@ def _classificar_prioridade(motivo: str, categoria: str) -> str:
     """
     Classifica automaticamente a prioridade baseado no motivo e categoria.
     """
+    global _priority_keywords_urgent, _priority_keywords_high
     motivo_lower = motivo.lower()
     
-    # Palavras que indicam urgência
-    palavras_urgentes = [
+    # Use configured keywords or defaults
+    palavras_urgentes = _priority_keywords_urgent or [
         "urgente", "emergência", "emergencia", "crítico", "critico",
         "não funciona", "parou", "bloqueado", "cancelar", "prejuízo"
     ]
     
-    palavras_alta = [
+    palavras_alta = _priority_keywords_high or [
         "reclamação", "reclamacao", "insatisfeito", "problema grave",
         "já tentei", "terceira vez", "não resolve"
     ]
@@ -449,6 +481,9 @@ ESCALATION_TOOLS = [
 def create_escalation_agent(
     escalation_triggers: str = "",
     escalation_channels: str = "",
+    business_hours: Optional[Dict[str, Any]] = None,
+    priority_keywords_urgent: Optional[List[str]] = None,
+    priority_keywords_high: Optional[List[str]] = None,
     handoffs: Optional[List] = None,
     tools: Optional[List] = None,
     guardrails: Optional[List["GuardrailCallable"]] = None,
@@ -472,6 +507,9 @@ def create_escalation_agent(
     Args:
         escalation_triggers: Custom triggers for escalation (keywords, situations).
         escalation_channels: Available contact channels description.
+        business_hours: Optional dict with "start", "end", and "days" (list of weekday numbers 0-6 or day names).
+        priority_keywords_urgent: Optional list of keywords that indicate urgent priority.
+        priority_keywords_high: Optional list of keywords that indicate high priority.
         handoffs: List of agents to hand off to (usually triage to return).
         tools: Additional tools (custom notifications, integrations).
         guardrails: List of input guardrails.
@@ -492,6 +530,27 @@ def create_escalation_agent(
         >>> triage.handoffs.append(escalation)
         >>> flow.handoffs.append(escalation)
     """
+    global _configured_business_hours, _priority_keywords_urgent, _priority_keywords_high
+    
+    # Configure business hours
+    if business_hours:
+        # Convert day names to weekday numbers if needed
+        days = business_hours.get("days", [])
+        if days and isinstance(days[0], str):
+            day_map = {
+                "monday": 0, "tuesday": 1, "wednesday": 2, "thursday": 3,
+                "friday": 4, "saturday": 5, "sunday": 6,
+            }
+            days_int = [day_map.get(day.lower(), day) for day in days if day.lower() in day_map]
+            business_hours = {**business_hours, "days": days_int}
+        _configured_business_hours = business_hours
+    else:
+        _configured_business_hours = None
+    
+    # Configure priority keywords
+    _priority_keywords_urgent = priority_keywords_urgent
+    _priority_keywords_high = priority_keywords_high
+    
     if custom_instructions:
         instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
     else: