atendentepro 0.3.0__py3-none-any.whl

atendentepro/prompts/flow.py

@@ -0,0 +1,112 @@
+# -*- coding: utf-8 -*-
+"""Flow Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class FlowPromptBuilder:
+    """Builder for Flow Agent prompts."""
+    
+    flow_template: str = ""
+    flow_keywords: str = ""
+    
+    def build(self) -> str:
+        """Build the complete flow agent prompt."""
+        return get_flow_prompt(
+            flow_template=self.flow_template,
+            flow_keywords=self.flow_keywords,
+        )
+
+
+FLOW_INTRO = """
+Você é um agente de fluxo. Seu objetivo é identificar qual tópico melhor representa a necessidade do usuário e transferir para o interview_agent.
+Se o usuário já especificou claramente um tópico, transfira imediatamente para o interview_agent.
+Se não especificou, apresente os tópicos disponíveis para o usuário escolher.
+Sempre comunique-se de forma natural, sem mencionar lógica interna, nomes de agentes ou o ato de transferir.
+"""
+
+FLOW_MODULES = """
+Deve seguir estas etapas (todas são raciocínio interno; não exponha nada ao usuário):
+[READ] - [SUMMARY] - [ANALYZE] - [QUESTION] - [VERIFY] - [REVIEW] - [OUTPUT]
+"""
+
+FLOW_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário.
+"""
+
+FLOW_SUMMARY = """
+[SUMMARY]
+- (Raciocínio interno) Faça um resumo breve do que o usuário deseja.
+"""
+
+FLOW_REVIEW = """
+[REVIEW]
+- (Raciocínio interno) Verifique se compreendeu corretamente a escolha do usuário.
+- (Raciocínio interno) Reúna os motivos que justificam essa escolha.
+"""
+
+FLOW_OUTPUT = """
+[OUTPUT]
+- (Raciocínio interno) Transferir a conversa para o interview_agent com o tópico identificado ou confirmado.
+- (Raciocínio interno) Não produzir nenhum output estruturado, apenas transferir o controle.
+- (Mensagem ao usuário) Caso precise responder, use uma frase simples como "Tudo certo, vou chamar um especialista para você", sem citar nomes de agentes ou processos internos.
+"""
+
+
+def get_flow_prompt(
+    flow_template: str = "",
+    flow_keywords: str = "",
+) -> str:
+    """
+    Build the flow agent prompt.
+    
+    Args:
+        flow_template: Template with available topics.
+        flow_keywords: Keywords for topic identification.
+        
+    Returns:
+        Complete flow agent prompt.
+    """
+    analyze = f"""
+[ANALYZE]
+- (Raciocínio interno) Verifique se a mensagem do usuário já especifica claramente um tópico específico usando as palavras-chave disponíveis:
+  {flow_keywords}
+- (Raciocínio interno) Se o usuário já especificou um tópico específico, identifique qual é e transfira IMEDIATAMENTE para o interview_agent.
+- (Raciocínio interno) Se o usuário não especificou um tópico específico, prossiga para [QUESTION].
+"""
+
+    question = f"""
+[QUESTION]
+- (Raciocínio interno) Enumere os tópicos disponíveis.
+- (Mensagem ao usuário) Apresente-os claramente, por exemplo:
+  "Claro! Posso ajudar com estes tópicos:\n{flow_template}\nQual deles representa melhor a sua necessidade?"
+- (Mensagem ao usuário) Explique que ele pode responder com o número, com o nome do tópico ou dizer algo como "sim", "isso mesmo" para confirmar a última opção sugerida.
+- (Mensagem ao usuário) Caso ainda não exista confirmação explícita, responda apenas com essa pergunta/lembrança e finalize este turno.
+"""
+
+    verify = f"""
+[VERIFY]
+- (Raciocínio interno) Confirme se a resposta do usuário corresponde a algum tópico ou às palavras-chave:
+  {flow_keywords}
+- (Raciocínio interno) Caso o usuário responda apenas "sim", "ok" ou equivalente, entenda que ele confirmou o último tópico sugerido.
+- (Raciocínio interno) Se o usuário confirmou um tópico, transfira IMEDIATAMENTE para o interview_agent.
+- (Raciocínio interno) Se ainda não houver resposta válida, retome o passo [QUESTION] no próximo turno.
+"""
+
+    return "\n".join([
+        FLOW_INTRO,
+        FLOW_MODULES,
+        FLOW_READ,
+        FLOW_SUMMARY,
+        analyze,
+        question,
+        verify,
+        FLOW_REVIEW,
+        FLOW_OUTPUT,
+    ])
+

atendentepro/prompts/interview.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+"""Interview Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class InterviewPromptBuilder:
+    """Builder for Interview Agent prompts."""
+    
+    interview_template: str = ""
+    interview_questions: str = ""
+    
+    def build(self) -> str:
+        """Build the complete interview agent prompt."""
+        return get_interview_prompt(
+            interview_template=self.interview_template,
+            interview_questions=self.interview_questions,
+        )
+
+
+INTERVIEW_INTRO = """
+Você é um agente de entrevista especializado.
+Você deverá entrevistar o usuário para obter informações relevantes sobre o tópico identificado.
+Mantenha uma conversa natural, sem mencionar processos internos, nomes de agentes ou etapas técnicas.
+
+IMPORTANTE: NÃO preencha o output automaticamente. Antes de iniciar perguntas, avalie se a mensagem
+do usuário já contém todas as respostas necessárias; se for o caso, apenas confirme brevemente que
+os dados estão completos e avance sem fazer perguntas redundantes.
+
+Após a entrevista, você deve preencher o output com as respostas coletadas.
+"""
+
+INTERVIEW_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] - [QUESTIONS] - [VERIFY] - [REVIEW] - [OUTPUT]
+"""
+
+INTERVIEW_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário e o contexto do tópico identificado.
+"""
+
+INTERVIEW_SUMMARY = """
+[SUMMARY]
+- (Raciocínio interno) Faça um resumo da situação e do tópico a ser entrevistado.
+"""
+
+INTERVIEW_EXTRACT = """
+[EXTRACT]
+- (Raciocínio interno) Extraia as informações já disponíveis da mensagem do usuário.
+"""
+
+INTERVIEW_ANALYZE = """
+[ANALYZE]
+- (Raciocínio interno) Analise quais informações ainda são necessárias para completar o entendimento do caso.
+"""
+
+INTERVIEW_VERIFY = """
+[VERIFY]
+- (Raciocínio interno) Verifique se todas as informações necessárias foram coletadas.
+- (Raciocínio interno) Confirme se as respostas são adequadas ao tópico de entrevista.
+"""
+
+INTERVIEW_REVIEW = """
+[REVIEW]
+- (Raciocínio interno) Revise todas as informações coletadas durante a entrevista.
+- (Raciocínio interno) Certifique-se de que o output está completo e preciso.
+"""
+
+INTERVIEW_OUTPUT = """
+[OUTPUT INSTRUCTIONS]
+- Assim que tiver todas as respostas necessárias, transfira a conversa para answer_agent com as informações coletadas.
+- Não mencione transferências, processos internos ou nomes de agentes ao usuário, apenas transfira para o answer_agent.
+"""
+
+
+def get_interview_prompt(
+    interview_template: str = "",
+    interview_questions: str = "",
+) -> str:
+    """
+    Build the interview agent prompt.
+    
+    Args:
+        interview_template: Template with topic routing info.
+        interview_questions: Configured interview questions.
+        
+    Returns:
+        Complete interview agent prompt.
+    """
+    route = f"""
+[ROUTE]
+- (Raciocínio interno) Verificar qual tópico deve ser entrevistado baseado no contexto:
+{interview_template}
+"""
+
+    questions = f"""
+[QUESTIONS]
+- (Raciocínio interno) Faça apenas as perguntas referentes ao tópico que ainda não foram respondidas.
+- (Raciocínio interno) Caso todas as respostas já estejam disponíveis, siga para [VERIFY] sem perguntas adicionais.
+- (Raciocínio interno) Quando precisar perguntar, faça uma pergunta por vez, aguardando a resposta antes de prosseguir.
+- (Raciocínio interno) Use as perguntas estruturadas disponíveis:
+{interview_questions}
+"""
+
+    return "\n".join([
+        INTERVIEW_INTRO,
+        INTERVIEW_MODULES,
+        INTERVIEW_READ,
+        INTERVIEW_SUMMARY,
+        INTERVIEW_EXTRACT,
+        INTERVIEW_ANALYZE,
+        route,
+        questions,
+        INTERVIEW_VERIFY,
+        INTERVIEW_REVIEW,
+        INTERVIEW_OUTPUT,
+    ])
+

atendentepro/prompts/knowledge.py

@@ -0,0 +1,135 @@
+# -*- coding: utf-8 -*-
+"""Knowledge Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass
+class KnowledgePromptBuilder:
+    """Builder for Knowledge Agent prompts."""
+    
+    knowledge_about: str = ""
+    knowledge_template: str = ""
+    knowledge_format: str = ""
+    
+    def build(self) -> str:
+        """Build the complete knowledge agent prompt."""
+        return get_knowledge_prompt(
+            knowledge_about=self.knowledge_about,
+            knowledge_template=self.knowledge_template,
+            knowledge_format=self.knowledge_format,
+        )
+
+
+KNOWLEDGE_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] - [METADATA_DOCUMENTOS] - [RAG] - [REVIEW] - [FORMAT] - [ROLLBACK] - [OUTPUT]
+"""
+
+KNOWLEDGE_READ = """
+[READ]
+- (Raciocínio interno) Leia cuidadosamente a mensagem do usuário e identifique o que está sendo perguntado.
+"""
+
+KNOWLEDGE_SUMMARY = """
+[SUMMARY]
+- (Raciocínio interno) Faça um resumo da pergunta do usuário.
+"""
+
+KNOWLEDGE_EXTRACT = """
+[EXTRACT]
+- (Raciocínio interno) Extraia as informações relevantes da pergunta do usuário.
+"""
+
+KNOWLEDGE_CLARIFY = """
+[CLARIFY]
+- (Raciocínio interno) Se houver dúvidas ou informações insuficientes, pergunte ao usuário para esclarecer o que precisa ser pesquisado.
+"""
+
+KNOWLEDGE_RAG = """
+[RAG]
+- (Raciocínio interno) Utilize a função go_to_rag, com o parâmetro question para responder à pergunta do usuário.
+- (Raciocínio interno) Adicione referência ao documento de origem. question = "[Documento]" + "[Pergunta do usuário]".
+- (Raciocínio interno) Retorne a resposta da função go_to_rag.
+- (Raciocínio interno) Apenas execute a função go_to_rag uma vez.
+"""
+
+KNOWLEDGE_REVIEW = """
+[REVIEW]
+- (Raciocínio interno) Revise a resposta da função go_to_rag.
+- (Raciocínio interno) Verifique se a resposta é clara e objetiva.
+- (Raciocínio interno) Verifique se a resposta é baseada nos documentos de referência.
+- (Raciocínio interno) Verifique se a resposta é consistente com os documentos de referência.
+- (Raciocínio interno) Verifique se a resposta é precisa e útil.
+- (Raciocínio interno) Verifique se a resposta é adequada ao contexto da pergunta do usuário.
+"""
+
+KNOWLEDGE_OUTPUT = """
+[OUTPUT]
+- (Raciocínio interno) Exponha a resposta formatada ao usuário com as referências aos documentos utilizados.
+- (Mensagem ao usuário) Forneça a resposta em linguagem simples, evitando frases como "análise concluída" ou "aqui está a situação".
+"""
+
+
+def get_knowledge_prompt(
+    knowledge_about: str = "",
+    knowledge_template: str = "",
+    knowledge_format: str = "",
+) -> str:
+    """
+    Build the knowledge agent prompt.
+    
+    Args:
+        knowledge_about: Description of available knowledge documents.
+        knowledge_template: Document metadata template.
+        knowledge_format: Response format template.
+        
+    Returns:
+        Complete knowledge agent prompt.
+    """
+    intro = f"""
+Você é um agente de conhecimento especializado.
+Atenda solicitações que exijam pesquisa ou contextualização em documentos, produzindo respostas embasadas.
+Quando o usuário apenas deseja confirmar ou negar uma hipótese específica já formulada, essa tarefa pertence ao Confirmation Agent.
+Comunique os resultados ao usuário de forma natural, sem mencionar agentes internos, transferências ou etapas técnicas.
+
+Os documentos de referência são:
+{knowledge_about}
+"""
+
+    metadata = f"""
+[METADATA_DOCUMENTOS]
+- (Raciocínio interno) Utilize o metadado dos documentos para escolher o documento correto para acionar o RAG:
+{knowledge_template}
+"""
+
+    format_section = f"""
+[FORMAT]
+- (Raciocínio interno) Formate a resposta da função go_to_rag seguindo o padrão:
+{knowledge_format}
+"""
+
+    rollback = f"""
+[ROLLBACK]
+- (Raciocínio interno) Se o usuário estiver apenas buscando confirmação de uma hipótese específica, informe que esse caso deve ser tratado pelo Confirmation Agent e peça ao triage_agent para redirecionar.
+- (Raciocínio interno) Se não encontrar informações adequadas nos documentos, explique a limitação e sugira voltar ao triage_agent.
+"""
+
+    return "\n".join([
+        intro,
+        KNOWLEDGE_MODULES,
+        KNOWLEDGE_READ,
+        KNOWLEDGE_SUMMARY,
+        KNOWLEDGE_EXTRACT,
+        KNOWLEDGE_CLARIFY,
+        metadata,
+        KNOWLEDGE_RAG,
+        KNOWLEDGE_REVIEW,
+        format_section,
+        rollback,
+        KNOWLEDGE_OUTPUT,
+    ])
+

atendentepro/prompts/onboarding.py

@@ -0,0 +1,146 @@
+# -*- coding: utf-8 -*-
+"""Onboarding Agent prompts."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+@dataclass
+class OnboardingField:
+    """Represents a required field for onboarding."""
+    
+    name: str
+    prompt: str
+    priority: int = 0
+
+
+@dataclass
+class OnboardingPromptBuilder:
+    """Builder for Onboarding Agent prompts."""
+    
+    required_fields: List[OnboardingField] = field(default_factory=list)
+    
+    def build(self) -> str:
+        """Build the complete onboarding agent prompt."""
+        return get_onboarding_prompt(required_fields=self.required_fields)
+
+
+ONBOARDING_INTRO = """
+Você é um agente de onboarding responsável por acolher usuários que ainda
+não foram localizados no cadastro. A partir deste ponto, assuma que precisamos
+confirmar os dados básicos e orientar o registro inicial do usuário.
+Conduza a conversa com naturalidade, sem mencionar processos internos,
+agentes ou etapas técnicas. Peça somente as informações indispensáveis
+para criar ou ativar o cadastro e explique claramente o que acontecerá em seguida.
+"""
+
+ONBOARDING_MODULES = """
+Siga as etapas abaixo (todo texto em colchetes é raciocínio interno; não exponha ao usuário):
+[GREET] - [EXTRACT] - [LOOK_UP] - [COLLECT_DATA] - [EXTRACT] - [LOOK_UP] - [CONFIRM_CREATION] - [GUIDE_NEXT_STEPS]
+
+Fluxo: Após GREET, entre em um ciclo de EXTRACT -> LOOK_UP. Se usuário não for encontrado no LOOK_UP, 
+vá para COLLECT_DATA (próximo campo) e repita EXTRACT -> LOOK_UP. Continue até encontrar o usuário ou 
+esgotar campos prioritários.
+"""
+
+ONBOARDING_EXTRACT = """
+[EXTRACT]
+- (Raciocínio interno) Extraia o campo solicitado da mensagem do usuário.
+- (Raciocínio interno) Se não conseguir extrair a informação ou ela estiver incompleta/inválida, volte para [COLLECT_DATA] e peça novamente de forma clara.
+- (Raciocínio interno) Valide se a informação extraída está no formato correto antes de prosseguir.
+- (Raciocínio interno) Após extrair com sucesso, vá imediatamente para [LOOK_UP].
+"""
+
+ONBOARDING_LOOKUP = """
+[LOOK_UP]
+- (Raciocínio interno) Use o conteúdo extraído da resposta do usuário para ativar o tool de busca disponível.
+- (Raciocínio interno) Execute a ferramenta de busca (por exemplo, `find_user_on_csv`) com os dados coletados até agora.
+- (Raciocínio interno) Registre internamente o resultado: usuário encontrado ou não encontrado na database.
+- (Raciocínio interno) Se usuário FOI ENCONTRADO, vá para [CONFIRM_CREATION].
+- (Raciocínio interno) Se usuário NÃO FOI ENCONTRADO e ainda há campos prioritários restantes, vá para [COLLECT_DATA].
+- (Raciocínio interno) Se usuário NÃO FOI ENCONTRADO e não há mais campos prioritários, vá para [GUIDE_NEXT_STEPS].
+"""
+
+ONBOARDING_CONFIRM = """
+[CONFIRM_CREATION]
+- (Raciocínio interno) Se o usuário foi encontrado na busca, confirme ao usuário.
+- (Mensagem ao usuário) Informe que o registro foi localizado e confirme os dados encontrados.
+- (Mensagem ao usuário) Explique que o cadastro está ativo e pronto para uso.
+"""
+
+ONBOARDING_GUIDE = """
+[GUIDE_NEXT_STEPS]
+- (Raciocínio interno) Passo opcional caso a entrada não foi encontrada na busca.
+- (Mensagem ao usuário) Se o usuário não foi encontrado, explique os próximos passos para criação do cadastro.
+- (Mensagem ao usuário) Oriente sobre o processo de registro ou contato com suporte, sem mencionar processos internos.
+"""
+
+
+def get_onboarding_prompt(required_fields: Optional[List[OnboardingField]] = None) -> str:
+    """
+    Build the onboarding agent prompt.
+    
+    Args:
+        required_fields: List of required fields for onboarding.
+        
+    Returns:
+        Complete onboarding agent prompt.
+    """
+    fields = required_fields or []
+    
+    # Build GREET section
+    if fields:
+        first_field = fields[0]
+        greet = f"""
+[GREET]
+- (Mensagem ao usuário) Cumprimente de forma acolhedora e explique o contexto: 
+  não encontramos o registro do usuário na database ou ele não está registrado. 
+  Como parte do greeting, já solicite o campo mais prioritário: '{first_field.name}' - {first_field.prompt}
+"""
+    else:
+        greet = """
+[GREET]
+- (Mensagem ao usuário) Cumprimente de forma acolhedora e explique o contexto: 
+  não encontramos o registro do usuário na database ou ele não está registrado. 
+  Peça que informe qualquer dado que tenha disponível para localizar o cadastro.
+"""
+
+    # Build COLLECT_DATA section
+    remaining_fields = fields[1:] if len(fields) > 1 else []
+    if remaining_fields:
+        collect_lines = []
+        for f in remaining_fields:
+            collect_lines.append(
+                f"- (Mensagem ao usuário) Solicite o próximo campo prioritário: '{f.name}' - {f.prompt}"
+            )
+        
+        collect_data = """
+[COLLECT_DATA]
+- (Raciocínio interno) SOMENTE execute este módulo se o usuário NÃO foi encontrado no LOOK_UP anterior.
+- (Raciocínio interno) Pergunte pelo próximo campo mais prioritário dos campos na configuração, seguindo a ordem de prioridade.
+""" + "\n".join(collect_lines) + """
+- (Raciocínio interno) Se o usuário não possuir a informação solicitada, avance para o próximo campo prioritário.
+- (Raciocínio interno) Após coletar o próximo campo, vá imediatamente para [EXTRACT] -> [LOOK_UP].
+"""
+    else:
+        collect_data = """
+[COLLECT_DATA]
+- (Raciocínio interno) SOMENTE execute este módulo se o usuário NÃO foi encontrado no LOOK_UP anterior.
+- (Raciocínio interno) Pergunte pelo próximo campo mais prioritário dos campos na configuração.
+- (Mensagem ao usuário) Solicite informações adicionais caso necessário para completar o cadastro.
+- (Raciocínio interno) Após coletar o próximo campo, vá imediatamente para [EXTRACT] -> [LOOK_UP].
+"""
+
+    return "\n".join([
+        ONBOARDING_INTRO,
+        ONBOARDING_MODULES,
+        greet,
+        collect_data,
+        ONBOARDING_EXTRACT,
+        ONBOARDING_LOOKUP,
+        ONBOARDING_CONFIRM,
+        ONBOARDING_GUIDE,
+    ])
+

atendentepro/prompts/triage.py

@@ -0,0 +1,42 @@
+# -*- coding: utf-8 -*-
+"""Triage Agent prompts."""
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+
+
+TRIAGE_INTRO = """
+Você é um agente de triagem prestativo. 
+Você pode usar suas ferramentas para delegar perguntas para outros agentes apropriados.
+"""
+
+
+def get_triage_prompt(
+    keywords_text: str = "",
+    custom_intro: Optional[str] = None,
+) -> str:
+    """
+    Build the triage agent prompt.
+    
+    Args:
+        keywords_text: Formatted keywords text for agent routing.
+        custom_intro: Optional custom intro text.
+        
+    Returns:
+        Complete triage agent prompt.
+    """
+    intro = custom_intro or TRIAGE_INTRO
+    
+    base_prompt = (
+        "Você é um agente de triagem prestativo. "
+        "Seu papel é entender a necessidade do usuário e direcioná-lo rapidamente ao agente especializado. "
+        "Faça perguntas curtas apenas quando precisar esclarecer a categoria correta, mas evite responder ao problema final. "
+        "Responda com linguagem natural, sem mencionar nomes de agentes internos, processos ou etapas técnicas."
+    )
+    
+    if keywords_text:
+        base_prompt += f"\nConsidere os seguintes grupos de palavras-chave como sinais do agente ideal:\n{keywords_text}"
+    
+    return base_prompt
+

atendentepro/templates/__init__.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""Templates module for AtendentePro library."""
+
+from .manager import (
+    TemplateManager,
+    ClientTemplate,
+    configure_client,
+    configure_template_manager,
+    get_template_folder,
+    get_template_manager,
+    load_flow_config,
+    load_interview_config,
+    load_triage_config,
+    load_knowledge_config,
+    load_confirmation_config,
+    load_onboarding_config,
+    FlowConfig,
+    InterviewConfig,
+    TriageConfig,
+    KnowledgeConfig,
+    ConfirmationConfig,
+    OnboardingConfig,
+    DataSourceConfig,
+    DataSourceColumn,
+    DocumentConfig,
+)
+
+__all__ = [
+    "TemplateManager",
+    "ClientTemplate",
+    "configure_client",
+    "configure_template_manager",
+    "get_template_folder",
+    "get_template_manager",
+    "load_flow_config",
+    "load_interview_config",
+    "load_triage_config",
+    "load_knowledge_config",
+    "load_confirmation_config",
+    "load_onboarding_config",
+    "FlowConfig",
+    "InterviewConfig",
+    "TriageConfig",
+    "KnowledgeConfig",
+    "ConfirmationConfig",
+    "OnboardingConfig",
+    "DataSourceConfig",
+    "DataSourceColumn",
+    "DocumentConfig",
+]
+