atendentepro 0.5.6__tar.gz → 0.5.9__tar.gz

{atendentepro-0.5.6 → atendentepro-0.5.9}/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.5.9] - 2025-01-07
+
+### Changed
+- Descrição PyPI formal: "Framework de orquestração de agentes IA"
+- README profissional com foco em capacidades corporativas
+- Tabela de capacidades técnicas no README
+
+## [0.5.8] - 2025-01-07
+
+### Changed
+- Updated PyPI description to highlight all agent types
+- Added new keywords: triage, handoff, escalation, feedback, knowledge-base, interview
+- Changed `tracing` optional dependency to use `monkai-trace`
+- Added `azure` optional dependency for Application Insights
+
+## [0.5.7] - 2025-01-07
+
+### Added
+- MonkAI Trace integration for comprehensive agent monitoring
+- New functions: `configure_monkai_trace`, `run_with_monkai_tracking`
+- Session management with `set_monkai_user`, `set_monkai_input`
+- Token segmentation support (input, output, process, memory)
+- Multi-user session tracking for WhatsApp/chat bots
+- Documentation for tracing setup in README
+
+### Changed
+- Renamed `configure_tracing` to `configure_application_insights` (legacy alias kept)
+
 ## [0.5.6] - 2025-01-07
 
 ### Added

atendentepro-0.5.6/README.md → atendentepro-0.5.9/PKG-INFO

@@ -1,12 +1,81 @@
-# AtendentePro 🤖
+Metadata-Version: 2.4
+Name: atendentepro
+Version: 0.5.9
+Summary: Framework de orquestração de agentes IA para resolver interações complexas integrando múltiplas fontes de dados (documentos, APIs, bancos) em uma única plataforma inteligente.
+Author-email: BeMonkAI <contato@monkai.com.br>
+Maintainer-email: BeMonkAI <contato@monkai.com.br>
+License: Proprietary
+Project-URL: Homepage, https://github.com/BeMonkAI/atendentepro
+Project-URL: Documentation, https://github.com/BeMonkAI/atendentepro#readme
+Project-URL: Repository, https://github.com/BeMonkAI/atendentepro
+Project-URL: Issues, https://github.com/BeMonkAI/atendentepro/issues
+Project-URL: Changelog, https://github.com/BeMonkAI/atendentepro/blob/main/CHANGELOG.md
+Keywords: ai,agents,customer-service,chatbot,openai,multi-agent,atendimento,openai-agents,conversational-ai,rag,triage,handoff,escalation,feedback,knowledge-base,interview
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Communications :: Chat
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai-agents>=0.3.3
+Requires-Dist: openai>=1.107.1
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: isort>=5.12.0; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.5.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
+Provides-Extra: rag
+Requires-Dist: PyPDF2>=3.0.0; extra == "rag"
+Requires-Dist: python-docx>=0.8.11; extra == "rag"
+Requires-Dist: python-pptx>=0.6.21; extra == "rag"
+Requires-Dist: PyMuPDF>=1.23.0; extra == "rag"
+Provides-Extra: tracing
+Requires-Dist: monkai-trace>=0.2.9; extra == "tracing"
+Provides-Extra: azure
+Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "azure"
+Requires-Dist: azure-monitor-opentelemetry-exporter>=1.0.0; extra == "azure"
+Provides-Extra: all
+Requires-Dist: atendentepro[azure,dev,docs,rag,tracing]; extra == "all"
+Dynamic: license-file
+
+# AtendentePro
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://badge.fury.io/py/atendentepro.svg)](https://pypi.org/project/atendentepro/)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
 
-**Sistema de Atendimento Inteligente com Múltiplos Agentes IA**
+**Framework de orquestração de agentes IA para interações complexas**
 
-Uma biblioteca Python modular para criar sistemas de atendimento automatizado usando múltiplos agentes de IA especializados baseados no [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+Plataforma que unifica múltiplos agentes especializados para resolver demandas que envolvem diferentes fontes de dados, sistemas e fluxos de decisão — tudo orquestrado em um único lugar. Baseado no [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+
+### Principais Capacidades
+
+| Capacidade | Descrição |
+|------------|-----------|
+| **Classificação Inteligente** | Identifica a intenção e direciona para o agente especializado |
+| **Integração de Dados** | Conecta documentos (RAG), CSVs, bancos de dados SQL e APIs externas |
+| **Orquestração de Fluxos** | Handoffs automáticos entre agentes conforme a complexidade da demanda |
+| **Escalonamento Controlado** | Transferência para atendimento humano com contexto preservado |
+| **Gestão de Feedbacks** | Sistema de tickets para reclamações, sugestões e acompanhamento |
+| **Configuração Declarativa** | Personalização completa via arquivos YAML |
 
 ---
 
@@ -23,6 +92,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)
 
 ---
@@ -33,8 +103,8 @@ Uma biblioteca Python modular para criar sistemas de atendimento automatizado us
 # Via PyPI
 pip install atendentepro
 
-# Ou via pip com versão específica
-pip install atendentepro==0.5.3
+# Com monitoramento (recomendado)
+pip install atendentepro[tracing]
 ```
 
 ---
@@ -553,6 +623,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
@@ -562,26 +709,56 @@ network = create_standard_network(
 
 ## 📝 Changelog
 
+### v0.5.9 (Atual)
+- Descrição PyPI formal: "Framework de orquestração de agentes IA"
+- README profissional com foco em capacidades corporativas
+
+### v0.5.8
+- Novos keywords: triage, handoff, escalation, feedback, knowledge-base
+- Dependência `tracing` agora usa `monkai-trace`
+
+### v0.5.7
+- **MonkAI Trace**: Integração completa para monitoramento de agentes
+- Novas funções: `configure_monkai_trace`, `run_with_monkai_tracking`
+- Suporte multi-usuário para WhatsApp/chat
+
+### v0.5.6
+- **Agentes configuráveis**: `include_knowledge=False`, `include_flow=False`, etc.
+- Permite criar redes sem agentes específicos
+
+### v0.5.5
+- Workflow PyPI apenas com tags de versão
+
+### v0.5.4
+- Documentação completa standalone no PyPI
+
 ### v0.5.3
-- Documentação completa no README para PyPI
+- Links de documentação corrigidos para PyPI
 
 ### v0.5.2
-- Atualização de contatos (monkai.com.br)
+- Contatos atualizados (monkai.com.br)
 
 ### v0.5.1
 - Prompts modulares para Escalation e Feedback
 - Remoção de handoff circular Answer→Interview
 
 ### v0.5.0
-- Novo: Feedback Agent (tickets/SAC)
+- **Novo**: Feedback Agent (tickets/SAC)
+- Ferramentas: criar_ticket, consultar_ticket, listar_meus_tickets
 
 ### v0.4.0
-- Novo: Escalation Agent (transferência humana)
+- **Novo**: Escalation Agent (transferência humana)
+- Verificação de horário, prioridade automática, webhooks
 
 ### v0.3.0
-- Sistema de licenciamento
+- Sistema de licenciamento com tokens
 - Publicação inicial no PyPI
 
+### v0.2.0
+- Arquitetura modular completa
+- 8 agentes especializados
+- Sistema de templates YAML
+
 ---
 
-**Made with ❤️ by MonkAI**
+**Made with ❤️ by [MonkAI](https://www.monkai.com.br)**

atendentepro-0.5.6/PKG-INFO → atendentepro-0.5.9/README.md

@@ -1,68 +1,23 @@
-Metadata-Version: 2.4
-Name: atendentepro
-Version: 0.5.6
-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>
-License: Proprietary
-Project-URL: Homepage, https://github.com/BeMonkAI/atendentepro
-Project-URL: Documentation, https://github.com/BeMonkAI/atendentepro#readme
-Project-URL: Repository, https://github.com/BeMonkAI/atendentepro
-Project-URL: Issues, https://github.com/BeMonkAI/atendentepro/issues
-Project-URL: Changelog, https://github.com/BeMonkAI/atendentepro/blob/main/CHANGELOG.md
-Keywords: ai,agents,customer-service,chatbot,openai,multi-agent,atendimento,openai-agents,conversational-ai,rag
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: License :: Other/Proprietary License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
-Classifier: Topic :: Communications :: Chat
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: openai-agents>=0.3.3
-Requires-Dist: openai>=1.107.1
-Requires-Dist: pydantic>=2.0.0
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: python-dotenv>=1.0.0
-Requires-Dist: httpx>=0.27.0
-Requires-Dist: numpy>=1.24.0
-Requires-Dist: scikit-learn>=1.3.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
-Requires-Dist: black>=23.0.0; extra == "dev"
-Requires-Dist: isort>=5.12.0; extra == "dev"
-Requires-Dist: mypy>=1.0.0; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: mkdocs>=1.5.0; extra == "docs"
-Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
-Provides-Extra: rag
-Requires-Dist: PyPDF2>=3.0.0; extra == "rag"
-Requires-Dist: python-docx>=0.8.11; extra == "rag"
-Requires-Dist: python-pptx>=0.6.21; extra == "rag"
-Requires-Dist: PyMuPDF>=1.23.0; extra == "rag"
-Provides-Extra: tracing
-Requires-Dist: opentelemetry-sdk>=1.20.0; extra == "tracing"
-Requires-Dist: azure-monitor-opentelemetry-exporter>=1.0.0; extra == "tracing"
-Provides-Extra: all
-Requires-Dist: atendentepro[dev,docs,rag,tracing]; extra == "all"
-Dynamic: license-file
-
-# AtendentePro 🤖
+# AtendentePro
 
 [![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
 [![PyPI version](https://badge.fury.io/py/atendentepro.svg)](https://pypi.org/project/atendentepro/)
 [![License: Proprietary](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
 
-**Sistema de Atendimento Inteligente com Múltiplos Agentes IA**
+**Framework de orquestração de agentes IA para interações complexas**
 
-Uma biblioteca Python modular para criar sistemas de atendimento automatizado usando múltiplos agentes de IA especializados baseados no [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+Plataforma que unifica múltiplos agentes especializados para resolver demandas que envolvem diferentes fontes de dados, sistemas e fluxos de decisão — tudo orquestrado em um único lugar. Baseado no [OpenAI Agents SDK](https://github.com/openai/openai-agents-python).
+
+### Principais Capacidades
+
+| Capacidade | Descrição |
+|------------|-----------|
+| **Classificação Inteligente** | Identifica a intenção e direciona para o agente especializado |
+| **Integração de Dados** | Conecta documentos (RAG), CSVs, bancos de dados SQL e APIs externas |
+| **Orquestração de Fluxos** | Handoffs automáticos entre agentes conforme a complexidade da demanda |
+| **Escalonamento Controlado** | Transferência para atendimento humano com contexto preservado |
+| **Gestão de Feedbacks** | Sistema de tickets para reclamações, sugestões e acompanhamento |
+| **Configuração Declarativa** | Personalização completa via arquivos YAML |
 
 ---
 
@@ -79,6 +34,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)
 
 ---
@@ -89,8 +45,8 @@ Uma biblioteca Python modular para criar sistemas de atendimento automatizado us
 # Via PyPI
 pip install atendentepro
 
-# Ou via pip com versão específica
-pip install atendentepro==0.5.3
+# Com monitoramento (recomendado)
+pip install atendentepro[tracing]
 ```
 
 ---
@@ -609,6 +565,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
@@ -618,26 +651,56 @@ network = create_standard_network(
 
 ## 📝 Changelog
 
+### v0.5.9 (Atual)
+- Descrição PyPI formal: "Framework de orquestração de agentes IA"
+- README profissional com foco em capacidades corporativas
+
+### v0.5.8
+- Novos keywords: triage, handoff, escalation, feedback, knowledge-base
+- Dependência `tracing` agora usa `monkai-trace`
+
+### v0.5.7
+- **MonkAI Trace**: Integração completa para monitoramento de agentes
+- Novas funções: `configure_monkai_trace`, `run_with_monkai_tracking`
+- Suporte multi-usuário para WhatsApp/chat
+
+### v0.5.6
+- **Agentes configuráveis**: `include_knowledge=False`, `include_flow=False`, etc.
+- Permite criar redes sem agentes específicos
+
+### v0.5.5
+- Workflow PyPI apenas com tags de versão
+
+### v0.5.4
+- Documentação completa standalone no PyPI
+
 ### v0.5.3
-- Documentação completa no README para PyPI
+- Links de documentação corrigidos para PyPI
 
 ### v0.5.2
-- Atualização de contatos (monkai.com.br)
+- Contatos atualizados (monkai.com.br)
 
 ### v0.5.1
 - Prompts modulares para Escalation e Feedback
 - Remoção de handoff circular Answer→Interview
 
 ### v0.5.0
-- Novo: Feedback Agent (tickets/SAC)
+- **Novo**: Feedback Agent (tickets/SAC)
+- Ferramentas: criar_ticket, consultar_ticket, listar_meus_tickets
 
 ### v0.4.0
-- Novo: Escalation Agent (transferência humana)
+- **Novo**: Escalation Agent (transferência humana)
+- Verificação de horário, prioridade automática, webhooks
 
 ### v0.3.0
-- Sistema de licenciamento
+- Sistema de licenciamento com tokens
 - Publicação inicial no PyPI
 
+### v0.2.0
+- Arquitetura modular completa
+- 8 agentes especializados
+- Sistema de templates YAML
+
 ---
 
-**Made with ❤️ by MonkAI**
+**Made with ❤️ by [MonkAI](https://www.monkai.com.br)**

{atendentepro-0.5.6 → atendentepro-0.5.9}/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-0.5.9/atendentepro/utils/__init__.py

@@ -0,0 +1,40 @@
+# -*- coding: utf-8 -*-
+"""Utility modules for AtendentePro library."""
+
+from .openai_client import (
+    get_async_client,
+    get_provider,
+    AsyncClient,
+    Provider,
+)
+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-0.5.9/atendentepro/utils/tracing.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+"""
+Tracing configuration for AtendentePro.
+
+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
+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__)
+
+
+# =============================================================================
+# 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.
+    
+    Args:
+        connection_string: Optional connection string. If not provided,
+                          uses the value from configuration.
+                          
+    Returns:
+        True if tracing was configured, False otherwise.
+    """
+    config = get_config()
+    conn_str = connection_string or config.application_insights_connection_string
+    
+    if not conn_str:
+        logger.debug("No Application Insights connection string provided. Tracing disabled.")
+        return False
+    
+    try:
+        # Try to configure Application Insights
+        from opentelemetry import trace
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+        
+        # Check if azure monitor is available
+        try:
+            from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
+            
+            exporter = AzureMonitorTraceExporter(connection_string=conn_str)
+            provider = TracerProvider()
+            processor = BatchSpanProcessor(exporter)
+            provider.add_span_processor(processor)
+            trace.set_tracer_provider(provider)
+            
+            logger.info("Application Insights tracing configured successfully.")
+            return True
+            
+        except ImportError:
+            logger.warning(
+                "Azure Monitor exporter not available. "
+                "Install 'azure-monitor-opentelemetry-exporter' for Application Insights support."
+            )
+            return False
+            
+    except ImportError:
+        logger.warning(
+            "OpenTelemetry not available. "
+            "Install 'opentelemetry-sdk' for tracing support."
+        )
+        return False
+    except Exception as e:
+        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 → atendentepro-0.5.9}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "atendentepro"
-version = "0.5.6"
-description = "Sistema de Atendimento Inteligente com Múltiplos Agentes IA - Biblioteca independente e modular baseada no OpenAI Agents SDK"
+version = "0.5.9"
+description = "Framework de orquestração de agentes IA para resolver interações complexas integrando múltiplas fontes de dados (documentos, APIs, bancos) em uma única plataforma inteligente."
 authors = [
     { name = "BeMonkAI", email = "contato@monkai.com.br" }
 ]
@@ -22,6 +22,12 @@ keywords = [
     "openai-agents",
     "conversational-ai",
     "rag",
+    "triage",
+    "handoff",
+    "escalation",
+    "feedback",
+    "knowledge-base",
+    "interview",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -66,11 +72,14 @@ rag = [
     "PyMuPDF>=1.23.0",
 ]
 tracing = [
+    "monkai-trace>=0.2.9",
+]
+azure = [
     "opentelemetry-sdk>=1.20.0",
     "azure-monitor-opentelemetry-exporter>=1.0.0",
 ]
 all = [
-    "atendentepro[dev,docs,rag,tracing]",
+    "atendentepro[dev,docs,rag,tracing,azure]",
 ]
 
 [project.urls]

atendentepro-0.5.6/atendentepro/utils/__init__.py

@@ -1,19 +0,0 @@
-# -*- coding: utf-8 -*-
-"""Utility modules for AtendentePro library."""
-
-from .openai_client import (
-    get_async_client,
-    get_provider,
-    AsyncClient,
-    Provider,
-)
-from .tracing import configure_tracing
-
-__all__ = [
-    "get_async_client",
-    "get_provider",
-    "AsyncClient",
-    "Provider",
-    "configure_tracing",
-]
-

atendentepro-0.5.6/atendentepro/utils/tracing.py

@@ -1,71 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Tracing configuration for AtendentePro.
-
-Provides optional Application Insights integration for telemetry.
-"""
-
-from __future__ import annotations
-
-import logging
-from typing import Optional
-
-from atendentepro.config import get_config
-
-logger = logging.getLogger(__name__)
-
-
-def configure_tracing(connection_string: Optional[str] = None) -> bool:
-    """
-    Configure Application Insights tracing if connection string is available.
-    
-    Args:
-        connection_string: Optional connection string. If not provided,
-                          uses the value from configuration.
-                          
-    Returns:
-        True if tracing was configured, False otherwise.
-    """
-    config = get_config()
-    conn_str = connection_string or config.application_insights_connection_string
-    
-    if not conn_str:
-        logger.debug("No Application Insights connection string provided. Tracing disabled.")
-        return False
-    
-    try:
-        # Try to configure Application Insights
-        from opentelemetry import trace
-        from opentelemetry.sdk.trace import TracerProvider
-        from opentelemetry.sdk.trace.export import BatchSpanProcessor
-        
-        # Check if azure monitor is available
-        try:
-            from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
-            
-            exporter = AzureMonitorTraceExporter(connection_string=conn_str)
-            provider = TracerProvider()
-            processor = BatchSpanProcessor(exporter)
-            provider.add_span_processor(processor)
-            trace.set_tracer_provider(provider)
-            
-            logger.info("Application Insights tracing configured successfully.")
-            return True
-            
-        except ImportError:
-            logger.warning(
-                "Azure Monitor exporter not available. "
-                "Install 'azure-monitor-opentelemetry-exporter' for Application Insights support."
-            )
-            return False
-            
-    except ImportError:
-        logger.warning(
-            "OpenTelemetry not available. "
-            "Install 'opentelemetry-sdk' for tracing support."
-        )
-        return False
-    except Exception as e:
-        logger.error(f"Failed to configure tracing: {e}")
-        return False
-