atendentepro 0.3.0__py3-none-any.whl

atendentepro/network.py

@@ -0,0 +1,325 @@
+# -*- coding: utf-8 -*-
+"""
+Agent Network for AtendentePro.
+
+Provides functions to create and configure the agent network with proper handoffs.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Literal, Optional
+
+from atendentepro.agents import (
+    create_triage_agent,
+    create_flow_agent,
+    create_interview_agent,
+    create_answer_agent,
+    create_knowledge_agent,
+    create_confirmation_agent,
+    create_usage_agent,
+    create_onboarding_agent,
+    TriageAgent,
+    FlowAgent,
+    InterviewAgent,
+    AnswerAgent,
+    KnowledgeAgent,
+    ConfirmationAgent,
+    UsageAgent,
+    OnboardingAgent,
+)
+from atendentepro.guardrails import get_guardrails_for_agent, set_guardrails_client
+from atendentepro.license import require_activation
+from atendentepro.templates import (
+    TemplateManager,
+    configure_template_manager,
+    load_flow_config,
+    load_interview_config,
+    load_triage_config,
+    load_knowledge_config,
+    load_confirmation_config,
+    load_onboarding_config,
+)
+
+
+@dataclass
+class AgentNetwork:
+    """
+    Container for all agents in the network.
+    
+    Provides access to individual agents and methods to configure
+    the network for different clients.
+    """
+    
+    triage: Optional[TriageAgent] = None
+    flow: Optional[FlowAgent] = None
+    interview: Optional[InterviewAgent] = None
+    answer: Optional[AnswerAgent] = None
+    knowledge: Optional[KnowledgeAgent] = None
+    confirmation: Optional[ConfirmationAgent] = None
+    usage: Optional[UsageAgent] = None
+    onboarding: Optional[OnboardingAgent] = None
+    
+    templates_root: Optional[Path] = None
+    current_client: str = "standard"
+    
+    def get_all_agents(self) -> List:
+        """Get list of all configured agents."""
+        agents = []
+        for attr in ["triage", "flow", "interview", "answer", "knowledge", 
+                     "confirmation", "usage", "onboarding"]:
+            agent = getattr(self, attr, None)
+            if agent:
+                agents.append(agent)
+        return agents
+
+
+def create_standard_network(
+    templates_root: Path,
+    client: str = "standard",
+    include_onboarding: bool = False,
+    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
+    
+    Args:
+        templates_root: Root directory for template configurations.
+        client: Client key to load configurations for.
+        include_onboarding: Whether to include the onboarding agent.
+        custom_tools: Optional dict of custom tools by agent name.
+        
+    Returns:
+        Configured AgentNetwork instance.
+        
+    Raises:
+        LicenseNotActivatedError: If the library is not activated.
+    """
+    # Verificar licença
+    require_activation()
+    
+    # Configure template manager
+    manager = configure_template_manager(templates_root, default_client=client)
+    
+    # Load configurations
+    try:
+        flow_config = load_flow_config(client)
+        flow_template = flow_config.get_flow_template()
+        flow_keywords = flow_config.get_flow_keywords()
+    except FileNotFoundError:
+        flow_template = ""
+        flow_keywords = ""
+    
+    try:
+        interview_config = load_interview_config(client)
+        interview_questions = interview_config.interview_questions
+    except FileNotFoundError:
+        interview_questions = ""
+    
+    try:
+        triage_config = load_triage_config(client)
+        triage_keywords = triage_config.get_keywords_text()
+    except FileNotFoundError:
+        triage_keywords = ""
+    
+    try:
+        knowledge_config = load_knowledge_config(client)
+        knowledge_about = knowledge_config.about
+        knowledge_template = knowledge_config.template
+        knowledge_format = knowledge_config.format
+        embeddings_path = (
+            Path(knowledge_config.embeddings_path) 
+            if knowledge_config.embeddings_path 
+            else None
+        )
+        data_sources_description = knowledge_config.get_data_source_description()
+        has_embeddings = knowledge_config.has_documents()
+    except FileNotFoundError:
+        knowledge_about = ""
+        knowledge_template = ""
+        knowledge_format = ""
+        embeddings_path = None
+        data_sources_description = ""
+        has_embeddings = False
+    
+    try:
+        confirmation_config = load_confirmation_config(client)
+        confirmation_about = confirmation_config.about
+        confirmation_template = confirmation_config.template
+        confirmation_format = confirmation_config.format
+    except FileNotFoundError:
+        confirmation_about = ""
+        confirmation_template = ""
+        confirmation_format = ""
+    
+    # Load guardrails
+    try:
+        set_guardrails_client(client, templates_root=templates_root)
+    except FileNotFoundError:
+        pass
+    
+    # Get custom tools
+    tools = custom_tools or {}
+    
+    # Create agents without handoffs first
+    triage = create_triage_agent(
+        keywords_text=triage_keywords,
+        guardrails=get_guardrails_for_agent("Triage Agent", templates_root),
+    )
+    
+    flow = create_flow_agent(
+        flow_template=flow_template,
+        flow_keywords=flow_keywords,
+        guardrails=get_guardrails_for_agent("Flow Agent", templates_root),
+    )
+    
+    interview = create_interview_agent(
+        interview_template=flow_template,
+        interview_questions=interview_questions,
+        tools=tools.get("interview", []),
+        guardrails=get_guardrails_for_agent("Interview Agent", templates_root),
+    )
+    
+    answer = create_answer_agent(
+        answer_template="",
+        guardrails=get_guardrails_for_agent("Answer Agent", templates_root),
+    )
+    
+    knowledge = create_knowledge_agent(
+        knowledge_about=knowledge_about,
+        knowledge_template=knowledge_template,
+        knowledge_format=knowledge_format,
+        embeddings_path=embeddings_path,
+        data_sources_description=data_sources_description,
+        include_rag_tool=has_embeddings,
+        tools=tools.get("knowledge", []),
+        guardrails=get_guardrails_for_agent("Knowledge Agent", templates_root),
+    )
+    
+    confirmation = create_confirmation_agent(
+        confirmation_about=confirmation_about,
+        confirmation_template=confirmation_template,
+        confirmation_format=confirmation_format,
+        guardrails=get_guardrails_for_agent("Confirmation Agent", templates_root),
+    )
+    
+    usage = create_usage_agent(
+        guardrails=get_guardrails_for_agent("Usage 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]
+    
+    network = AgentNetwork(
+        triage=triage,
+        flow=flow,
+        interview=interview,
+        answer=answer,
+        knowledge=knowledge,
+        confirmation=confirmation,
+        usage=usage,
+        templates_root=templates_root,
+        current_client=client,
+    )
+    
+    # Add onboarding if requested
+    if include_onboarding:
+        try:
+            onboarding_config = load_onboarding_config(client)
+            from atendentepro.prompts.onboarding import OnboardingField as PromptField
+            
+            fields = [
+                PromptField(
+                    name=f.name,
+                    prompt=f.prompt,
+                    priority=f.priority,
+                )
+                for f in onboarding_config.required_fields
+            ]
+        except FileNotFoundError:
+            fields = []
+        
+        onboarding = create_onboarding_agent(
+            required_fields=fields,
+            tools=tools.get("onboarding", []),
+            guardrails=get_guardrails_for_agent("Onboarding Agent", templates_root),
+        )
+        
+        network.onboarding = onboarding
+        onboarding.handoffs = [triage]
+    
+    return network
+
+
+def create_custom_network(
+    templates_root: Path,
+    client: str,
+    network_config: Dict[str, List[str]],
+    custom_tools: Optional[Dict[str, List]] = None,
+) -> AgentNetwork:
+    """
+    Create a custom agent network with specified handoff configuration.
+    
+    Args:
+        templates_root: Root directory for template configurations.
+        client: Client key to load configurations for.
+        network_config: Dict mapping agent names to list of handoff agent names.
+        custom_tools: Optional dict of custom tools by agent name.
+        
+    Returns:
+        Configured AgentNetwork instance.
+        
+    Raises:
+        LicenseNotActivatedError: If the library is not activated.
+    """
+    # Verificar licença (já é feito em create_standard_network, mas verificamos novamente)
+    require_activation()
+    
+    # First create the standard network
+    network = create_standard_network(
+        templates_root=templates_root,
+        client=client,
+        include_onboarding="onboarding" in network_config,
+        custom_tools=custom_tools,
+    )
+    
+    # Map agent names to instances
+    agent_map = {
+        "triage": network.triage,
+        "flow": network.flow,
+        "interview": network.interview,
+        "answer": network.answer,
+        "knowledge": network.knowledge,
+        "confirmation": network.confirmation,
+        "usage": network.usage,
+        "onboarding": network.onboarding,
+    }
+    
+    # Apply custom handoff configuration
+    for agent_name, handoff_names in network_config.items():
+        agent = agent_map.get(agent_name)
+        if agent:
+            handoffs = [
+                agent_map[h] for h in handoff_names 
+                if h in agent_map and agent_map[h] is not None
+            ]
+            agent.handoffs = handoffs
+    
+    return network
+

atendentepro/prompts/__init__.py

@@ -0,0 +1,35 @@
+# -*- coding: utf-8 -*-
+"""Prompts module for AtendentePro library."""
+
+from .triage import get_triage_prompt, TRIAGE_INTRO
+from .flow import get_flow_prompt, FlowPromptBuilder
+from .interview import get_interview_prompt, InterviewPromptBuilder
+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
+
+__all__ = [
+    # Triage
+    "get_triage_prompt",
+    "TRIAGE_INTRO",
+    # Flow
+    "get_flow_prompt",
+    "FlowPromptBuilder",
+    # Interview
+    "get_interview_prompt",
+    "InterviewPromptBuilder",
+    # Answer
+    "get_answer_prompt",
+    "AnswerPromptBuilder",
+    # Knowledge
+    "get_knowledge_prompt",
+    "KnowledgePromptBuilder",
+    # Confirmation
+    "get_confirmation_prompt",
+    "ConfirmationPromptBuilder",
+    # Onboarding
+    "get_onboarding_prompt",
+    "OnboardingPromptBuilder",
+]
+

atendentepro/prompts/answer.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+"""Answer Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class AnswerPromptBuilder:
+    """Builder for Answer Agent prompts."""
+    
+    answer_template: str = ""
+    
+    def build(self) -> str:
+        """Build the complete answer agent prompt."""
+        return get_answer_prompt(answer_template=self.answer_template)
+
+
+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.
+"""
+
+ANSWER_MODULES = """
+Deve seguir as seguintes etapas de forma sequencial (todas são raciocínio interno; não exponha nada ao usuário):
+[READ] - [SUMMARY] - [EXTRACT] - [ANALYZE] - [ROUTE] - [VERIFY] - [REVIEW] - [FORMAT] - [OUTPUT]
+"""
+
+ANSWER_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário e as informações coletadas.
+"""
+
+ANSWER_SUMMARY = """
+[SUMMARY]
+- (Raciocínio interno) Faça um resumo da situação e das informações disponíveis.
+"""
+
+ANSWER_EXTRACT = """
+[EXTRACT]
+- (Raciocínio interno) Extraia as informações relevantes da mensagem do usuário e do contexto da entrevista.
+"""
+
+ANSWER_ANALYZE = """
+[ANALYZE]
+- (Raciocínio interno) Analise as informações disponíveis e identifique o que é necessário para responder adequadamente.
+"""
+
+ANSWER_VERIFY = """
+[VERIFY]
+- (Raciocínio interno) Verifique se a informação é adequada ao template de resposta e se responde completamente à pergunta do usuário.
+- (Raciocínio interno) Determine se a resposta está pronta para ser entregue. Se houver lacunas, identifique exatamente o que falta para resolver no passo seguinte.
+"""
+
+ANSWER_REVIEW = """
+[REVIEW]
+- (Raciocínio interno) Revise a informação respondida para garantir clareza e precisão.
+"""
+
+ANSWER_FORMAT = """
+[FORMAT]
+- (Raciocínio interno) Formate a resposta para que seja enviada ao usuário de maneira clara e objetiva.
+- (Raciocínio interno) Certifique-se de que a resposta seja útil e compreensível.
+- (Mensagem ao usuário) Utilize um tom profissional e direto, evitando frases como "análise concluída" ou "aqui está a situação".
+"""
+
+ANSWER_OUTPUT = """
+[OUTPUT]
+- (Raciocínio interno) Se a resposta estiver completa e validada:
+    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.
+- (Mensagem ao usuário) Resuma apenas o necessário, sem mencionar transferências, ferramentas ou processos internos.
+"""
+
+
+def get_answer_prompt(answer_template: str = "") -> str:
+    """
+    Build the answer agent prompt.
+    
+    Args:
+        answer_template: Template for answer formatting.
+        
+    Returns:
+        Complete answer agent prompt.
+    """
+    route = f"""
+[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.
+"""
+
+    return "\n".join([
+        ANSWER_INTRO,
+        ANSWER_MODULES,
+        ANSWER_READ,
+        ANSWER_SUMMARY,
+        ANSWER_EXTRACT,
+        ANSWER_ANALYZE,
+        route,
+        ANSWER_VERIFY,
+        ANSWER_REVIEW,
+        ANSWER_FORMAT,
+        ANSWER_OUTPUT,
+    ])
+

atendentepro/prompts/confirmation.py

@@ -0,0 +1,124 @@
+# -*- coding: utf-8 -*-
+"""Confirmation Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class ConfirmationPromptBuilder:
+    """Builder for Confirmation Agent prompts."""
+    
+    confirmation_about: str = ""
+    confirmation_template: str = ""
+    confirmation_format: str = ""
+    
+    def build(self) -> str:
+        """Build the complete confirmation agent prompt."""
+        return get_confirmation_prompt(
+            confirmation_about=self.confirmation_about,
+            confirmation_template=self.confirmation_template,
+            confirmation_format=self.confirmation_format,
+        )
+
+
+CONFIRMATION_MODULES = """
+Deve seguir as seguintes etapas de forma sequencial (todas são raciocínio interno; não exponha nada ao usuário):
+[READ] - [SUMMARY] - [EXTRACT] - [CLARIFY] - [CONFIRMATION] - [REVIEW] - [FORMAT] - [ROLLBACK] - [OUTPUT]
+"""
+
+CONFIRMATION_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário e o contexto da solicitação.
+"""
+
+CONFIRMATION_SUMMARY = """
+[SUMMARY]
+- (Raciocínio interno) Faça um resumo da solicitação do usuário.
+"""
+
+CONFIRMATION_EXTRACT = """
+[EXTRACT]
+- (Raciocínio interno) Extraia as informações relevantes da mensagem do usuário.
+"""
+
+CONFIRMATION_CLARIFY = """
+[CLARIFY]
+- (Raciocínio interno) Se houver dados insuficientes para decidir, solicite apenas as informações que faltam para confirmar ou negar a hipótese apresentada.
+"""
+
+CONFIRMATION_REVIEW = """
+[REVIEW]
+- (Raciocínio interno) Revise a informação confirmada. Toda resposta precisa ser referenciada ao template de confirmação.
+"""
+
+CONFIRMATION_OUTPUT = """
+[OUTPUT]
+- (Raciocínio interno) Exponha a informação confirmada ao usuário de maneira clara e precisa.
+- (Mensagem ao usuário) Explique o resultado de forma direta e profissional, evitando frases como "análise concluída" ou "transferindo para".
+"""
+
+
+def get_confirmation_prompt(
+    confirmation_about: str = "",
+    confirmation_template: str = "",
+    confirmation_format: str = "",
+) -> str:
+    """
+    Build the confirmation agent prompt.
+    
+    Args:
+        confirmation_about: Scope description for confirmation.
+        confirmation_template: Template for confirmation logic.
+        confirmation_format: Response format template.
+        
+    Returns:
+        Complete confirmation agent prompt.
+    """
+    intro = f"""
+Você é um agente de confirmação especializado.
+Você só atende hipóteses ou dúvidas específicas já formuladas pelo usuário (ex.: "O código XX se aplica a Y?").
+Seu papel é analisar o cenário apresentado e confirmar ou negar a hipótese, explicando claramente o motivo.
+Quando a solicitação exigir pesquisa ou descoberta de nova informação, outro agente (ex.: Knowledge Agent) deve ser acionado via triage.
+Ao se comunicar com o usuário, use linguagem natural e nunca mencione agentes internos, transferências ou etapas de análise.
+
+Escopo de atuação:
+{confirmation_about}
+"""
+
+    confirmation = f"""
+[CONFIRMATION]
+- (Raciocínio interno) Avalie se a hipótese fornecida pelo usuário está correta ou incorreta usando o template:
+{confirmation_template}
+- (Raciocínio interno) Produza uma conclusão clara (ex.: "Sim, é aplicável porque..." ou "Não, não se aplica porque...") sempre acompanhada da explicação.
+"""
+
+    rollback = f"""
+[ROLLBACK]
+- (Raciocínio interno) Se o usuário está pedindo descoberta de informações novas ou temas fora de:
+{confirmation_about}
+- Solicite ao triage_agent que direcione para o agente apropriado (ex.: Knowledge Agent) e finalize este turno.
+"""
+
+    format_section = f"""
+[FORMAT]
+- (Raciocínio interno) Formate a resposta para que seja enviada ao usuário seguindo o padrão: 
+{confirmation_format}
+"""
+
+    return "\n".join([
+        intro,
+        CONFIRMATION_MODULES,
+        CONFIRMATION_READ,
+        CONFIRMATION_SUMMARY,
+        CONFIRMATION_EXTRACT,
+        CONFIRMATION_CLARIFY,
+        confirmation,
+        CONFIRMATION_REVIEW,
+        format_section,
+        rollback,
+        CONFIRMATION_OUTPUT,
+    ])
+