atendentepro 0.3.0__py3-none-any.whl

atendentepro/__init__.py

@@ -0,0 +1,215 @@
+# -*- coding: utf-8 -*-
+"""
+AtendentePro - 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.
+
+⚠️ ATIVAÇÃO NECESSÁRIA:
+
+    Esta biblioteca requer um token de licença para funcionar.
+    
+    Opção 1 - Ativar programaticamente:
+    
+        from atendentepro import activate
+        activate("seu-token-de-acesso")
+        
+    Opção 2 - Variável de ambiente:
+    
+        export ATENDENTEPRO_LICENSE_KEY="seu-token-de-acesso"
+
+Exemplo de uso básico:
+
+    from atendentepro import activate, create_standard_network, configure
+    from pathlib import Path
+    
+    # 1. Ativar a biblioteca
+    activate("seu-token-de-acesso")
+    
+    # 2. Configurar a biblioteca
+    configure(provider="openai", openai_api_key="sua-chave")
+    
+    # 3. Criar rede de agentes
+    network = create_standard_network(
+        templates_root=Path("./client_templates"),
+        client="standard"
+    )
+    
+    # 4. Usar o agente de triagem como ponto de entrada
+    triage_agent = network.triage
+
+Para obter um token de licença, entre em contato: contato@bemonkai.com
+Para mais informações, consulte a documentação.
+"""
+
+__version__ = "0.3.0"
+__author__ = "BeMonkAI"
+__email__ = "contato@bemonkai.com"
+__license__ = "Proprietary"
+
+# License (deve ser importado primeiro)
+from atendentepro.license import (
+    activate,
+    deactivate,
+    is_activated,
+    get_license_info,
+    require_activation,
+    has_feature,
+    generate_license_token,
+    LicenseInfo,
+    LicenseError,
+    LicenseNotActivatedError,
+    LicenseExpiredError,
+    InvalidTokenError,
+)
+
+# Configuration
+from atendentepro.config import (
+    AtendentProConfig,
+    get_config,
+    configure,
+    RECOMMENDED_PROMPT_PREFIX,
+    DEFAULT_MODEL,
+)
+
+# Models
+from atendentepro.models import (
+    ContextNote,
+    FlowTopic,
+    FlowOutput,
+    InterviewOutput,
+    KnowledgeToolResult,
+    GuardrailValidationOutput,
+)
+
+# Agents
+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,
+    go_to_rag,
+)
+
+# Network
+from atendentepro.network import (
+    AgentNetwork,
+    create_standard_network,
+    create_custom_network,
+)
+
+# Templates
+from atendentepro.templates import (
+    TemplateManager,
+    ClientTemplate,
+    configure_client,
+    get_template_folder,
+    load_flow_config,
+    load_interview_config,
+    load_triage_config,
+    load_knowledge_config,
+    load_confirmation_config,
+    load_onboarding_config,
+)
+
+# Guardrails
+from atendentepro.guardrails import (
+    GuardrailManager,
+    get_guardrails_for_agent,
+    get_out_of_scope_message,
+    set_guardrails_client,
+)
+
+# Utils
+from atendentepro.utils import (
+    get_async_client,
+    get_provider,
+    configure_tracing,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    "__author__",
+    # License
+    "activate",
+    "deactivate",
+    "is_activated",
+    "get_license_info",
+    "require_activation",
+    "has_feature",
+    "generate_license_token",
+    "LicenseInfo",
+    "LicenseError",
+    "LicenseNotActivatedError",
+    "LicenseExpiredError",
+    "InvalidTokenError",
+    # Configuration
+    "AtendentProConfig",
+    "get_config",
+    "configure",
+    "RECOMMENDED_PROMPT_PREFIX",
+    "DEFAULT_MODEL",
+    # Models
+    "ContextNote",
+    "FlowTopic",
+    "FlowOutput",
+    "InterviewOutput",
+    "KnowledgeToolResult",
+    "GuardrailValidationOutput",
+    # Agents
+    "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",
+    "go_to_rag",
+    # Network
+    "AgentNetwork",
+    "create_standard_network",
+    "create_custom_network",
+    # Templates
+    "TemplateManager",
+    "ClientTemplate",
+    "configure_client",
+    "get_template_folder",
+    "load_flow_config",
+    "load_interview_config",
+    "load_triage_config",
+    "load_knowledge_config",
+    "load_confirmation_config",
+    "load_onboarding_config",
+    # Guardrails
+    "GuardrailManager",
+    "get_guardrails_for_agent",
+    "get_out_of_scope_message",
+    "set_guardrails_client",
+    # Utils
+    "get_async_client",
+    "get_provider",
+    "configure_tracing",
+]
+

atendentepro/agents/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""
+Agents module for AtendentePro library.
+
+This module provides factory functions for creating agents with customizable
+configurations. Templates can be loaded from external directories.
+"""
+
+from .triage import create_triage_agent, TriageAgent
+from .flow import create_flow_agent, FlowAgent
+from .interview import create_interview_agent, InterviewAgent
+from .answer import create_answer_agent, AnswerAgent
+from .knowledge import create_knowledge_agent, KnowledgeAgent, go_to_rag
+from .confirmation import create_confirmation_agent, ConfirmationAgent
+from .usage import create_usage_agent, UsageAgent
+from .onboarding import create_onboarding_agent, OnboardingAgent
+
+__all__ = [
+    # Triage
+    "create_triage_agent",
+    "TriageAgent",
+    # Flow
+    "create_flow_agent",
+    "FlowAgent",
+    # Interview
+    "create_interview_agent",
+    "InterviewAgent",
+    # Answer
+    "create_answer_agent",
+    "AnswerAgent",
+    # Knowledge
+    "create_knowledge_agent",
+    "KnowledgeAgent",
+    "go_to_rag",
+    # Confirmation
+    "create_confirmation_agent",
+    "ConfirmationAgent",
+    # Usage
+    "create_usage_agent",
+    "UsageAgent",
+    # Onboarding
+    "create_onboarding_agent",
+    "OnboardingAgent",
+]
+

atendentepro/agents/answer.py

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+"""Answer Agent for AtendentePro."""
+
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+from agents import Agent
+
+from atendentepro.config import RECOMMENDED_PROMPT_PREFIX
+from atendentepro.models import ContextNote
+from atendentepro.prompts import get_answer_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Answer Agent
+AnswerAgent = Agent[ContextNote]
+
+
+def create_answer_agent(
+    answer_template: str = "",
+    handoffs: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Answer Agent",
+    custom_instructions: Optional[str] = None,
+) -> AnswerAgent:
+    """
+    Create an Answer Agent instance.
+    
+    The answer agent synthesizes final responses using collected data
+    and the configured answer template.
+    
+    Args:
+        answer_template: Template for answer formatting.
+        handoffs: List of agents to hand off to.
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Answer Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_answer_prompt(answer_template=answer_template)
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description=(
+            "Agente responsável por sintetizar a resposta técnica final usando os dados coletados. "
+            "Após concluir a orientação, deve acionar o handoff para o Triage Agent a fim de encerrar o caso. "
+            "Se identificar lacunas de informação, orienta o que falta e aciona o handoff para o Interview Agent."
+        ),
+        instructions=instructions,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/confirmation.py

@@ -0,0 +1,69 @@
+# -*- coding: utf-8 -*-
+"""Confirmation Agent for AtendentePro."""
+
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+from agents import Agent
+
+from atendentepro.config import RECOMMENDED_PROMPT_PREFIX
+from atendentepro.models import ContextNote
+from atendentepro.prompts import get_confirmation_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Confirmation Agent
+ConfirmationAgent = Agent[ContextNote]
+
+
+def create_confirmation_agent(
+    confirmation_about: str = "",
+    confirmation_template: str = "",
+    confirmation_format: str = "",
+    handoffs: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Confirmation Agent",
+    custom_instructions: Optional[str] = None,
+) -> ConfirmationAgent:
+    """
+    Create a Confirmation Agent instance.
+    
+    The confirmation agent validates hypotheses and provides yes/no answers
+    with explanations based on configured rules.
+    
+    Args:
+        confirmation_about: Scope description for confirmation.
+        confirmation_template: Template for confirmation logic.
+        confirmation_format: Response format template.
+        handoffs: List of agents to hand off to.
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Confirmation Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_confirmation_prompt(
+            confirmation_about=confirmation_about,
+            confirmation_template=confirmation_template,
+            confirmation_format=confirmation_format,
+        )
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description=(
+            "Agente especializado em confirmar ou negar hipóteses específicas do usuário, "
+            "explicando o motivo da decisão com base nas regras e políticas conhecidas do produto ou processo."
+        ),
+        instructions=instructions,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/flow.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+"""Flow Agent for AtendentePro."""
+
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+from agents import Agent
+
+from atendentepro.config import RECOMMENDED_PROMPT_PREFIX
+from atendentepro.models import ContextNote
+from atendentepro.prompts import get_flow_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Flow Agent
+FlowAgent = Agent[ContextNote]
+
+
+def create_flow_agent(
+    flow_template: str = "",
+    flow_keywords: str = "",
+    handoffs: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Flow Agent",
+    custom_instructions: Optional[str] = None,
+) -> FlowAgent:
+    """
+    Create a Flow Agent instance.
+    
+    The flow agent identifies topics and routes users to the interview agent.
+    
+    Args:
+        flow_template: Template with available topics.
+        flow_keywords: Keywords for topic identification.
+        handoffs: List of agents to hand off to.
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Flow Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_flow_prompt(flow_template=flow_template, flow_keywords=flow_keywords)
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description="""
+        Um agente de fluxo inteligente que:
+        1. Se o usuário já especificou um tópico específico, vai direto para o interview_agent
+        2. Se não especificou, apresenta a lista de tópicos para o usuário escolher
+        3. Só transfere para triage se a resposta não for clara o suficiente
+        """,
+        instructions=instructions,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/interview.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+"""Interview Agent for AtendentePro."""
+
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+from agents import Agent
+
+from atendentepro.config import RECOMMENDED_PROMPT_PREFIX
+from atendentepro.models import ContextNote
+from atendentepro.prompts import get_interview_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Interview Agent
+InterviewAgent = Agent[ContextNote]
+
+
+def create_interview_agent(
+    interview_template: str = "",
+    interview_questions: str = "",
+    handoffs: Optional[List] = None,
+    tools: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Interview Agent",
+    custom_instructions: Optional[str] = None,
+) -> InterviewAgent:
+    """
+    Create an Interview Agent instance.
+    
+    The interview agent collects information from users through structured
+    questions based on the identified topic.
+    
+    Args:
+        interview_template: Template with topic routing info.
+        interview_questions: Configured interview questions.
+        handoffs: List of agents to hand off to.
+        tools: List of tools available to the agent.
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Interview Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_interview_prompt(
+            interview_template=interview_template,
+            interview_questions=interview_questions,
+        )
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description="""
+        Um agente de entrevista que pode entrevistar o usuário para obter informações relevantes.
+        """,
+        instructions=instructions,
+        handoffs=handoffs or [],
+        tools=tools or [],
+        input_guardrails=guardrails or [],
+    )
+