Promptheus

Ferramenta de refinamento de prompts com inteligência artificial, com questionamento adaptativo e suporte a múltiplos provedores. Refina prompts de forma inteligente por meio de perguntas esclarecedoras, suporta mais de 6 provedores de IA (Google Gemini, Anthropic Claude, OpenAI, Groq, Alibaba Qwen, Zhipu GLM) e oferece recursos abrangentes de engenharia de prompts.

GitHub

Documentação

Promptheus

Refine e otimize prompts para LLMs

Início Rápido

pip install promptheus

# Interactive session
promptheus

# Single prompt
promptheus "Write a technical blog post"

# Skip clarifying questions
promptheus -s "Explain Kubernetes"

# Use web UI
promptheus web

Uso da biblioteca Python

from promptheus import refine_prompt

result = refine_prompt("Write a technical blog post", skip_questions=True)
print(result["refined_prompt"])

Se você já está em uma aplicação assíncrona (ex.: FastAPI), chame refine_prompt_async em vez do helper síncrono.

O que é o Promptheus?

O Promptheus analisa seus prompts e os refina com:

Questionamento adaptativo: Detecção inteligente de quais informações você precisa fornecer
Suporte a múltiplos provedores: Funciona com Google, OpenAI, Anthropic, Groq, Qwen e outros
Refinamento interativo: Melhore resultados iterativamente por meio de conversa natural
Histórico de sessões: Rastreie e reutilize prompts anteriores automaticamente
CLI e Interface Web: Use pelo terminal ou navegador

Provedores Suportados

Provedor	Modelos	Configuração
Google Gemini	gemini-2.0-flash, gemini-1.5-pro	Chave de API
Anthropic Claude	claude-3-5-sonnet, claude-3-opus	Console
OpenAI	gpt-4o, gpt-4-turbo	Chave de API
Groq	llama-3.3-70b, mixtral-8x7b	Console
Alibaba Qwen	qwen-max, qwen-plus	DashScope
Zhipu GLM	glm-4-plus, glm-4-air	Console
OpenRouter	openrouter/auto (roteamento automático)	Painel

A integração com OpenRouter no Promptheus é otimizada em torno do modelo de roteamento openrouter/auto:

A listagem de modelos é intencionalmente mínima: o Promptheus não expõe seu catálogo completo de contas do OpenRouter.
Você ainda pode especificar um modelo concreto manualmente com OPENROUTER_MODEL ou --model se sua chave tiver acesso.

Recursos Principais

🧠 Detecção Adaptativa de Tarefas Detecta automaticamente se sua tarefa precisa de refinamento ou otimização direta

⚡ Refinamento Interativo Faça perguntas direcionadas para elicitar requisitos e melhorar resultados

📝 Integração com Pipelines Funciona perfeitamente em pipelines Unix e scripts de shell

🔄 Gerenciamento de Sessões Rastreie, carregue e reutilize prompts anteriores automaticamente

📊 Telemetria e Análises Rastreamento anônimo de uso e métricas de desempenho para insights (armazenamento local apenas, pode ser desativado)

🌐 Interface Web UI bonita para refinamento interativo de prompts e gerenciamento de histórico

Configuração

Crie um arquivo .env com pelo menos uma chave de API de provedor:

GOOGLE_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Ou execute a configuração interativa:

promptheus auth

Exemplos

Geração de Conteúdo

promptheus "Write a blog post about async programming"
# System asks: audience, tone, length, key topics
# Generates refined prompt with all specifications

Análise de Código

promptheus -s "Review this function for security issues"
# Skips questions, applies direct enhancement

Sessão Interativa

promptheus
/set provider anthropic
/set model claude-3-5-sonnet
# Process multiple prompts, switch providers/models with /commands

Integração com Pipelines

echo "Create a REST API schema" | promptheus | jq '.refined_prompt'
cat prompts.txt | while read line; do promptheus "$line"; done

Testes e Exemplos: Veja sample_prompts.md para prompts de teste que demonstram detecção adaptativa de tarefas (análise vs. geração).

Telemetria e Análises

# View telemetry summary (anonymous metrics about usage and performance)
promptheus telemetry summary

# Disable telemetry if desired
export PROMPTHEUS_TELEMETRY_ENABLED=0

# Customize history storage location
export PROMPTHEUS_HISTORY_DIR=~/.custom_promptheus

Servidor MCP

O Promptheus inclui um servidor Model Context Protocol (MCP) que expõe capacidades de refinamento de prompts como ferramentas padronizadas para integração com clientes compatíveis com MCP.

O que o Servidor MCP Faz

O servidor MCP do Promptheus fornece:

Refinamento de prompts com perguntas e respostas: Otimização inteligente de prompts por meio de questionamento adaptativo
Ajuste de prompts: Modificações cirúrgicas em prompts existentes
Inspeção de modelos/provedores: Descoberta e validação de provedores de IA disponíveis
Validação de ambiente: Verificação de configuração e teste de conectividade

Iniciando o Servidor MCP

# Start the MCP server
promptheus mcp

# Or run directly with Python
python -m promptheus.mcp_server

Pré-requisitos:

Pacote MCP instalado: pip install mcp (incluído no requirements.txt)
Pelo menos uma chave de API de provedor configurada (veja Configuração)

Ferramentas MCP Disponíveis

`refine_prompt`

Refinamento inteligente de prompts com perguntas de esclarecimento opcionais.

Entradas:

prompt (obrigatório): O prompt inicial a ser refinado
answers (opcional): Dicionário mapeando IDs de perguntas para respostas {q0: "answer", q1: "answer"}
answer_mapping (opcional): Mapeia IDs de perguntas para o texto original da pergunta
provider (opcional): Substituir provedor (ex.: "google", "openai")
model (opcional): Substituir nome do modelo

Tipos de Resposta:

{"type": "refined", "prompt": "...", "next_action": "..."}: Sucesso com prompt refinado
{"type": "clarification_needed", "questions_for_ask_user_question": [...], "answer_mapping": {...}}: Perguntas necessárias
{"type": "error", "error_type": "...", "message": "..."}: Ocorreu um erro

`tweak_prompt`

Aplicar modificações direcionadas em prompts existentes.

Entradas:

prompt (obrigatório): Prompt atual a ser modificado
modification (obrigatório): Descrição das alterações (ex.: "tornar mais curto")
provider, model (opcional): Substituições de provedor/modelo

Retorna:

{"type": "refined", "prompt": "..."}: Prompt modificado

`list_models`

Descobrir modelos disponíveis dos provedores configurados.

Entradas:

providers (opcional): Lista de nomes de provedores a consultar
limit (opcional): Máximo de modelos por provedor (padrão: 20)
include_nontext (opcional): Incluir modelos de visão/embedding

Retorna:

{"type": "success", "providers": {"google": {"available": true, "models": [...]}}}

`list_providers`

Verificar o status de configuração do provedor.

Retorna:

{"type": "success", "providers": {"google": {"configured": true, "model": "..."}}}

`validate_environment`

Testar a configuração do ambiente e a conectividade da API.

Entradas:

providers (opcional): Provedores específicos a validar
test_connection (opcional): Testar conectividade real da API

Retorna:

{"type": "success", "validation": {"google": {"configured": true, "connection_test": "passed"}}}

Fluxo de Trabalho de Refinamento de Prompts com Perguntas e Respostas

O servidor MCP suporta um fluxo de trabalho estruturado de esclarecimento para refinamento ideal de prompts:

Etapa 1: Solicitação Inicial de Refinamento

{
  "tool": "refine_prompt",
  "arguments": {
    "prompt": "Write a blog post about machine learning"
  }
}

Etapa 2: Tratar Resposta de Esclarecimento

{
  "type": "clarification_needed",
  "task_type": "generation",
  "message": "To refine this prompt effectively, I need to ask...",
  "questions_for_ask_user_question": [
    {
      "question": "Who is your target audience?",
      "header": "Q1",
      "multiSelect": false,
      "options": [
        {"label": "Technical professionals", "description": "Technical professionals"},
        {"label": "Business executives", "description": "Business executives"}
      ]
    }
  ],
  "answer_mapping": {
    "q0": "Who is your target audience?"
  }
}

Etapa 3: Coletar Respostas do Usuário

Use a ferramenta AskUserQuestion do seu cliente MCP com as perguntas fornecidas e, em seguida, mapeie as respostas para os IDs das perguntas.

Etapa 4: Refinamento Final com Respostas

{
  "tool": "refine_prompt", 
  "arguments": {
    "prompt": "Write a blog post about machine learning",
    "answers": {"q0": "Technical professionals"},
    "answer_mapping": {"q0": "Who is your target audience?"}
  }
}

Resposta:

{
  "type": "refined",
  "prompt": "Write a comprehensive technical blog post about machine learning fundamentals targeted at software engineers and technical professionals. Include practical code examples and architectural patterns...",
  "next_action": "This refined prompt is now ready to use. If the user asked you to execute/run the prompt, use this refined prompt directly with your own capabilities..."
}

Contrato de Integração AskUser

O servidor MCP opera em dois modos:

Modo Interativo (quando AskUserQuestion está disponível):

Faz perguntas de esclarecimento automaticamente por meio da função AskUserQuestion injetada
Retorna o prompt refinado imediatamente após coletar as respostas
Experiência de usuário perfeita em clientes compatíveis

Modo Estruturado (fallback para todos os clientes):

Retorna resposta clarification_needed com perguntas formatadas
O cliente é responsável por chamar a ferramenta AskUserQuestion
As respostas são mapeadas de volta via dicionário answer_mapping

Formato das Perguntas: Cada pergunta em questions_for_ask_user_question inclui:

question: O texto da pergunta a ser exibido
header: Identificador curto (Q1, Q2, etc.)
multiSelect: Booleano para opções de múltipla seleção
options: Matriz de {label, description} para perguntas de rádio/checkbox

Mapeamento de Respostas:

Os IDs das perguntas seguem o padrão: q0, q1, q2, etc.
O dicionário de respostas usa esses IDs como chaves: {"q0": "answer", "q1": "answer"}
answer_mapping preserva o texto original da pergunta para contexto do provedor

Solução de Problemas do MCP

Pacote MCP Não Instalado

Error: The 'mcp' package is not installed. Please install it with 'pip install mcp'.

Correção: pip install mcp ou instale o Promptheus com dependências de desenvolvimento: pip install -e .[dev]

Chaves de API de Provedor Ausentes

{
  "type": "error",
  "error_type": "ConfigurationError", 
  "message": "No provider configured. Please set API keys in environment."
}

Diagnóstico: Use as ferramentas list_providers ou validate_environment para verificar o status da configuração

Configuração Incorreta do Provedor

{
  "type": "success",
  "providers": {
    "google": {"configured": false, "error": "GOOGLE_API_KEY not found"},
    "openai": {"configured": true, "model": "gpt-4o"}
  }
}

Correção: Defina as chaves de API ausentes no arquivo .env ou nas variáveis de ambiente

Falhas no Teste de Conexão

{
  "type": "success", 
  "validation": {
    "google": {
      "configured": true,
      "connection_test": "failed: Authentication error"
    }
  }
}

Correção: Verifique se as chaves de API são válidas e têm as permissões necessárias

Documentação Completa

Referência rápida: promptheus --help

Guias abrangentes:

Desenvolvimento

git clone https://github.com/abhichandra21/Promptheus.git
cd Promptheus
pip install -e ".[dev]"
pytest -q

Veja CLAUDE.md para orientações detalhadas de desenvolvimento.

Licença

Licença MIT - veja LICENSE para detalhes

Contribuindo

Contribuições são bem-vindas! Consulte nosso guia de desenvolvimento para diretrizes de contribuição.

Perguntas? Abra uma issue | Demonstração ao vivo: promptheus web