atendentepro 0.3.0__py3-none-any.whl → 0.5.2__py3-none-any.whl

atendentepro/license.py

@@ -77,7 +77,7 @@ class LicenseNotActivatedError(LicenseError):
             "║    export ATENDENTEPRO_LICENSE_KEY='seu-token'              ║\n"
             "║                                                              ║\n"
             "║  Para obter um token, entre em contato:                     ║\n"
-            "║  📧 contato@bemonkai.com                                    ║\n"
+            "║  📧 contato@monkai.com.br                                    ║\n"
             "║                                                              ║\n"
             "╚══════════════════════════════════════════════════════════════╝\n"
         )
@@ -96,7 +96,7 @@ class LicenseExpiredError(LicenseError):
             f"║  Sua licença expirou em: {expiration:<36}║\n"
             f"║                                                              ║\n"
             f"║  Para renovar, entre em contato:                            ║\n"
-            f"║  📧 contato@bemonkai.com                                    ║\n"
+            f"║  📧 contato@monkai.com.br                                    ║\n"
             f"║                                                              ║\n"
             f"╚══════════════════════════════════════════════════════════════╝\n"
         )
@@ -115,7 +115,7 @@ class InvalidTokenError(LicenseError):
             "║  O token fornecido não é válido.                            ║\n"
             "║                                                              ║\n"
             "║  Verifique se o token está correto ou entre em contato:     ║\n"
-            "║  📧 contato@bemonkai.com                                    ║\n"
+            "║  📧 contato@monkai.com.br                                    ║\n"
             "║                                                              ║\n"
             "╚══════════════════════════════════════════════════════════════╝\n"
         )

atendentepro/network.py

@@ -20,6 +20,8 @@ from atendentepro.agents import (
     create_confirmation_agent,
     create_usage_agent,
     create_onboarding_agent,
+    create_escalation_agent,
+    create_feedback_agent,
     TriageAgent,
     FlowAgent,
     InterviewAgent,
@@ -28,6 +30,8 @@ from atendentepro.agents import (
     ConfirmationAgent,
     UsageAgent,
     OnboardingAgent,
+    EscalationAgent,
+    FeedbackAgent,
 )
 from atendentepro.guardrails import get_guardrails_for_agent, set_guardrails_client
 from atendentepro.license import require_activation
@@ -60,6 +64,8 @@ class AgentNetwork:
     confirmation: Optional[ConfirmationAgent] = None
     usage: Optional[UsageAgent] = None
     onboarding: Optional[OnboardingAgent] = None
+    escalation: Optional[EscalationAgent] = None
+    feedback: Optional[FeedbackAgent] = None
     
     templates_root: Optional[Path] = None
     current_client: str = "standard"
@@ -68,35 +74,67 @@ class AgentNetwork:
         """Get list of all configured agents."""
         agents = []
         for attr in ["triage", "flow", "interview", "answer", "knowledge", 
-                     "confirmation", "usage", "onboarding"]:
+                     "confirmation", "usage", "onboarding", "escalation", "feedback"]:
             agent = getattr(self, attr, None)
             if agent:
                 agents.append(agent)
         return agents
+    
+    def add_escalation_to_all(self) -> None:
+        """Add escalation agent as handoff to all other agents."""
+        if not self.escalation:
+            return
+        
+        for agent in self.get_all_agents():
+            if agent != self.escalation and self.escalation not in agent.handoffs:
+                agent.handoffs.append(self.escalation)
+    
+    def add_feedback_to_all(self) -> None:
+        """Add feedback agent as handoff to all other agents."""
+        if not self.feedback:
+            return
+        
+        for agent in self.get_all_agents():
+            if agent != self.feedback and self.feedback not in agent.handoffs:
+                agent.handoffs.append(self.feedback)
 
 
 def create_standard_network(
     templates_root: Path,
     client: str = "standard",
     include_onboarding: bool = False,
+    include_escalation: bool = True,
+    include_feedback: bool = True,
+    escalation_channels: str = "",
+    feedback_protocol_prefix: str = "TKT",
+    feedback_brand_color: str = "#4A90D9",
+    feedback_brand_name: str = "Atendimento",
     custom_tools: Optional[Dict[str, List]] = None,
 ) -> AgentNetwork:
     """
     Create a standard agent network with proper handoff configuration.
     
     This creates the default network configuration with:
-    - Triage -> Flow, Confirmation, Knowledge, Usage
-    - Flow -> Interview, Triage
-    - Interview -> Answer
-    - Answer -> Triage, Interview
-    - Confirmation -> Triage
-    - Knowledge -> Triage
-    - Usage -> Triage
+    - Triage -> Flow, Confirmation, Knowledge, Usage, Escalation, Feedback
+    - Flow -> Interview, Triage, Escalation, Feedback
+    - Interview -> Answer, Escalation, Feedback
+    - Answer -> Triage, Escalation, Feedback
+    - Confirmation -> Triage, Escalation, Feedback
+    - Knowledge -> Triage, Escalation, Feedback
+    - Usage -> Triage, Escalation, Feedback
+    - Escalation -> Triage
+    - Feedback -> Triage, Escalation
     
     Args:
         templates_root: Root directory for template configurations.
         client: Client key to load configurations for.
         include_onboarding: Whether to include the onboarding agent.
+        include_escalation: Whether to include the escalation agent (default True).
+        include_feedback: Whether to include the feedback agent (default True).
+        escalation_channels: Description of available escalation channels.
+        feedback_protocol_prefix: Prefix for ticket protocols (e.g., "SAC", "TKT").
+        feedback_brand_color: Brand color for feedback emails.
+        feedback_brand_name: Brand name for feedback emails.
         custom_tools: Optional dict of custom tools by agent name.
         
     Returns:
@@ -217,14 +255,72 @@ def create_standard_network(
         guardrails=get_guardrails_for_agent("Usage Agent", templates_root),
     )
     
+    # Create escalation agent if requested
+    escalation = None
+    if include_escalation:
+        escalation = create_escalation_agent(
+            escalation_channels=escalation_channels,
+            tools=tools.get("escalation", []),
+            guardrails=get_guardrails_for_agent("Escalation Agent", templates_root),
+        )
+    
+    # Create feedback agent if requested
+    feedback = None
+    if include_feedback:
+        feedback = create_feedback_agent(
+            protocol_prefix=feedback_protocol_prefix,
+            email_brand_color=feedback_brand_color,
+            email_brand_name=feedback_brand_name,
+            tools=tools.get("feedback", []),
+            guardrails=get_guardrails_for_agent("Feedback Agent", templates_root),
+        )
+    
     # Configure handoffs
-    triage.handoffs = [flow, confirmation, knowledge, usage]
-    flow.handoffs = [interview, triage]
-    confirmation.handoffs = [triage]
-    knowledge.handoffs = [triage]
-    usage.handoffs = [triage]
-    interview.handoffs = [answer]
-    answer.handoffs = [triage, interview]
+    triage_handoffs = [flow, confirmation, knowledge, usage]
+    flow_handoffs = [interview, triage]
+    confirmation_handoffs = [triage]
+    knowledge_handoffs = [triage]
+    usage_handoffs = [triage]
+    interview_handoffs = [answer]
+    answer_handoffs = [triage]  # Answer só volta para Triage (não faz sentido voltar para Interview)
+    escalation_handoffs = [triage]
+    feedback_handoffs = [triage]
+    
+    # Add escalation to all agents if enabled
+    if escalation:
+        triage_handoffs.append(escalation)
+        flow_handoffs.append(escalation)
+        confirmation_handoffs.append(escalation)
+        knowledge_handoffs.append(escalation)
+        usage_handoffs.append(escalation)
+        interview_handoffs.append(escalation)
+        answer_handoffs.append(escalation)
+        if feedback:
+            feedback_handoffs.append(escalation)
+    
+    # Add feedback to all agents if enabled
+    if feedback:
+        triage_handoffs.append(feedback)
+        flow_handoffs.append(feedback)
+        confirmation_handoffs.append(feedback)
+        knowledge_handoffs.append(feedback)
+        usage_handoffs.append(feedback)
+        interview_handoffs.append(feedback)
+        answer_handoffs.append(feedback)
+        if escalation:
+            escalation_handoffs.append(feedback)
+    
+    triage.handoffs = triage_handoffs
+    flow.handoffs = flow_handoffs
+    confirmation.handoffs = confirmation_handoffs
+    knowledge.handoffs = knowledge_handoffs
+    usage.handoffs = usage_handoffs
+    interview.handoffs = interview_handoffs
+    answer.handoffs = answer_handoffs
+    if escalation:
+        escalation.handoffs = escalation_handoffs
+    if feedback:
+        feedback.handoffs = feedback_handoffs
     
     network = AgentNetwork(
         triage=triage,
@@ -234,6 +330,8 @@ def create_standard_network(
         knowledge=knowledge,
         confirmation=confirmation,
         usage=usage,
+        escalation=escalation,
+        feedback=feedback,
         templates_root=templates_root,
         current_client=client,
     )
@@ -309,6 +407,8 @@ def create_custom_network(
         "confirmation": network.confirmation,
         "usage": network.usage,
         "onboarding": network.onboarding,
+        "escalation": network.escalation,
+        "feedback": network.feedback,
     }
     
     # Apply custom handoff configuration

atendentepro/prompts/__init__.py

@@ -8,6 +8,8 @@ from .answer import get_answer_prompt, AnswerPromptBuilder
 from .knowledge import get_knowledge_prompt, KnowledgePromptBuilder
 from .confirmation import get_confirmation_prompt, ConfirmationPromptBuilder
 from .onboarding import get_onboarding_prompt, OnboardingPromptBuilder
+from .escalation import get_escalation_prompt, EscalationPromptBuilder, ESCALATION_INTRO
+from .feedback import get_feedback_prompt, FeedbackPromptBuilder, FEEDBACK_INTRO
 
 __all__ = [
     # Triage
@@ -31,5 +33,13 @@ __all__ = [
     # Onboarding
     "get_onboarding_prompt",
     "OnboardingPromptBuilder",
+    # Escalation
+    "get_escalation_prompt",
+    "EscalationPromptBuilder",
+    "ESCALATION_INTRO",
+    # Feedback
+    "get_feedback_prompt",
+    "FeedbackPromptBuilder",
+    "FEEDBACK_INTRO",
 ]
 

atendentepro/prompts/answer.py

@@ -22,7 +22,6 @@ ANSWER_INTRO = """
 Você é um agente de resposta especializado.
 Você deverá responder à pergunta do usuário usando o template de resposta configurado.
 Use as informações coletadas durante a entrevista para fornecer uma resposta precisa e útil.
-Se precisar de mais informações, transfira para o interview_agent com orientações objetivas.
 Sempre que concluir uma resposta válida ao usuário, assim que receber qualquer outra pergunta, transfira a conversa para o triage_agent.
 Nas mensagens ao usuário, utilize linguagem natural e evite revelar processos internos, etapas de análise ou nomes de agentes.
 """
@@ -76,7 +75,7 @@ ANSWER_OUTPUT = """
     1. Envie a mensagem final ao usuário.
     2. Em seguida, com qualquer pergunta, transfira a conversa para o triage_agent.
 - (Raciocínio interno) Se a resposta não estiver completa:
-    1. Explique internamente quais dados faltam e transfira para o interview_agent para coletar as informações necessárias.
+    1. Solicite as informações faltantes diretamente ao usuário de forma clara e objetiva.
 - (Mensagem ao usuário) Resuma apenas o necessário, sem mencionar transferências, ferramentas ou processos internos.
 """
 
@@ -95,7 +94,7 @@ def get_answer_prompt(answer_template: str = "") -> str:
 [ROUTE]
 - (Raciocínio interno) Responder à pergunta do usuário usando o template de resposta como guia: 
   {answer_template}
-- (Raciocínio interno) Identifique se todas as informações obrigatórias do template estão preenchidas. Se faltar algo, prepare um pedido específico para o interview_agent recuperar a informação ausente.
+- (Raciocínio interno) Identifique se todas as informações obrigatórias do template estão preenchidas. Se faltar algo, solicite diretamente ao usuário.
 """
 
     return "\n".join([

atendentepro/prompts/escalation.py

@@ -0,0 +1,190 @@
+# -*- coding: utf-8 -*-
+"""Escalation Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class EscalationPromptBuilder:
+    """Builder for Escalation Agent prompts."""
+    
+    escalation_triggers: str = ""
+    escalation_channels: str = ""
+    
+    def build(self) -> str:
+        """Build the complete escalation agent prompt."""
+        return get_escalation_prompt(
+            escalation_triggers=self.escalation_triggers,
+            escalation_channels=self.escalation_channels,
+        )
+
+
+ESCALATION_INTRO = """
+Você é o Agente de Escalação, responsável por transferir conversas para atendimento humano.
+Sua função é garantir que o usuário receba o suporte adequado quando o sistema automatizado não consegue resolver.
+"""
+
+ESCALATION_MODULES = """
+Deve seguir as seguintes etapas de forma sequencial (todas são raciocínio interno; não exponha nada ao usuário):
+[READ] - [IDENTIFY] - [COLLECT] - [VERIFY] - [REGISTER] - [INFORM] - [OUTPUT]
+"""
+
+ESCALATION_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário e identifique o motivo da escalação.
+- (Raciocínio interno) Verifique se é uma solicitação explícita ou se foi encaminhado por outro agente.
+"""
+
+ESCALATION_IDENTIFY = """
+[IDENTIFY]
+- (Raciocínio interno) Identifique o tipo de escalação necessária:
+  - Solicitação explícita do usuário ("quero falar com um humano")
+  - Tópico não coberto pelo sistema
+  - Frustração ou insatisfação do usuário
+  - Problema complexo que requer análise humana
+  - Questões jurídicas, financeiras ou críticas
+"""
+
+ESCALATION_COLLECT = """
+[COLLECT]
+- (Raciocínio interno) Colete as informações necessárias para a escalação:
+  - Nome do usuário (se ainda não coletado)
+  - Telefone ou email para contato
+  - Motivo resumido da escalação
+  - Nível de urgência (normal ou urgente)
+"""
+
+ESCALATION_VERIFY = """
+[VERIFY]
+- (Raciocínio interno) Verifique o horário de atendimento humano.
+- (Raciocínio interno) Se estiver fora do horário, informe ao usuário e ofereça alternativas.
+- (Raciocínio interno) Se estiver dentro do horário, prossiga com o registro.
+"""
+
+ESCALATION_REGISTER = """
+[REGISTER]
+- (Raciocínio interno) Utilize a ferramenta registrar_escalacao para criar o registro.
+- (Raciocínio interno) Anote o número do protocolo gerado para informar ao usuário.
+"""
+
+ESCALATION_INFORM = """
+[INFORM]
+- (Raciocínio interno) Prepare a mensagem final com:
+  - Confirmação de que a escalação foi registrada
+  - Número do protocolo
+  - Canais de atendimento disponíveis
+  - Tempo estimado de espera (se aplicável)
+"""
+
+ESCALATION_OUTPUT = """
+[OUTPUT]
+- (Mensagem ao usuário) Informe que a solicitação de atendimento humano foi registrada.
+- (Mensagem ao usuário) Forneça o protocolo e os canais de contato de forma clara.
+- (Mensagem ao usuário) Seja empático e tranquilize o usuário sobre o atendimento.
+"""
+
+DEFAULT_ESCALATION_TRIGGERS = """
+## Gatilhos de Escalação
+
+### Solicitações Explícitas
+- "quero falar com um humano"
+- "atendente humano"
+- "falar com uma pessoa"
+- "transferir para atendente"
+- "pessoa real"
+
+### Frustração do Usuário
+- "você não está me ajudando"
+- "isso não resolve"
+- "já tentei de tudo"
+- "não funciona"
+- "estou frustrado"
+
+### Tópicos Não Cobertos
+- Questões jurídicas
+- Cancelamento de contrato
+- Reclamações formais graves
+- Processos administrativos
+"""
+
+
+def get_escalation_prompt(
+    escalation_triggers: str = "",
+    escalation_channels: str = "",
+) -> str:
+    """
+    Build the escalation agent prompt.
+    
+    Args:
+        escalation_triggers: Custom triggers for escalation.
+        escalation_channels: Available channels (phone, email, chat).
+        
+    Returns:
+        Complete escalation agent prompt.
+    """
+    intro = f"""
+{ESCALATION_INTRO}
+
+## Seu Papel
+
+Você ajuda os usuários que precisam de atendimento humano:
+1. **Identificar** o motivo da escalação
+2. **Coletar** informações de contato
+3. **Verificar** disponibilidade de atendimento
+4. **Registrar** a solicitação
+5. **Informar** o protocolo e canais disponíveis
+
+## Quando Escalar
+
+- O usuário solicita explicitamente falar com um humano
+- O tópico não é coberto pelo sistema automatizado
+- O usuário demonstra frustração ou insatisfação
+- O problema é complexo e requer análise humana
+- Questões jurídicas, financeiras ou críticas
+"""
+
+    triggers = escalation_triggers or DEFAULT_ESCALATION_TRIGGERS
+    
+    channels_section = ""
+    if escalation_channels:
+        channels_section = f"""
+## Canais Disponíveis
+
+{escalation_channels}
+"""
+    
+    guidelines = """
+## Diretrizes
+
+- Seja empático e demonstre que entende a necessidade do usuário
+- Nunca force o usuário a usar o sistema automatizado se ele quer um humano
+- Colete apenas as informações essenciais para o contato
+- Informe claramente o tempo estimado de resposta
+- Se fora do horário, ofereça alternativas (callback, email, etc.)
+
+## Tom de Voz
+
+- Seja compreensivo e profissional
+- Valide os sentimentos do usuário
+- Transmita confiança de que o problema será resolvido
+- Evite frases como "infelizmente" ou "não é possível"
+"""
+
+    return "\n".join([
+        intro,
+        triggers,
+        channels_section,
+        guidelines,
+        ESCALATION_MODULES,
+        ESCALATION_READ,
+        ESCALATION_IDENTIFY,
+        ESCALATION_COLLECT,
+        ESCALATION_VERIFY,
+        ESCALATION_REGISTER,
+        ESCALATION_INFORM,
+        ESCALATION_OUTPUT,
+    ])
+