atendentepro 0.5.6__py3-none-any.whl → 0.5.7__py3-none-any.whl

atendentepro/__init__.py

@@ -144,6 +144,14 @@ from atendentepro.utils import (
     get_async_client,
     get_provider,
     configure_tracing,
+    # MonkAI Trace
+    configure_monkai_trace,
+    get_monkai_hooks,
+    set_monkai_user,
+    set_monkai_input,
+    run_with_monkai_tracking,
+    # Application Insights
+    configure_application_insights,
 )
 
 __all__ = [
@@ -225,5 +233,13 @@ __all__ = [
     "get_async_client",
     "get_provider",
     "configure_tracing",
+    # MonkAI Trace
+    "configure_monkai_trace",
+    "get_monkai_hooks",
+    "set_monkai_user",
+    "set_monkai_input",
+    "run_with_monkai_tracking",
+    # Application Insights
+    "configure_application_insights",
 ]
 

atendentepro/utils/__init__.py

@@ -7,13 +7,34 @@ from .openai_client import (
     AsyncClient,
     Provider,
 )
-from .tracing import configure_tracing
+from .tracing import (
+    # MonkAI Trace (recommended)
+    configure_monkai_trace,
+    get_monkai_hooks,
+    set_monkai_user,
+    set_monkai_input,
+    run_with_monkai_tracking,
+    # Application Insights (Azure)
+    configure_application_insights,
+    # Legacy
+    configure_tracing,
+)
 
 __all__ = [
+    # OpenAI Client
     "get_async_client",
     "get_provider",
     "AsyncClient",
     "Provider",
+    # MonkAI Trace
+    "configure_monkai_trace",
+    "get_monkai_hooks",
+    "set_monkai_user",
+    "set_monkai_input",
+    "run_with_monkai_tracking",
+    # Application Insights
+    "configure_application_insights",
+    # Legacy
     "configure_tracing",
 ]
 

atendentepro/utils/tracing.py

@@ -2,20 +2,200 @@
 """
 Tracing configuration for AtendentePro.
 
-Provides optional Application Insights integration for telemetry.
+Provides optional tracing integrations:
+- MonkAI Trace (recommended): Full agent tracking with token segmentation
+- Application Insights: Azure telemetry
+
+MonkAI Trace: https://github.com/BeMonkAI/monkai-trace
 """
 
 from __future__ import annotations
 
 import logging
-from typing import Optional
+import os
+from typing import Optional, Any, TYPE_CHECKING
 
 from atendentepro.config import get_config
 
+if TYPE_CHECKING:
+    from agents import Agent
+
 logger = logging.getLogger(__name__)
 
 
-def configure_tracing(connection_string: Optional[str] = None) -> bool:
+# =============================================================================
+# MONKAI TRACE INTEGRATION
+# =============================================================================
+
+_MONKAI_HOOKS: Optional[Any] = None
+
+
+def configure_monkai_trace(
+    tracer_token: Optional[str] = None,
+    namespace: Optional[str] = None,
+    inactivity_timeout: int = 120,
+    batch_size: int = 1,
+) -> bool:
+    """
+    Configure MonkAI Trace for agent tracking.
+    
+    MonkAI Trace provides comprehensive agent monitoring with:
+    - Automatic session management
+    - Token segmentation (input, output, process, memory)
+    - Multi-agent handoff tracking
+    - Web search and tool tracking
+    
+    Args:
+        tracer_token: MonkAI tracer token (or env MONKAI_TRACER_TOKEN)
+        namespace: Namespace for grouping traces (default: "atendentepro")
+        inactivity_timeout: Session timeout in seconds (default: 120)
+        batch_size: Upload batch size, 1 for real-time (default: 1)
+        
+    Returns:
+        True if MonkAI Trace was configured, False otherwise.
+        
+    Example:
+        >>> from atendentepro.utils import configure_monkai_trace
+        >>> configure_monkai_trace(tracer_token="tk_your_token")
+        True
+        
+        >>> # Or via environment variable
+        >>> # export MONKAI_TRACER_TOKEN="tk_your_token"
+        >>> configure_monkai_trace()
+        True
+    """
+    global _MONKAI_HOOKS
+    
+    # Get token from parameter or environment
+    token = tracer_token or os.environ.get("MONKAI_TRACER_TOKEN")
+    
+    if not token:
+        logger.debug("No MonkAI tracer token provided. MonkAI Trace disabled.")
+        return False
+    
+    try:
+        from monkai_trace.integrations.openai_agents import MonkAIRunHooks
+        
+        _MONKAI_HOOKS = MonkAIRunHooks(
+            tracer_token=token,
+            namespace=namespace or "atendentepro",
+            inactivity_timeout=inactivity_timeout,
+            batch_size=batch_size,
+        )
+        
+        logger.info(f"MonkAI Trace configured successfully (namespace: {namespace or 'atendentepro'})")
+        return True
+        
+    except ImportError:
+        logger.warning(
+            "MonkAI Trace not available. "
+            "Install 'monkai-trace' for agent tracking: pip install monkai-trace"
+        )
+        return False
+    except Exception as e:
+        logger.error(f"Failed to configure MonkAI Trace: {e}")
+        return False
+
+
+def get_monkai_hooks() -> Optional[Any]:
+    """
+    Get the configured MonkAI Run Hooks.
+    
+    Returns:
+        MonkAIRunHooks instance if configured, None otherwise.
+        
+    Example:
+        >>> hooks = get_monkai_hooks()
+        >>> if hooks:
+        ...     result = await Runner.run(agent, messages, hooks=hooks)
+    """
+    return _MONKAI_HOOKS
+
+
+def set_monkai_user(user_id: str) -> None:
+    """
+    Set the user ID for MonkAI session tracking.
+    
+    Useful for multi-user scenarios like WhatsApp bots.
+    
+    Args:
+        user_id: Unique user identifier (phone, email, etc.)
+        
+    Example:
+        >>> set_monkai_user("5511999999999")  # WhatsApp
+        >>> set_monkai_user("user@email.com")  # Email
+    """
+    if _MONKAI_HOOKS:
+        _MONKAI_HOOKS.set_user_id(user_id)
+
+
+def set_monkai_input(user_input: str) -> None:
+    """
+    Set the user input for MonkAI tracking.
+    
+    Call this before running the agent to capture the user message.
+    
+    Args:
+        user_input: The user's message/query
+        
+    Example:
+        >>> set_monkai_input("Como faço para cancelar minha assinatura?")
+        >>> result = await Runner.run(agent, messages, hooks=get_monkai_hooks())
+    """
+    if _MONKAI_HOOKS:
+        _MONKAI_HOOKS.set_user_input(user_input)
+
+
+async def run_with_monkai_tracking(
+    agent: "Agent",
+    user_input: str,
+    user_id: Optional[str] = None,
+) -> Any:
+    """
+    Run an agent with MonkAI tracking enabled.
+    
+    This is the recommended way to run agents with full tracking.
+    Captures internal tools (web_search, file_search) automatically.
+    
+    Args:
+        agent: The agent to run
+        user_input: User's message/query
+        user_id: Optional user identifier for session management
+        
+    Returns:
+        RunResult from the agent execution
+        
+    Example:
+        >>> from atendentepro.utils import configure_monkai_trace, run_with_monkai_tracking
+        >>> configure_monkai_trace(tracer_token="tk_your_token")
+        >>> result = await run_with_monkai_tracking(network.triage, "Olá!")
+    """
+    if not _MONKAI_HOOKS:
+        # Fallback to normal execution without tracking
+        from agents import Runner
+        return await Runner.run(agent, user_input)
+    
+    try:
+        from monkai_trace.integrations.openai_agents import MonkAIRunHooks
+        
+        if user_id:
+            _MONKAI_HOOKS.set_user_id(user_id)
+        
+        # Use run_with_tracking for full internal tools capture
+        return await MonkAIRunHooks.run_with_tracking(agent, user_input, _MONKAI_HOOKS)
+        
+    except Exception as e:
+        logger.error(f"Error running with MonkAI tracking: {e}")
+        # Fallback to normal execution
+        from agents import Runner
+        return await Runner.run(agent, user_input)
+
+
+# =============================================================================
+# APPLICATION INSIGHTS INTEGRATION (Azure)
+# =============================================================================
+
+def configure_application_insights(connection_string: Optional[str] = None) -> bool:
     """
     Configure Application Insights tracing if connection string is available.
     
@@ -69,3 +249,15 @@ def configure_tracing(connection_string: Optional[str] = None) -> bool:
         logger.error(f"Failed to configure tracing: {e}")
         return False
 
+
+# =============================================================================
+# LEGACY ALIAS
+# =============================================================================
+
+def configure_tracing(connection_string: Optional[str] = None) -> bool:
+    """
+    Legacy alias for configure_application_insights.
+    
+    Deprecated: Use configure_monkai_trace() or configure_application_insights().
+    """
+    return configure_application_insights(connection_string)

{atendentepro-0.5.6.dist-info → atendentepro-0.5.7.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: atendentepro
-Version: 0.5.6
+Version: 0.5.7
 Summary: Sistema de Atendimento Inteligente com Múltiplos Agentes IA - Biblioteca independente e modular baseada no OpenAI Agents SDK
 Author-email: BeMonkAI <contato@monkai.com.br>
 Maintainer-email: BeMonkAI <contato@monkai.com.br>
@@ -79,6 +79,7 @@ Uma biblioteca Python modular para criar sistemas de atendimento automatizado us
 - [Escalation Agent](#-escalation-agent)
 - [Feedback Agent](#-feedback-agent)
 - [Fluxo de Handoffs](#-fluxo-de-handoffs)
+- [Tracing e Monitoramento](#-tracing-e-monitoramento)
 - [Suporte](#-suporte)
 
 ---
@@ -609,6 +610,83 @@ network = create_standard_network(
 
 ---
 
+## 📊 Tracing e Monitoramento
+
+### MonkAI Trace (Recomendado)
+
+Integração com [MonkAI Trace](https://github.com/BeMonkAI/monkai-trace) para monitoramento completo de agentes:
+
+```bash
+pip install monkai-trace
+```
+
+```python
+from atendentepro import (
+    activate,
+    create_standard_network,
+    configure_monkai_trace,
+    run_with_monkai_tracking,
+)
+
+# 1. Ativar biblioteca
+activate("ATP_seu-token")
+
+# 2. Configurar MonkAI Trace
+configure_monkai_trace(
+    tracer_token="tk_seu_token_monkai",  # ou env MONKAI_TRACER_TOKEN
+    namespace="meu-projeto",
+)
+
+# 3. Criar rede
+network = create_standard_network(...)
+
+# 4. Executar com tracking
+result = await run_with_monkai_tracking(
+    agent=network.triage,
+    user_input="Olá, preciso de ajuda",
+    user_id="user123",  # Opcional: para sessões multi-usuário
+)
+```
+
+**Recursos do MonkAI Trace:**
+- ✅ Tracking automático de sessões
+- ✅ Segmentação de tokens (input, output, process, memory)
+- ✅ Rastreamento de handoffs entre agentes
+- ✅ Captura de ferramentas internas (web_search, RAG)
+- ✅ Suporte multi-usuário (WhatsApp, chat)
+
+### Uso Avançado
+
+```python
+from atendentepro import (
+    get_monkai_hooks,
+    set_monkai_user,
+    set_monkai_input,
+)
+from agents import Runner
+
+# Para controle manual
+hooks = get_monkai_hooks()
+set_monkai_user("5511999999999")  # WhatsApp
+set_monkai_input("Como cancelar?")
+
+result = await Runner.run(network.triage, messages, hooks=hooks)
+```
+
+### Application Insights (Azure)
+
+Para Azure, use Application Insights:
+
+```python
+from atendentepro import configure_application_insights
+
+configure_application_insights(
+    connection_string="InstrumentationKey=..."
+)
+```
+
+---
+
 ## 🤝 Suporte
 
 - 📧 **Email:** contato@monkai.com.br

{atendentepro-0.5.6.dist-info → atendentepro-0.5.7.dist-info}/RECORD

@@ -1,5 +1,5 @@
 atendentepro/README.md,sha256=AMVMJlVOlXcwU_kRGBiIoSn8hASLHrhZwxV1jr1LJsU,43012
-atendentepro/__init__.py,sha256=r_9RwvfKcvcS6bk2a1sdQsQyf_CUW-tljE-vh3TeLyw,5150
+atendentepro/__init__.py,sha256=A7ANs1G18HZEhl-C_OVVdOzM0KCRDo-sX1Veq4IYwDo,5572
 atendentepro/license.py,sha256=rlPtysXNqAzEQkP2VjUAVu_nMndhPgfKv1yN2ruUYVI,17570
 atendentepro/network.py,sha256=s7h9if2oS_15BL8VoONjMlihEFCkJqdHxR5WFL81gl4,17310
 atendentepro/agents/__init__.py,sha256=OcPhG1Dp6xe49B5YIti4HVmaZDoDIrFLfRa8GmI4jpQ,1638
@@ -32,12 +32,12 @@ atendentepro/prompts/onboarding.py,sha256=78fSIh2ifsGeoav8DV41_jnyU157c0dtggJujc
 atendentepro/prompts/triage.py,sha256=bSdEVheGy03r5P6MQuv7NwhN2_wrt0mK80F9f_LskRU,1283
 atendentepro/templates/__init__.py,sha256=kSXiDXVIZKKsSn2GuHBcHsnXqVRcNWyBzRlKl9HYoCI,1137
 atendentepro/templates/manager.py,sha256=KdE4khWDMD2S607TDTMkvJ8lZzQ9D_TD_lBaXYSTBzI,17932
-atendentepro/utils/__init__.py,sha256=6EgS4DrW4fG17JdaHNKWMpzicigfFLVJO2VxPV73k9c,334
+atendentepro/utils/__init__.py,sha256=WCJ6_btsLaI6xxHXvNHNue-nKrXWTKscNZGTToQiJ8A,833
 atendentepro/utils/openai_client.py,sha256=R0ns7SU36vTgploq14-QJMTke1pPxcAXlENDeoHU0L4,4552
-atendentepro/utils/tracing.py,sha256=HQ3l4IiNcesCJ6l5qcERWyeBQav0G1ea-H8Rei6eQpE,2319
-atendentepro-0.5.6.dist-info/licenses/LICENSE,sha256=TF6CdXxePoT9DXtPnCejiU5mUwWzrFzd1iyWJyoMauA,983
-atendentepro-0.5.6.dist-info/METADATA,sha256=ujtXRzOUoraqgh2a4hX9qP7pTKEXNS5S5QoZ0Kj64v0,19013
-atendentepro-0.5.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-atendentepro-0.5.6.dist-info/entry_points.txt,sha256=OP0upzqJF3MLS6VX-M-5BfUwx5YLJO2sJ3YBAp4e6yI,89
-atendentepro-0.5.6.dist-info/top_level.txt,sha256=BFasD4SMmgDUmWKlTIZ1PeuukoRBhyiMIz8umKWVCcs,13
-atendentepro-0.5.6.dist-info/RECORD,,
+atendentepro/utils/tracing.py,sha256=kpTPw1PF4rR1qq1RyBnAaPIQIJRka4RF8MfG_JrRJ7U,8486
+atendentepro-0.5.7.dist-info/licenses/LICENSE,sha256=TF6CdXxePoT9DXtPnCejiU5mUwWzrFzd1iyWJyoMauA,983
+atendentepro-0.5.7.dist-info/METADATA,sha256=sNb7PC8RcGrtRtciak-J_yiJedDxquF7N2mtl_4QwFo,20757
+atendentepro-0.5.7.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+atendentepro-0.5.7.dist-info/entry_points.txt,sha256=OP0upzqJF3MLS6VX-M-5BfUwx5YLJO2sJ3YBAp4e6yI,89
+atendentepro-0.5.7.dist-info/top_level.txt,sha256=BFasD4SMmgDUmWKlTIZ1PeuukoRBhyiMIz8umKWVCcs,13
+atendentepro-0.5.7.dist-info/RECORD,,