atendentepro 0.6.5__tar.gz → 0.6.6__tar.gz

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.6.5
+Version: 0.6.6
 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.6}/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.6}/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.6}/atendentepro/network.py

@@ -157,6 +157,10 @@ class AgentNetwork:
     templates_root: Optional[Path] = None
     current_client: str = "standard"
     
+    # User loading
+    user_loader: Optional[Callable[[List], Optional["UserContext"]]] = None
+    loaded_user_context: Optional["UserContext"] = None
+    
     def get_all_agents(self) -> List:
         """Get list of all configured agents."""
         agents = []
@@ -216,6 +220,9 @@ def create_standard_network(
     agent_filters: Optional[Dict[str, AccessFilter]] = None,
     conditional_prompts: Optional[Dict[str, List[FilteredPromptSection]]] = None,
     filtered_tools: Optional[Dict[str, List[FilteredTool]]] = None,
+    # User loading
+    user_loader: Optional[Callable[[List], Optional[UserContext]]] = None,
+    auto_load_user: bool = False,
 ) -> AgentNetwork:
     """
     Create a standard agent network with proper handoff configuration.
@@ -259,6 +266,10 @@ def create_standard_network(
         agent_filters: Dict mapping agent names to AccessFilter (controls agent access).
         conditional_prompts: Dict mapping agent names to list of FilteredPromptSection.
         filtered_tools: Dict mapping agent names to list of FilteredTool.
+        user_loader: Optional function to load user data from messages. Receives list of
+                    messages and returns UserContext or None. See create_user_loader().
+        auto_load_user: If True, automatically loads user context before agent execution.
+                        Requires user_loader to be configured.
         
     Returns:
         Configured AgentNetwork instance.
@@ -686,6 +697,9 @@ def create_standard_network(
         network.onboarding = onboarding
         onboarding.handoffs = [triage]
     
+    # Store user_loader in network for later use
+    network.user_loader = user_loader
+    
     return network
 
 

{atendentepro-0.6.5 → atendentepro-0.6.6}/atendentepro/utils/__init__.py

@@ -19,6 +19,14 @@ from .tracing import (
     # Legacy
     configure_tracing,
 )
+from .user_loader import (
+    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__ = [
     # OpenAI Client
@@ -36,5 +44,12 @@ __all__ = [
     "configure_application_insights",
     # Legacy
     "configure_tracing",
+    # 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.6/atendentepro/utils/user_loader.py

@@ -0,0 +1,335 @@
+# -*- coding: utf-8 -*-
+"""
+User Loader utilities for AtendentePro.
+
+Provides functions to load user data from various sources and create UserContext
+objects for enriching agent conversations with user information.
+"""
+
+from __future__ import annotations
+
+import csv
+import re
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+from atendentepro.models import UserContext
+
+
+def extract_phone_from_messages(messages: List[Dict[str, Any]]) -> Optional[str]:
+    """
+    Extract phone number from user messages.
+    
+    Searches for phone patterns in the first user message.
+    Supports formats: (11) 99999-9999, 11999999999, +55 11 99999-9999, etc.
+    
+    Args:
+        messages: List of message dictionaries with 'role' and 'content' keys.
+        
+    Returns:
+        Phone number string if found, None otherwise.
+        
+    Example:
+        >>> messages = [{"role": "user", "content": "Meu telefone é (11) 99999-8888"}]
+        >>> extract_phone_from_messages(messages)
+        '11999998888'
+    """
+    if not messages:
+        return None
+    
+    # Find first user message
+    user_message = None
+    for msg in messages:
+        if msg.get("role") == "user" and msg.get("content"):
+            user_message = msg["content"]
+            break
+    
+    if not user_message:
+        return None
+    
+    # Phone patterns: (XX) XXXXX-XXXX, XX XXXXXXXX, +55 XX XXXXXXXX, etc.
+    phone_patterns = [
+        r'\(?(\d{2})\)?\s*(\d{4,5})-?(\d{4})',  # (11) 99999-8888 or 11 99999-8888
+        r'\+?55\s*(\d{2})\s*(\d{4,5})-?(\d{4})',  # +55 11 99999-8888
+        r'(\d{10,11})',  # 11999998888
+    ]
+    
+    for pattern in phone_patterns:
+        match = re.search(pattern, user_message)
+        if match:
+            # Extract digits only
+            digits = re.sub(r'\D', '', match.group(0))
+            # Normalize to 10 or 11 digits (with or without area code)
+            if len(digits) >= 10:
+                return digits[-10:] if len(digits) > 10 else digits
+    
+    return None
+
+
+def extract_email_from_messages(messages: List[Dict[str, Any]]) -> Optional[str]:
+    """
+    Extract email address from user messages.
+    
+    Searches for email patterns in user messages.
+    
+    Args:
+        messages: List of message dictionaries with 'role' and 'content' keys.
+        
+    Returns:
+        Email address string if found, None otherwise.
+        
+    Example:
+        >>> messages = [{"role": "user", "content": "Meu email é joao@example.com"}]
+        >>> extract_email_from_messages(messages)
+        'joao@example.com'
+    """
+    if not messages:
+        return None
+    
+    # Find first user message
+    user_message = None
+    for msg in messages:
+        if msg.get("role") == "user" and msg.get("content"):
+            user_message = msg["content"]
+            break
+    
+    if not user_message:
+        return None
+    
+    # Email pattern
+    email_pattern = r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b'
+    match = re.search(email_pattern, user_message)
+    
+    if match:
+        return match.group(0).lower()
+    
+    return None
+
+
+def extract_user_id_from_messages(messages: List[Dict[str, Any]]) -> Optional[str]:
+    """
+    Extract user ID from user messages.
+    
+    Looks for common patterns like "user_id:", "id:", "CPF:", etc.
+    
+    Args:
+        messages: List of message dictionaries with 'role' and 'content' keys.
+        
+    Returns:
+        User ID string if found, None otherwise.
+        
+    Example:
+        >>> messages = [{"role": "user", "content": "Meu CPF é 123.456.789-00"}]
+        >>> extract_user_id_from_messages(messages)
+        '12345678900'
+    """
+    if not messages:
+        return None
+    
+    # Find first user message
+    user_message = None
+    for msg in messages:
+        if msg.get("role") == "user" and msg.get("content"):
+            user_message = msg["content"]
+            break
+    
+    if not user_message:
+        return None
+    
+    # Patterns for user IDs
+    patterns = [
+        (r'(?:user[_\s]?id|id[_\s]?usuario|cpf|documento)[:\s]+([\d\.\-\/]+)', lambda m: re.sub(r'\D', '', m.group(1))),
+        (r'([\d]{11})', lambda m: m.group(1)),  # CPF-like (11 digits)
+        (r'([\d]{14})', lambda m: m.group(1)),  # CNPJ-like (14 digits)
+    ]
+    
+    for pattern, extractor in patterns:
+        match = re.search(pattern, user_message, re.IGNORECASE)
+        if match:
+            return extractor(match)
+    
+    return None
+
+
+def load_user_from_csv(
+    csv_path: Path,
+    identifier_field: str,
+    identifier_value: str,
+) -> Optional[Dict[str, Any]]:
+    """
+    Load user data from a CSV file.
+    
+    Args:
+        csv_path: Path to the CSV file.
+        identifier_field: Name of the column to search (e.g., "email", "telefone", "cpf").
+        identifier_value: Value to search for in the identifier_field column.
+        
+    Returns:
+        Dictionary with user data if found, None otherwise.
+        
+    Example:
+        >>> from pathlib import Path
+        >>> user_data = load_user_from_csv(
+        ...     Path("users.csv"),
+        ...     "email",
+        ...     "joao@example.com"
+        ... )
+        >>> if user_data:
+        ...     print(user_data["nome"])
+    """
+    if not csv_path.exists():
+        return None
+    
+    try:
+        with open(csv_path, 'r', encoding='utf-8') as f:
+            reader = csv.DictReader(f)
+            
+            # Normalize identifier value (remove formatting)
+            normalized_value = re.sub(r'\D', '', str(identifier_value).lower())
+            
+            for row in reader:
+                # Get value from identifier field
+                field_value = row.get(identifier_field, '')
+                # Normalize for comparison
+                normalized_field = re.sub(r'\D', '', str(field_value).lower())
+                
+                if normalized_field == normalized_value:
+                    # Return all row data as dict
+                    return dict(row)
+    
+    except Exception:
+        return None
+    
+    return None
+
+
+def create_user_loader(
+    loader_func: Callable[[str], Optional[Dict[str, Any]]],
+    identifier_extractor: Optional[Callable[[List[Dict[str, Any]]], Optional[str]]] = None,
+) -> Callable[[List[Dict[str, Any]]], Optional[UserContext]]:
+    """
+    Create a user loader function.
+    
+    Factory function that creates a callable that extracts user identifier from
+    messages and loads user data using the provided loader function.
+    
+    Args:
+        loader_func: Function that receives an identifier (str) and returns
+                     user data dict or None if not found.
+        identifier_extractor: Optional function to extract identifier from messages.
+                             If None, tries common extractors (phone, email, user_id).
+                             
+    Returns:
+        Function that receives messages and returns UserContext or None.
+        
+    Example:
+        >>> def load_from_db(identifier: str) -> Optional[Dict]:
+        ...     # Your database lookup logic
+        ...     return {"user_id": "123", "role": "cliente", "nome": "João"}
+        ...
+        >>> loader = create_user_loader(
+        ...     loader_func=load_from_db,
+        ...     identifier_extractor=extract_email_from_messages
+        ... )
+        >>> 
+        >>> messages = [{"role": "user", "content": "joao@example.com"}]
+        >>> user_context = loader(messages)
+        >>> if user_context:
+        ...     print(user_context.user_id)
+    """
+    def load_user(messages: List[Dict[str, Any]]) -> Optional[UserContext]:
+        """
+        Load user context from messages.
+        
+        Args:
+            messages: List of message dictionaries.
+            
+        Returns:
+            UserContext if user found, None otherwise.
+        """
+        # Extract identifier
+        identifier = None
+        if identifier_extractor:
+            identifier = identifier_extractor(messages)
+        else:
+            # Try common extractors in order
+            identifier = (
+                extract_phone_from_messages(messages) or
+                extract_email_from_messages(messages) or
+                extract_user_id_from_messages(messages)
+            )
+        
+        if not identifier:
+            return None
+        
+        # Load user data
+        user_data = loader_func(identifier)
+        if not user_data:
+            return None
+        
+        # Create UserContext
+        return UserContext(
+            user_id=user_data.get("user_id") or identifier,
+            role=user_data.get("role"),
+            metadata={
+                **user_data,  # Include all user data in metadata
+                "loaded_from": "user_loader",
+            }
+        )
+    
+    return load_user
+
+
+async def run_with_user_context(
+    network: Any,
+    agent: Any,
+    messages: List[Dict[str, Any]],
+) -> Any:
+    """
+    Run agent with automatic user context loading.
+    
+    This function automatically loads user data if a user_loader is configured
+    in the network, enriches the network's loaded_user_context, and then runs
+    the agent normally.
+    
+    Args:
+        network: AgentNetwork instance with optional user_loader configured.
+        agent: Agent instance to run.
+        messages: List of message dictionaries.
+        
+    Returns:
+        RunResult from the agent execution.
+        
+    Example:
+        >>> from agents import Runner
+        >>> from atendentepro import create_standard_network, create_user_loader
+        >>> from pathlib import Path
+        >>> 
+        >>> def load_user(identifier: str):
+        ...     # Your loading logic
+        ...     return {"user_id": identifier, "role": "cliente"}
+        >>> 
+        >>> loader = create_user_loader(load_user)
+        >>> network = create_standard_network(
+        ...     templates_root=Path("templates"),
+        ...     user_loader=loader
+        ... )
+        >>> 
+        >>> messages = [{"role": "user", "content": "Olá!"}]
+        >>> result = await run_with_user_context(network, network.triage, messages)
+        >>> print(result.final_output)
+    """
+    from agents import Runner
+    
+    # Load user if loader is configured
+    if hasattr(network, 'user_loader') and network.user_loader:
+        try:
+            user_context = network.user_loader(messages)
+            if user_context:
+                network.loaded_user_context = user_context
+        except Exception:
+            # Silently fail if loading fails - don't break the conversation
+            pass
+    
+    # Run agent normally
+    return await Runner.run(agent, messages)

{atendentepro-0.6.5 → atendentepro-0.6.6}/atendentepro.egg-info/SOURCES.txt

@@ -41,4 +41,5 @@ atendentepro/templates/__init__.py
 atendentepro/templates/manager.py
 atendentepro/utils/__init__.py
 atendentepro/utils/openai_client.py
-atendentepro/utils/tracing.py
+atendentepro/utils/tracing.py
+atendentepro/utils/user_loader.py

{atendentepro-0.6.5 → atendentepro-0.6.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "atendentepro"
-version = "0.6.5"
+version = "0.6.6"
 description = "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."
 authors = [
     { name = "BeMonkAI", email = "contato@monkai.com.br" }