Promptheus

Promptheus

Refina y optimiza prompts para LLMs

Inicio 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 de la biblioteca Python

from promptheus import refine_prompt

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

Si ya estás en una aplicación asíncrona (por ejemplo, FastAPI), llama a refine_prompt_async en lugar del helper síncrono.

¿Qué es Promptheus?

Promptheus analiza tus prompts y los refina con:

• Preguntas adaptativas: Detección inteligente de qué información necesitas proporcionar
• Soporte multi-proveedor: Funciona con Google, OpenAI, Anthropic, Groq, Qwen y más
• Refinamiento interactivo: Mejora iterativamente los resultados mediante conversación natural
• Historial de sesiones: Rastrea y reutiliza automáticamente prompts anteriores
• CLI y Web UI: Úsalo desde la terminal o el navegador

Proveedores Soportados

Proveedor	Modelos	Configuración
Google Gemini	gemini-2.0-flash, gemini-1.5-pro	Clave API
Anthropic Claude	claude-3-5-sonnet, claude-3-opus	Consola
OpenAI	gpt-4o, gpt-4-turbo	Clave API
Groq	llama-3.3-70b, mixtral-8x7b	Consola
Alibaba Qwen	qwen-max, qwen-plus	DashScope
Zhipu GLM	glm-4-plus, glm-4-air	Consola
OpenRouter	openrouter/auto (auto-routing)	Panel

La integración de OpenRouter en Promptheus está optimizada alrededor del modelo de enrutamiento openrouter/auto:

• El listado de modelos es intencionalmente mínimo: Promptheus no expone tu catálogo completo de cuentas de OpenRouter.
• Aún puedes especificar un modelo concreto manualmente con OPENROUTER_MODEL o --model si tu clave tiene acceso.

Características Principales

🧠 Detección Adaptativa de Tareas Detecta automáticamente si tu tarea necesita refinamiento u optimización directa

⚡ Refinamiento Interactivo Haz preguntas específicas para obtener requisitos y mejorar los resultados

📝 Integración con Pipelines Funciona perfectamente en pipelines de Unix y scripts de shell

🔄 Gestión de Sesiones Rastrea, carga y reutiliza prompts anteriores automáticamente

📊 Telemetría y Analíticas Seguimiento anónimo de uso y métricas de rendimiento para obtener información (solo almacenamiento local, se puede desactivar)

🌐 Interfaz Web Interfaz atractiva para el refinamiento interactivo de prompts y la gestión del historial

Configuración

Crea un archivo .env con al menos una clave API de proveedor:

GOOGLE_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

O ejecuta la configuración interactiva:

promptheus auth

Ejemplos

Generación de Contenido

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

Análisis de Código

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

Sesión Interactiva

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

Integración con Pipelines

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

Pruebas y Ejemplos: Consulta sample_prompts.md para prompts de prueba que demuestran la detección adaptativa de tareas (análisis vs generación).

Telemetría y Analíticas

# 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

Promptheus incluye un servidor de Protocolo de Contexto de Modelo (MCP) que expone capacidades de refinamiento de prompts como herramientas estandarizadas para la integración con clientes compatibles con MCP.

¿Qué hace el Servidor MCP?

El servidor MCP de Promptheus proporciona:

• Refinamiento de prompts con preguntas y respuestas: Optimización inteligente de prompts mediante preguntas adaptativas
• Ajuste de prompts: Modificaciones quirúrgicas a prompts existentes
• Inspección de modelos/proveedores: Descubrimiento y validación de proveedores de IA disponibles
• Validación del entorno: Verificación de configuración y pruebas de conectividad

Iniciar el Servidor MCP

# Start the MCP server
promptheus mcp

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

Requisitos previos:

• Paquete MCP instalado: pip install mcp (incluido en requirements.txt)
• Al menos una clave API de proveedor configurada (ver Configuración)

Herramientas MCP Disponibles

refine_prompt

Refinamiento inteligente de prompts con preguntas de aclaración opcionales.

Entradas:

• prompt (obligatorio): El prompt inicial a refinar
• answers (opcional): Diccionario que mapea IDs de preguntas a respuestas {q0: "answer", q1: "answer"}
• answer_mapping (opcional): Mapea IDs de preguntas al texto original de la pregunta
• provider (opcional): Sobrescribir proveedor (por ejemplo, "google", "openai")
• model (opcional): Sobrescribir nombre del modelo

Tipos de Respuesta:

• {"type": "refined", "prompt": "...", "next_action": "..."}: Éxito con prompt refinado
• {"type": "clarification_needed", "questions_for_ask_user_question": [...], "answer_mapping": {...}}: Preguntas necesarias
• {"type": "error", "error_type": "...", "message": "..."}: Ocurrió un error

tweak_prompt

Aplica modificaciones específicas a prompts existentes.

Entradas:

• prompt (obligatorio): Prompt actual a modificar
• modification (obligatorio): Descripción de los cambios (por ejemplo, "hazlo más corto")
• provider, model (opcional): Sobrescrituras de proveedor/modelo

Devuelve:

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

list_models

Descubre modelos disponibles de los proveedores configurados.

Entradas:

• providers (opcional): Lista de nombres de proveedores a consultar
• limit (opcional): Máximo de modelos por proveedor (predeterminado: 20)
• include_nontext (opcional): Incluir modelos de visión/incrustación

Devuelve:

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

list_providers

Verifica el estado de configuración del proveedor.

Devuelve:

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

validate_environment

Prueba la configuración del entorno y la conectividad de la API.

Entradas:

• providers (opcional): Proveedores específicos a validar
• test_connection (opcional): Probar la conectividad real de la API

Devuelve:

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

Flujo de Trabajo de Refinamiento de Prompts con Preguntas y Respuestas

El servidor MCP admite un flujo de trabajo de aclaración estructurado para un refinamiento óptimo de prompts:

Paso 1: Solicitud Inicial de Refinamiento

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

Paso 2: Manejar la Respuesta de Aclaración

{
  "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?"
  }
}

Paso 3: Recopilar Respuestas del Usuario

Usa la herramienta AskUserQuestion de tu cliente MCP con las preguntas proporcionadas, luego mapea las respuestas a los IDs de preguntas.

Paso 4: Refinamiento Final con Respuestas

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

Respuesta:

{
  "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 Integración AskUser

El servidor MCP opera en dos modos:

Modo Interactivo (cuando AskUserQuestion está disponible):

• Pregunta automáticamente preguntas de aclaración mediante la función AskUserQuestion inyectada
• Devuelve el prompt refinado inmediatamente después de recopilar las respuestas
• Experiencia de usuario fluida en clientes compatibles

Modo Estructurado (respaldo para todos los clientes):

• Devuelve una respuesta clarification_needed con preguntas formateadas
• El cliente es responsable de llamar a la herramienta AskUserQuestion
• Las respuestas se mapean de vuelta mediante el diccionario answer_mapping

Formato de Pregunta: Cada pregunta en questions_for_ask_user_question incluye:

• question: El texto de la pregunta a mostrar
• header: Identificador corto (Q1, Q2, etc.)
• multiSelect: Booleano para opciones de selección múltiple
• options: Arreglo de {label, description} para preguntas de radio/casillas

Mapeo de Respuestas:

• Los IDs de preguntas siguen el patrón: q0, q1, q2, etc.
• El diccionario de respuestas usa estos IDs como claves: {"q0": "answer", "q1": "answer"}
• answer_mapping conserva el texto original de la pregunta para el contexto del proveedor

Solución de Problemas MCP

Paquete MCP No Instalado

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

Solución: pip install mcp o instala Promptheus con dependencias de desarrollo: pip install -e .[dev]

Faltan Claves API de Proveedor

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

Diagnóstico: Usa las herramientas list_providers o validate_environment para verificar el estado de configuración

Configuración Incorrecta del Proveedor

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

Solución: Establece las claves API faltantes en el archivo .env o en variables de entorno

Fallos en Pruebas de Conexión

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

Solución: Verifica que las claves API sean válidas y tengan los permisos necesarios

Documentación Completa

Referencia rápida: promptheus --help

Guías completas:

• 📖 Instalación y Configuración
• 🚀 Guía de Uso
• 🔧 Configuración
• ⌨️ Referencia CLI
• 🌐 Guía de Web UI
• 🔌 Configuración de Proveedores

Desarrollo

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

Consulta CLAUDE.md para obtener orientación detallada sobre desarrollo.

Licencia

Licencia MIT - consulta LICENSE para más detalles

Contribuciones

¡Las contribuciones son bienvenidas! Consulta nuestra guía de desarrollo para las pautas de contribución.

---

¿Preguntas? Abre un issue | Demo en vivo: promptheus web