atendentepro 0.3.0__py3-none-any.whl

atendentepro/agents/knowledge.py

@@ -0,0 +1,296 @@
+# -*- coding: utf-8 -*-
+"""Knowledge Agent for AtendentePro."""
+
+from __future__ import annotations
+
+import logging
+import pickle
+from pathlib import Path
+from typing import Any, Callable, List, Optional, TYPE_CHECKING
+
+from pydantic import BaseModel, Field
+
+from agents import Agent, function_tool
+
+from atendentepro.config import RECOMMENDED_PROMPT_PREFIX, get_config
+from atendentepro.models import ContextNote, KnowledgeToolResult
+from atendentepro.prompts import get_knowledge_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+logger = logging.getLogger(__name__)
+
+
+# Type alias for the Knowledge Agent
+KnowledgeAgent = Agent[ContextNote]
+
+
+# Global embedding path (can be configured per client)
+_EMBEDDINGS_PATH: Optional[Path] = None
+
+
+def set_embeddings_path(path: Path) -> None:
+    """Set the path for embeddings file."""
+    global _EMBEDDINGS_PATH
+    _EMBEDDINGS_PATH = path
+
+
+def get_embeddings_path() -> Optional[Path]:
+    """Get the current embeddings path."""
+    return _EMBEDDINGS_PATH
+
+
+def load_embeddings() -> List[dict]:
+    """Load embeddings from disk."""
+    embeddings_path = _EMBEDDINGS_PATH
+    if not embeddings_path or not embeddings_path.exists():
+        logger.warning("No embeddings path configured or file doesn't exist")
+        return []
+    
+    try:
+        with open(embeddings_path, "rb") as file:
+            loaded_data = pickle.load(file)
+            logger.info("Embeddings loaded successfully from %s", embeddings_path)
+            return loaded_data
+    except Exception as exc:
+        logger.error("Failed to load embeddings from %s: %s", embeddings_path, exc)
+        return []
+
+
+async def _find_relevant_chunks(query: str, top_k: int = 3) -> List[dict]:
+    """Find most relevant chunks for a given query."""
+    try:
+        from sklearn.metrics.pairwise import cosine_similarity
+        import numpy as np
+        
+        from atendentepro.utils import get_async_client
+        
+        client = get_async_client()
+        response = await client.embeddings.create(model="text-embedding-3-large", input=query)
+        query_embedding = response.data[0].embedding
+        
+        chunk_embeddings = load_embeddings()
+        if not chunk_embeddings:
+            logger.error("No embeddings loaded")
+            return []
+        
+        similarities: List[tuple] = []
+        for chunk_data in chunk_embeddings:
+            chunk_embedding = chunk_data.get("embedding")
+            if not chunk_embedding:
+                continue
+            
+            query_emb = np.array(query_embedding).reshape(1, -1)
+            chunk_emb = np.array(chunk_embedding).reshape(1, -1)
+            similarity = cosine_similarity(query_emb, chunk_emb)[0][0]
+            similarities.append((similarity, chunk_data))
+        
+        similarities.sort(key=lambda x: x[0], reverse=True)
+        
+        top_results: List[dict] = []
+        for score, chunk_data in similarities[:top_k]:
+            enriched_chunk = dict(chunk_data)
+            enriched_chunk["similarity"] = score
+            top_results.append(enriched_chunk)
+        
+        return top_results
+    
+    except Exception as exc:
+        logger.error("Error finding relevant chunks: %s", exc)
+        return []
+
+
+@function_tool
+async def go_to_rag(question: str) -> KnowledgeToolResult:
+    """
+    Utilize RAG to answer the user's question.
+    
+    Args:
+        question: The question to answer using RAG.
+        
+    Returns:
+        KnowledgeToolResult with answer, context, sources, and confidence.
+    """
+    from atendentepro.utils import get_async_client
+    from atendentepro.config import get_config
+    
+    logger.info("Processing question: %s", question)
+    
+    relevant_chunks = await _find_relevant_chunks(question, top_k=3)
+    
+    if not relevant_chunks:
+        return KnowledgeToolResult(
+            answer="Não consegui encontrar informações relevantes nos documentos para responder sua pergunta.",
+            context="",
+            sources=[],
+            confidence=0.0,
+        )
+    
+    context_sections: List[str] = []
+    sources: List[str] = []
+    seen_sources: set = set()
+    similarities: List[float] = []
+    
+    for chunk in relevant_chunks:
+        chunk_info = chunk.get("chunk", {}) or {}
+        source = chunk_info.get("source", "Desconhecido")
+        content = chunk_info.get("content", "")
+        similarity = float(chunk.get("similarity", 0.0))
+        
+        if source not in seen_sources:
+            sources.append(source)
+            seen_sources.add(source)
+        
+        similarities.append(similarity)
+        context_sections.append(f"Documento: {source}\nConteúdo: {content}")
+    
+    context = "\n\n".join(context_sections)
+    logger.info("Context: %s", context)
+    
+    confidence = (
+        sum(max(score, 0.0) for score in similarities) / len(similarities) if similarities else 0.0
+    )
+    
+    answer = (
+        "Encontrei trechos relevantes, mas não consegui sintetizar uma resposta a partir deles. "
+        "Use o contexto abaixo para responder manualmente."
+    )
+    
+    try:
+        config = get_config()
+        client = get_async_client()
+        completion = await client.responses.create(
+            model=config.default_model,
+            input=[
+                {
+                    "role": "system",
+                    "content": (
+                        "Você é um especialista no domínio deste produto. Use apenas o contexto fornecido para "
+                        "responder de forma objetiva. Se não houver informação suficiente, informe isso."
+                    ),
+                },
+                {
+                    "role": "user",
+                    "content": (
+                        f"Pergunta: {question}\n\n"
+                        f"Contexto:\n{context}\n\n"
+                        "Responda em português, destacando os passos principais e cite os documentos utilizados."
+                    ),
+                },
+            ],
+        )
+        
+        if hasattr(completion, "output_text"):
+            answer_candidate = completion.output_text.strip()
+            if answer_candidate:
+                answer = answer_candidate
+        else:
+            parts: List[str] = []
+            for output in getattr(completion, "output", []):
+                for content in getattr(output, "content", []):
+                    text_part = getattr(content, "text", None)
+                    if text_part:
+                        parts.append(text_part)
+            if parts:
+                answer = "\n".join(parts).strip()
+    except Exception as exc:
+        logger.error("Failed to synthesize answer: %s", exc)
+    
+    return KnowledgeToolResult(
+        answer=answer,
+        context=context,
+        sources=sources,
+        confidence=confidence,
+    )
+
+
+def create_knowledge_agent(
+    knowledge_about: str = "",
+    knowledge_template: str = "",
+    knowledge_format: str = "",
+    embeddings_path: Optional[Path] = None,
+    data_sources_description: str = "",
+    include_rag_tool: bool = True,
+    handoffs: Optional[List] = None,
+    tools: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Knowledge Agent",
+    custom_instructions: Optional[str] = None,
+) -> KnowledgeAgent:
+    """
+    Create a Knowledge Agent instance.
+    
+    The knowledge agent handles document research (RAG) and structured data queries.
+    It can be configured to use:
+    - Document-based RAG with embeddings
+    - Structured data sources (CSV, databases, APIs) via custom tools
+    - Both simultaneously
+    
+    Args:
+        knowledge_about: Description of available knowledge documents.
+        knowledge_template: Document metadata template.
+        knowledge_format: Response format template.
+        embeddings_path: Path to the embeddings file for RAG.
+        data_sources_description: Description of available structured data sources.
+        include_rag_tool: Whether to include the go_to_rag tool (default True if embeddings_path).
+        handoffs: List of agents to hand off to.
+        tools: Additional tools for structured data queries.
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Knowledge Agent instance.
+    """
+    # Set embeddings path if provided
+    if embeddings_path:
+        set_embeddings_path(embeddings_path)
+    
+    # Build about section including data sources
+    full_about = knowledge_about
+    if data_sources_description:
+        full_about = f"{knowledge_about}\n\nFontes de dados estruturados disponíveis:\n{data_sources_description}"
+    
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_knowledge_prompt(
+            knowledge_about=full_about,
+            knowledge_template=knowledge_template,
+            knowledge_format=knowledge_format,
+        )
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    # Build tools list
+    agent_tools: List = []
+    
+    # Include RAG tool if embeddings are configured
+    if include_rag_tool and embeddings_path:
+        agent_tools.append(go_to_rag)
+    
+    # Add custom tools for structured data
+    if tools:
+        agent_tools.extend(tools)
+    
+    # Build handoff description based on capabilities
+    capabilities = []
+    if embeddings_path:
+        capabilities.append("pesquisar documentos")
+    if tools:
+        capabilities.append("consultar dados estruturados")
+    
+    handoff_desc = (
+        f"Agente voltado a {' e '.join(capabilities) if capabilities else 'recuperar informações'} "
+        "quando é preciso descobrir ou contextualizar algo novo."
+    )
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description=handoff_desc,
+        instructions=instructions,
+        tools=agent_tools,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/onboarding.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""Onboarding 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_onboarding_prompt
+from atendentepro.prompts.onboarding import OnboardingField
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Onboarding Agent
+OnboardingAgent = Agent[ContextNote]
+
+
+def create_onboarding_agent(
+    required_fields: Optional[List[OnboardingField]] = None,
+    handoffs: Optional[List] = None,
+    tools: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Onboarding Agent",
+    custom_instructions: Optional[str] = None,
+) -> OnboardingAgent:
+    """
+    Create an Onboarding Agent instance.
+    
+    The onboarding agent welcomes new users and guides them through
+    the registration process.
+    
+    Args:
+        required_fields: List of required fields for onboarding.
+        handoffs: List of agents to hand off to.
+        tools: List of tools available to the agent (e.g., find_user_on_csv).
+        guardrails: List of input guardrails.
+        name: Agent name.
+        custom_instructions: Optional custom instructions to override default.
+        
+    Returns:
+        Configured Onboarding Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        prompt = get_onboarding_prompt(required_fields=required_fields)
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {prompt}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description=(
+            "Agente de onboarding responsável por acolher usuários não encontrados no cadastro "
+            "e orientar o registro inicial."
+        ),
+        instructions=instructions,
+        handoffs=handoffs or [],
+        tools=tools or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/triage.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""Triage 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_triage_prompt
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Triage Agent
+TriageAgent = Agent[ContextNote]
+
+
+def create_triage_agent(
+    keywords_text: str = "",
+    handoffs: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Triage Agent",
+    custom_instructions: Optional[str] = None,
+) -> TriageAgent:
+    """
+    Create a Triage Agent instance.
+    
+    The triage agent is responsible for understanding user needs and
+    directing them to the appropriate specialized agent.
+    
+    Args:
+        keywords_text: Formatted keywords for agent routing.
+        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 Triage Agent instance.
+    """
+    if custom_instructions:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {custom_instructions}"
+    else:
+        instructions = f"{RECOMMENDED_PROMPT_PREFIX} {get_triage_prompt(keywords_text)}"
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description="A triage agent that can delegate a customer's request to the appropriate agent.",
+        instructions=instructions,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/agents/usage.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+"""Usage 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
+
+if TYPE_CHECKING:
+    from atendentepro.guardrails import GuardrailCallable
+
+
+# Type alias for the Usage Agent
+UsageAgent = Agent[ContextNote]
+
+
+DEFAULT_USAGE_INSTRUCTIONS = """
+You are a helpful usage agent. You will answer questions about the usage of the system.
+Respond in natural language and never mention internal agents, transfers, or reasoning steps.
+"""
+
+
+def create_usage_agent(
+    handoffs: Optional[List] = None,
+    guardrails: Optional[List["GuardrailCallable"]] = None,
+    name: str = "Usage Agent",
+    custom_instructions: Optional[str] = None,
+) -> UsageAgent:
+    """
+    Create a Usage Agent instance.
+    
+    The usage agent answers questions about system usage.
+    
+    Args:
+        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 Usage Agent instance.
+    """
+    instructions = custom_instructions or DEFAULT_USAGE_INSTRUCTIONS
+    
+    return Agent[ContextNote](
+        name=name,
+        handoff_description="A usage agent that can answer questions about the usage of the system.",
+        instructions=instructions,
+        handoffs=handoffs or [],
+        input_guardrails=guardrails or [],
+    )
+

atendentepro/config/__init__.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+"""Configuration module for AtendentePro library."""
+
+from .settings import (
+    AtendentProConfig,
+    get_config,
+    configure,
+    RECOMMENDED_PROMPT_PREFIX,
+    DEFAULT_MODEL,
+)
+
+__all__ = [
+    "AtendentProConfig",
+    "get_config",
+    "configure",
+    "RECOMMENDED_PROMPT_PREFIX",
+    "DEFAULT_MODEL",
+]
+

atendentepro/config/settings.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""
+AtendentePro Configuration Settings.
+
+This module provides centralized configuration management for the AtendentePro library.
+It supports both OpenAI and Azure OpenAI providers.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal, Optional
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+@dataclass
+class AtendentProConfig:
+    """Main configuration class for AtendentePro."""
+    
+    # Provider configuration
+    provider: Literal["openai", "azure"] = "openai"
+    
+    # OpenAI settings
+    openai_api_key: Optional[str] = None
+    
+    # Azure OpenAI settings
+    azure_api_key: Optional[str] = None
+    azure_api_endpoint: Optional[str] = None
+    azure_api_version: Optional[str] = None
+    azure_deployment_name: Optional[str] = None
+    
+    # Model settings
+    default_model: str = "gpt-4.1"
+    
+    # OCR settings (optional)
+    ocr_enabled: bool = True
+    azure_ai_vision_endpoint: Optional[str] = None
+    azure_ai_vision_key: Optional[str] = None
+    
+    # Tracing settings
+    application_insights_connection_string: Optional[str] = None
+    
+    # Templates settings
+    templates_root: Optional[Path] = None
+    default_client: str = "standard"
+    
+    # Context output directory
+    context_output_dir: str = "context"
+    
+    @classmethod
+    def from_env(cls) -> "AtendentProConfig":
+        """Create configuration from environment variables."""
+        # Determine provider
+        provider_env = (os.getenv("OPENAI_PROVIDER") or "").strip().lower()
+        azure_api_key = os.getenv("AZURE_API_KEY")
+        azure_api_endpoint = os.getenv("AZURE_API_ENDPOINT") or os.getenv("AZURE_OPENAI_ENDPOINT")
+        
+        if provider_env:
+            provider: Literal["openai", "azure"] = "azure" if provider_env == "azure" else "openai"
+        else:
+            provider = "azure" if azure_api_key and azure_api_endpoint else "openai"
+        
+        return cls(
+            provider=provider,
+            openai_api_key=os.getenv("OPENAI_API_KEY"),
+            azure_api_key=azure_api_key,
+            azure_api_endpoint=azure_api_endpoint,
+            azure_api_version=os.getenv("AZURE_API_VERSION") or os.getenv("AZURE_OPENAI_API_VERSION"),
+            azure_deployment_name=os.getenv("AZURE_DEPLOYMENT_NAME"),
+            default_model=os.getenv("DEFAULT_MODEL", "gpt-4.1"),
+            ocr_enabled=os.getenv("OCR_ENABLED", "true").lower() == "true",
+            azure_ai_vision_endpoint=os.getenv("AZURE_AI_VISION_ENDPOINT"),
+            azure_ai_vision_key=os.getenv("AZURE_AI_VISION_KEY"),
+            application_insights_connection_string=os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING"),
+            context_output_dir=os.getenv("CONTEXT_OUTPUT_DIR", "context"),
+        )
+
+
+# Global configuration instance
+_config: Optional[AtendentProConfig] = None
+
+
+def get_config() -> AtendentProConfig:
+    """Get the current configuration, initializing from environment if needed."""
+    global _config
+    if _config is None:
+        _config = AtendentProConfig.from_env()
+    return _config
+
+
+def configure(config: Optional[AtendentProConfig] = None, **kwargs) -> AtendentProConfig:
+    """
+    Configure the AtendentePro library.
+    
+    Args:
+        config: Optional pre-built configuration object
+        **kwargs: Configuration parameters to override
+        
+    Returns:
+        The active configuration object
+    """
+    global _config
+    
+    if config is not None:
+        _config = config
+    elif kwargs:
+        current = get_config()
+        for key, value in kwargs.items():
+            if hasattr(current, key):
+                setattr(current, key, value)
+    
+    return get_config()
+
+
+# Default model
+DEFAULT_MODEL = "gpt-4.1"
+
+# Recommended prompt prefix for all agents
+RECOMMENDED_PROMPT_PREFIX = """
+[CONTEXT SYSTEM]
+- Você faz parte de um sistema multiagente chamado Agents SDK, criado para facilitar a coordenação e execução de agentes.
+- O Agents SDK utiliza duas principais abstrações: **Agentes** e **Handoffs** (transferências).
+- Um agente abrange instruções e ferramentas e pode transferir uma conversa para outro agente quando apropriado.
+- Transferências entre agentes são realizadas chamando uma função de transferência, geralmente nomeada como `transfer_to_<nome_do_agente>`.
+- As transferências entre agentes ocorrem de forma transparente em segundo plano; não mencione nem chame atenção para essas transferências na sua conversa com o usuário.
+- Produza respostas naturais, evitando termos como "transferindo para...", "análise concluída", "aqui está a situação" ou qualquer indicação de lógica interna.
+"""
+

atendentepro/guardrails/__init__.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""Guardrails module for AtendentePro library."""
+
+from .manager import (
+    GuardrailManager,
+    get_guardrails_for_agent,
+    get_out_of_scope_message,
+    load_guardrail_config,
+    set_guardrails_client,
+    clear_guardrail_cache,
+)
+
+__all__ = [
+    "GuardrailManager",
+    "get_guardrails_for_agent",
+    "get_out_of_scope_message",
+    "load_guardrail_config",
+    "set_guardrails_client",
+    "clear_guardrail_cache",
+]
+