atendentepro 0.5.2__tar.gz → 0.5.5__tar.gz

{atendentepro-0.5.2 → atendentepro-0.5.5}/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.5] - 2025-01-06
+
+### Fixed
+- GitHub Actions workflow now only triggers PyPI publish on version tags
+
+## [0.5.4] - 2025-01-06
+
+### Changed
+- Complete standalone documentation in README.md for PyPI
+- All documentation now visible directly on PyPI page
+- No external links to private repository
+
+## [0.5.3] - 2025-01-06
+
+### Fixed
+- Documentation links now use absolute GitHub URLs for PyPI compatibility
+- Removed reference to private `examples/` folder
+
 ## [0.5.2] - 2025-01-06
 
 ### Changed

atendentepro-0.5.5/PKG-INFO

@@ -0,0 +1,608 @@
+Metadata-Version: 2.4
+Name: atendentepro
+Version: 0.5.5
+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 🤖
+
+[![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**
+
+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).
+
+---
+
+## 📋 Índice
+
+- [Instalação](#-instalação)
+- [Ativação (Licença)](#-ativação-licença)
+- [Configurar API Key](#-configurar-api-key)
+- [Início Rápido](#-início-rápido)
+- [Arquitetura](#-arquitetura)
+- [Agentes Disponíveis](#-agentes-disponíveis)
+- [Criar Templates Customizados](#-criar-templates-customizados)
+- [Configurações YAML](#-configurações-yaml)
+- [Escalation Agent](#-escalation-agent)
+- [Feedback Agent](#-feedback-agent)
+- [Fluxo de Handoffs](#-fluxo-de-handoffs)
+- [Suporte](#-suporte)
+
+---
+
+## 📦 Instalação
+
+```bash
+# Via PyPI
+pip install atendentepro
+
+# Ou via pip com versão específica
+pip install atendentepro==0.5.3
+```
+
+---
+
+## 🔑 Ativação (Licença)
+
+A biblioteca **requer um token de licença** para funcionar.
+
+### Opção 1: Variável de Ambiente (Recomendado)
+
+```bash
+export ATENDENTEPRO_LICENSE_KEY="ATP_seu-token-aqui"
+```
+
+### Opção 2: Via Código
+
+```python
+from atendentepro import activate
+
+activate("ATP_seu-token-aqui")
+```
+
+### Opção 3: Arquivo .env
+
+```env
+ATENDENTEPRO_LICENSE_KEY=ATP_seu-token-aqui
+OPENAI_API_KEY=sk-sua-chave-openai
+```
+
+### Obter um Token
+
+Entre em contato para obter seu token:
+- 📧 **Email:** contato@monkai.com.br
+- 🌐 **Site:** https://www.monkai.com.br
+
+---
+
+## 🔐 Configurar API Key
+
+### OpenAI
+
+```bash
+# .env
+OPENAI_API_KEY=sk-sua-chave-openai
+```
+
+### Azure OpenAI
+
+```bash
+# .env
+OPENAI_PROVIDER=azure
+AZURE_API_KEY=sua-chave-azure
+AZURE_API_ENDPOINT=https://seu-recurso.openai.azure.com
+AZURE_API_VERSION=2024-02-15-preview
+AZURE_DEPLOYMENT_NAME=gpt-4o
+```
+
+### Via Código
+
+```python
+from atendentepro import activate, configure
+
+activate("ATP_seu-token")
+
+configure(
+    openai_api_key="sk-sua-chave-openai",
+    default_model="gpt-4o-mini"
+)
+```
+
+---
+
+## ⚡ Início Rápido
+
+```python
+import asyncio
+from pathlib import Path
+from atendentepro import activate, create_standard_network
+from agents import Runner
+
+# 1. Ativar
+activate("ATP_seu-token")
+
+async def main():
+    # 2. Criar rede de agentes
+    network = create_standard_network(
+        templates_root=Path("./meu_cliente"),
+        client="config"
+    )
+    
+    # 3. Executar conversa
+    result = await Runner.run(
+        network.triage,
+        [{"role": "user", "content": "Olá, preciso de ajuda"}]
+    )
+    
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+---
+
+## 🏗️ Arquitetura
+
+```
+┌────────────────────────────────────────────────────────────────────────────┐
+│                              ATENDENTEPRO                                  │
+├────────────────────────────────────────────────────────────────────────────┤
+│                                                                            │
+│   👤 Usuário                                                               │
+│       │                                                                    │
+│       ▼                                                                    │
+│   ┌─────────────┐                                                         │
+│   │   Triage    │──► Classifica intenção do usuário                       │
+│   └─────────────┘                                                         │
+│         │                                                                  │
+│    ┌────┴────┬─────────┬─────────┬─────────┬─────────┬─────────┐          │
+│    ▼         ▼         ▼         ▼         ▼         ▼         ▼          │
+│ ┌──────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐     │
+│ │ Flow │ │Knowl. │ │Confirm│ │ Usage │ │Onboard│ │Escala.│ │Feedbk.│     │
+│ └──────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘ └───────┘     │
+│    │                                                                       │
+│    ▼                                                                       │
+│ ┌─────────────┐                                                           │
+│ │  Interview  │──► Coleta informações estruturadas                        │
+│ └─────────────┘                                                           │
+│       │                                                                    │
+│       ▼                                                                    │
+│ ┌─────────────┐                                                           │
+│ │   Answer    │──► Sintetiza resposta final                               │
+│ └─────────────┘                                                           │
+│                                                                            │
+│ ══════════════════════════════════════════════════════════════════════    │
+│  📞 Escalation → Transfere para atendimento humano IMEDIATO               │
+│  📝 Feedback   → Registra tickets para resposta POSTERIOR                 │
+│                                                                            │
+└────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🤖 Agentes Disponíveis
+
+| Agente | Descrição | Quando Usar |
+|--------|-----------|-------------|
+| **Triage** | Classifica intenção e direciona | Sempre (ponto de entrada) |
+| **Flow** | Apresenta opções/menu ao usuário | Múltiplas opções disponíveis |
+| **Interview** | Coleta informações através de perguntas | Precisa de dados do usuário |
+| **Answer** | Sintetiza resposta final | Após coletar informações |
+| **Knowledge** | Consulta RAG e dados estruturados | Perguntas sobre documentos/dados |
+| **Confirmation** | Valida com respostas sim/não | Confirmar ações |
+| **Usage** | Responde dúvidas sobre o sistema | "Como funciona?" |
+| **Onboarding** | Cadastro de novos usuários | Novos usuários |
+| **Escalation** | Transfere para humano | Urgente/não resolvido |
+| **Feedback** | Registra tickets | Dúvidas/reclamações/sugestões |
+
+---
+
+## 📁 Criar Templates Customizados
+
+### Estrutura de Pastas
+
+```
+meu_cliente/
+├── triage_config.yaml       # ✅ Obrigatório
+├── flow_config.yaml         # Recomendado
+├── interview_config.yaml    # Recomendado
+├── answer_config.yaml       # Opcional
+├── knowledge_config.yaml    # Opcional
+├── escalation_config.yaml   # Recomendado
+├── feedback_config.yaml     # Recomendado
+├── guardrails_config.yaml   # Recomendado
+└── data/                    # Dados estruturados (CSV, etc.)
+```
+
+### Usar o Template
+
+```python
+from pathlib import Path
+from atendentepro import create_standard_network
+
+network = create_standard_network(
+    templates_root=Path("./"),
+    client="meu_cliente",
+    include_escalation=True,
+    include_feedback=True,
+)
+```
+
+---
+
+## ⚙️ Configurações YAML
+
+### triage_config.yaml (Obrigatório)
+
+Define palavras-chave para classificação:
+
+```yaml
+agent_name: "Triage Agent"
+
+keywords:
+  - agent: "Flow Agent"
+    keywords:
+      - "produto"
+      - "serviço"
+      - "preço"
+  
+  - agent: "Knowledge Agent"
+    keywords:
+      - "documentação"
+      - "manual"
+      - "como funciona"
+  
+  - agent: "Escalation Agent"
+    keywords:
+      - "falar com humano"
+      - "atendente"
+```
+
+### flow_config.yaml
+
+Define opções/menu:
+
+```yaml
+agent_name: "Flow Agent"
+
+topics:
+  - id: 1
+    label: "Vendas"
+    keywords: ["comprar", "preço", "orçamento"]
+    
+  - id: 2
+    label: "Suporte"
+    keywords: ["problema", "erro", "ajuda"]
+    
+  - id: 3
+    label: "Financeiro"
+    keywords: ["pagamento", "boleto", "fatura"]
+```
+
+### interview_config.yaml
+
+Define perguntas para coleta:
+
+```yaml
+agent_name: "Interview Agent"
+
+interview_questions: |
+  Para cada tópico, faça as seguintes perguntas:
+  
+  ## Vendas
+  1. Qual produto você tem interesse?
+  2. Qual quantidade desejada?
+  3. Qual seu email para contato?
+  
+  ## Suporte
+  1. Descreva o problema
+  2. Quando começou?
+  3. Já tentou alguma solução?
+```
+
+### guardrails_config.yaml
+
+Define escopo e restrições:
+
+```yaml
+scope: |
+  Este assistente pode ajudar com:
+  - Informações sobre produtos
+  - Suporte técnico
+  - Dúvidas sobre serviços
+
+forbidden_topics:
+  - "política"
+  - "religião"
+  - "conteúdo adulto"
+
+out_of_scope_message: |
+  Desculpe, não posso ajudar com esse assunto.
+  Posso ajudar com produtos, suporte ou serviços.
+```
+
+---
+
+## 📞 Escalation Agent
+
+Transfere para atendimento humano quando:
+- Usuário solicita explicitamente
+- Tópico não coberto pelo sistema
+- Usuário demonstra frustração
+- Agente não consegue resolver
+
+### escalation_config.yaml
+
+```yaml
+name: "Escalation Agent"
+
+triggers:
+  explicit_request:
+    - "quero falar com um humano"
+    - "atendente humano"
+    - "falar com uma pessoa"
+  
+  frustration:
+    - "você não está me ajudando"
+    - "isso não resolve"
+
+channels:
+  phone:
+    enabled: true
+    number: "0800-123-4567"
+    hours: "Seg-Sex 8h-18h"
+  
+  email:
+    enabled: true
+    address: "atendimento@empresa.com"
+    sla: "Resposta em até 24h"
+  
+  whatsapp:
+    enabled: true
+    number: "(11) 99999-9999"
+
+business_hours:
+  start: 8
+  end: 18
+  days: [monday, tuesday, wednesday, thursday, friday]
+
+messages:
+  greeting: "Entendo que você precisa de um atendimento especializado."
+  out_of_hours: "Nosso atendimento funciona de Seg-Sex, 8h-18h."
+```
+
+### Usar Escalation
+
+```python
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    include_escalation=True,
+    escalation_channels="""
+📞 Telefone: 0800-123-4567 (Seg-Sex 8h-18h)
+📧 Email: atendimento@empresa.com
+💬 WhatsApp: (11) 99999-9999
+""",
+)
+```
+
+---
+
+## 📝 Feedback Agent
+
+Registra tickets para:
+- ❓ **Dúvidas** - Perguntas que precisam de pesquisa
+- 💬 **Feedback** - Opinião sobre produto/serviço
+- 📢 **Reclamação** - Insatisfação formal (prioridade alta)
+- 💡 **Sugestão** - Ideia de melhoria
+- ⭐ **Elogio** - Agradecimento
+- ⚠️ **Problema** - Bug/erro técnico (prioridade alta)
+
+### feedback_config.yaml
+
+```yaml
+name: "Feedback Agent"
+
+protocol_prefix: "SAC"  # Formato: SAC-20240106-ABC123
+
+ticket_types:
+  - name: "duvida"
+    label: "Dúvida"
+    default_priority: "normal"
+    
+  - name: "reclamacao"
+    label: "Reclamação"
+    default_priority: "alta"
+    
+  - name: "sugestao"
+    label: "Sugestão"
+    default_priority: "baixa"
+
+email:
+  enabled: true
+  brand_color: "#660099"
+  brand_name: "Minha Empresa"
+  sla_message: "Retornaremos em até 24h úteis."
+
+priorities:
+  - name: "baixa"
+    sla_hours: 72
+  - name: "normal"
+    sla_hours: 24
+  - name: "alta"
+    sla_hours: 8
+  - name: "urgente"
+    sla_hours: 2
+```
+
+### Usar Feedback
+
+```python
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    include_feedback=True,
+    feedback_protocol_prefix="SAC",
+    feedback_brand_color="#660099",
+    feedback_brand_name="Minha Empresa",
+)
+```
+
+### Diferença: Escalation vs Feedback
+
+| Aspecto | Escalation | Feedback |
+|---------|------------|----------|
+| **Propósito** | Atendimento IMEDIATO | Registro para DEPOIS |
+| **Urgência** | Alta | Pode aguardar |
+| **Canal** | Telefone, chat | Email, ticket |
+| **Protocolo** | ESC-XXXXXX | SAC-XXXXXX |
+| **Quando usar** | "Quero falar com alguém" | "Tenho uma sugestão" |
+
+---
+
+## 🔄 Fluxo de Handoffs
+
+```
+Triage ──► Flow, Knowledge, Confirmation, Usage, Onboarding, Escalation, Feedback
+Flow ────► Interview, Triage, Escalation, Feedback
+Interview► Answer, Escalation, Feedback
+Answer ──► Triage, Escalation, Feedback
+Knowledge► Triage, Escalation, Feedback
+Escalation► Triage, Feedback
+Feedback ► Triage, Escalation
+```
+
+### Configuração de Handoffs
+
+```python
+# Todos os handoffs habilitados (padrão)
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    include_escalation=True,  # Padrão: True
+    include_feedback=True,    # Padrão: True
+)
+
+# Sem Escalation ou Feedback
+network = create_standard_network(
+    templates_root=Path("./meu_cliente"),
+    client="config",
+    include_escalation=False,
+    include_feedback=False,
+)
+```
+
+---
+
+## 🔧 Dependências
+
+- Python 3.9+
+- openai-agents >= 0.3.3
+- openai >= 1.107.1
+- pydantic >= 2.0.0
+- PyYAML >= 6.0
+- python-dotenv >= 1.0.0
+
+---
+
+## 📄 Variáveis de Ambiente
+
+| Variável | Descrição | Obrigatório |
+|----------|-----------|-------------|
+| `ATENDENTEPRO_LICENSE_KEY` | Token de licença | ✅ Sim |
+| `OPENAI_API_KEY` | Chave API OpenAI | ✅ (se OpenAI) |
+| `OPENAI_PROVIDER` | `openai` ou `azure` | Não |
+| `DEFAULT_MODEL` | Modelo padrão | Não |
+| `AZURE_API_KEY` | Chave API Azure | ✅ (se Azure) |
+| `AZURE_API_ENDPOINT` | Endpoint Azure | ✅ (se Azure) |
+| `SMTP_HOST` | Servidor SMTP | Para emails |
+| `SMTP_USER` | Usuário SMTP | Para emails |
+| `SMTP_PASSWORD` | Senha SMTP | Para emails |
+
+---
+
+## 🤝 Suporte
+
+- 📧 **Email:** contato@monkai.com.br
+- 🌐 **Site:** https://www.monkai.com.br
+
+---
+
+## 📝 Changelog
+
+### v0.5.3
+- Documentação completa no README para PyPI
+
+### v0.5.2
+- Atualização de contatos (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)
+
+### v0.4.0
+- Novo: Escalation Agent (transferência humana)
+
+### v0.3.0
+- Sistema de licenciamento
+- Publicação inicial no PyPI
+
+---
+
+**Made with ❤️ by MonkAI**