Promptheus

Refine and optimize prompts for LLMs

Quick Start

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

Python library usage

from promptheus import refine_prompt

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

If you're already in an async application (e.g., FastAPI), call refine_prompt_async instead of the sync helper.

What is Promptheus?

Promptheus analyzes your prompts and refines them with:

Adaptive questioning: Smart detection of what information you need to provide
Multi-provider support: Works with Google, OpenAI, Anthropic, Groq, Qwen, and more
Interactive refinement: Iteratively improve outputs through natural conversation
Session history: Automatically track and reuse past prompts
CLI and Web UI: Use from terminal or browser

Supported Providers

Provider	Models	Setup
Google Gemini	gemini-2.0-flash, gemini-1.5-pro	API Key
Anthropic Claude	claude-3-5-sonnet, claude-3-opus	Console
OpenAI	gpt-4o, gpt-4-turbo	API Key
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 (auto-routing)	Dashboard

OpenRouter integration in Promptheus is optimized around the openrouter/auto routing model:

Model listing is intentionally minimal: Promptheus does not expose your full OpenRouter account catalog.
You can still specify a concrete model manually with OPENROUTER_MODEL or --model if your key has access.

Core Features

🧠 Adaptive Task Detection Automatically detects whether your task needs refinement or direct optimization

⚡ Interactive Refinement Ask targeted questions to elicit requirements and improve outputs

📝 Pipeline Integration Works seamlessly in Unix pipelines and shell scripts

🔄 Session Management Track, load, and reuse past prompts automatically

📊 Telemetry & Analytics Anonymous usage and performance metrics tracking for insights (local storage only, can be disabled)

🌐 Web Interface Beautiful UI for interactive prompt refinement and history management

Configuration

Create a .env file with at least one provider API key:

GOOGLE_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Or run the interactive setup:

promptheus auth

Examples

Content Generation

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

Code Analysis

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

Interactive Session

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

Pipeline Integration

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

Testing & Examples: See sample_prompts.md for test prompts demonstrating adaptive task detection (analysis vs generation).

Telemetry & Analytics

# 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

MCP Server

Promptheus includes a Model Context Protocol (MCP) server that exposes prompt refinement capabilities as standardized tools for integration with MCP-compatible clients.

What the MCP Server Does

The Promptheus MCP server provides:

Prompt refinement with Q&A: Intelligent prompt optimization through adaptive questioning
Prompt tweaking: Surgical modifications to existing prompts
Model/provider inspection: Discovery and validation of available AI providers
Environment validation: Configuration checking and connectivity testing

Starting the MCP Server

# Start the MCP server
promptheus mcp

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

Prerequisites:

MCP package installed: pip install mcp (included in requirements.txt)
At least one provider API key configured (see Configuration)

Available MCP Tools

`refine_prompt`

Intelligent prompt refinement with optional clarification questions.

Inputs:

prompt (required): The initial prompt to refine
answers (optional): Dictionary mapping question IDs to answers {q0: "answer", q1: "answer"}
answer_mapping (optional): Maps question IDs to original question text
provider (optional): Override provider (e.g., "google", "openai")
model (optional): Override model name

Response Types:

{"type": "refined", "prompt": "...", "next_action": "..."}: Success with refined prompt
{"type": "clarification_needed", "questions_for_ask_user_question": [...], "answer_mapping": {...}}: Questions needed
{"type": "error", "error_type": "...", "message": "..."}: Error occurred

`tweak_prompt`

Apply targeted modifications to existing prompts.

Inputs:

prompt (required): Current prompt to modify
modification (required): Description of changes (e.g., "make it shorter")
provider, model (optional): Provider/model overrides

Returns:

{"type": "refined", "prompt": "..."}: Modified prompt

`list_models`

Discover available models from configured providers.

Inputs:

providers (optional): List of provider names to query
limit (optional): Max models per provider (default: 20)
include_nontext (optional): Include vision/embedding models

Returns:

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

`list_providers`

Check provider configuration status.

Returns:

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

`validate_environment`

Test environment configuration and API connectivity.

Inputs:

providers (optional): Specific providers to validate
test_connection (optional): Test actual API connectivity

Returns:

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

The MCP server supports a structured clarification workflow for optimal prompt refinement:

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

Step 2: Handle Clarification Response

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

Step 3: Collect User Answers

Use your MCP client's AskUserQuestion tool with the provided questions, then map answers to question IDs.

Step 4: Final Refinement with Answers

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

Response:

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

AskUser Integration Contract

The MCP server operates in two modes:

Interactive Mode (when AskUserQuestion is available):

Automatically asks clarification questions via injected AskUserQuestion function
Returns refined prompt immediately after collecting answers
Seamless user experience within supported clients

Structured Mode (fallback for all clients):

Returns clarification_needed response with formatted questions
Client responsible for calling AskUserQuestion tool
Answers mapped back via answer_mapping dictionary

Question Format: Each question in questions_for_ask_user_question includes:

question: The question text to display
header: Short identifier (Q1, Q2, etc.)
multiSelect: Boolean for multi-select options
options: Array of {label, description} for radio/checkbox questions

Answer Mapping:

Question IDs follow pattern: q0, q1, q2, etc.
Answers dictionary uses these IDs as keys: {"q0": "answer", "q1": "answer"}
answer_mapping preserves original question text for provider context

Troubleshooting MCP

MCP Package Not Installed

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

Fix: pip install mcp or install Promptheus with dev dependencies: pip install -e .[dev]

Missing Provider API Keys

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

Diagnosis: Use list_providers or validate_environment tools to check configuration status

Provider Misconfiguration

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

Fix: Set missing API keys in .env file or environment variables

Connection Test Failures

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

Fix: Verify API keys are valid and have necessary permissions

Full Documentation

Quick reference: promptheus --help

Comprehensive guides:

Development

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

See CLAUDE.md for detailed development guidance.

License

MIT License - see LICENSE for details

Contributing

Contributions welcome! Please see our development guide for contribution guidelines.

Questions? Open an issue | Live demo: promptheus web

Promptheus

Refine and optimize prompts for LLMs

Quick Start

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

Python library usage

from promptheus import refine_prompt

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

If you're already in an async application (e.g., FastAPI), call refine_prompt_async instead of the sync helper.

What is Promptheus?

Promptheus analyzes your prompts and refines them with:

Adaptive questioning: Smart detection of what information you need to provide
Multi-provider support: Works with Google, OpenAI, Anthropic, Groq, Qwen, and more
Interactive refinement: Iteratively improve outputs through natural conversation
Session history: Automatically track and reuse past prompts
CLI and Web UI: Use from terminal or browser

Supported Providers

Provider	Models	Setup
Google Gemini	gemini-2.0-flash, gemini-1.5-pro	API Key
Anthropic Claude	claude-3-5-sonnet, claude-3-opus	Console
OpenAI	gpt-4o, gpt-4-turbo	API Key
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 (auto-routing)	Dashboard

OpenRouter integration in Promptheus is optimized around the openrouter/auto routing model:

Model listing is intentionally minimal: Promptheus does not expose your full OpenRouter account catalog.
You can still specify a concrete model manually with OPENROUTER_MODEL or --model if your key has access.

Core Features

🧠 Adaptive Task Detection Automatically detects whether your task needs refinement or direct optimization

⚡ Interactive Refinement Ask targeted questions to elicit requirements and improve outputs

📝 Pipeline Integration Works seamlessly in Unix pipelines and shell scripts

🔄 Session Management Track, load, and reuse past prompts automatically

📊 Telemetry & Analytics Anonymous usage and performance metrics tracking for insights (local storage only, can be disabled)

🌐 Web Interface Beautiful UI for interactive prompt refinement and history management

Configuration

Create a .env file with at least one provider API key:

GOOGLE_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
OPENAI_API_KEY=your_key_here

Or run the interactive setup:

promptheus auth

Examples

Content Generation

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

Code Analysis

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

Interactive Session

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

Pipeline Integration

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

Testing & Examples: See sample_prompts.md for test prompts demonstrating adaptive task detection (analysis vs generation).

Telemetry & Analytics

# 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

MCP Server

Promptheus includes a Model Context Protocol (MCP) server that exposes prompt refinement capabilities as standardized tools for integration with MCP-compatible clients.

What the MCP Server Does

The Promptheus MCP server provides:

Prompt refinement with Q&A: Intelligent prompt optimization through adaptive questioning
Prompt tweaking: Surgical modifications to existing prompts
Model/provider inspection: Discovery and validation of available AI providers
Environment validation: Configuration checking and connectivity testing

Starting the MCP Server

# Start the MCP server
promptheus mcp

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

Prerequisites:

MCP package installed: pip install mcp (included in requirements.txt)
At least one provider API key configured (see Configuration)

Available MCP Tools

`refine_prompt`

Intelligent prompt refinement with optional clarification questions.

Inputs:

prompt (required): The initial prompt to refine
answers (optional): Dictionary mapping question IDs to answers {q0: "answer", q1: "answer"}
answer_mapping (optional): Maps question IDs to original question text
provider (optional): Override provider (e.g., "google", "openai")
model (optional): Override model name

Response Types:

{"type": "refined", "prompt": "...", "next_action": "..."}: Success with refined prompt
{"type": "clarification_needed", "questions_for_ask_user_question": [...], "answer_mapping": {...}}: Questions needed
{"type": "error", "error_type": "...", "message": "..."}: Error occurred

`tweak_prompt`

Apply targeted modifications to existing prompts.

Inputs:

prompt (required): Current prompt to modify
modification (required): Description of changes (e.g., "make it shorter")
provider, model (optional): Provider/model overrides

Returns:

{"type": "refined", "prompt": "..."}: Modified prompt

`list_models`

Discover available models from configured providers.

Inputs:

providers (optional): List of provider names to query
limit (optional): Max models per provider (default: 20)
include_nontext (optional): Include vision/embedding models

Returns:

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

`list_providers`

Check provider configuration status.

Returns:

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

`validate_environment`

Test environment configuration and API connectivity.

Inputs:

providers (optional): Specific providers to validate
test_connection (optional): Test actual API connectivity

Returns:

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

The MCP server supports a structured clarification workflow for optimal prompt refinement:

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

Step 2: Handle Clarification Response

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

Step 3: Collect User Answers

Use your MCP client's AskUserQuestion tool with the provided questions, then map answers to question IDs.

Step 4: Final Refinement with Answers

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

Response:

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

AskUser Integration Contract

The MCP server operates in two modes:

Interactive Mode (when AskUserQuestion is available):

Automatically asks clarification questions via injected AskUserQuestion function
Returns refined prompt immediately after collecting answers
Seamless user experience within supported clients

Structured Mode (fallback for all clients):

Returns clarification_needed response with formatted questions
Client responsible for calling AskUserQuestion tool
Answers mapped back via answer_mapping dictionary

Question Format: Each question in questions_for_ask_user_question includes:

question: The question text to display
header: Short identifier (Q1, Q2, etc.)
multiSelect: Boolean for multi-select options
options: Array of {label, description} for radio/checkbox questions

Answer Mapping:

Question IDs follow pattern: q0, q1, q2, etc.
Answers dictionary uses these IDs as keys: {"q0": "answer", "q1": "answer"}
answer_mapping preserves original question text for provider context

Troubleshooting MCP

MCP Package Not Installed

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

Fix: pip install mcp or install Promptheus with dev dependencies: pip install -e .[dev]

Missing Provider API Keys

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

Diagnosis: Use list_providers or validate_environment tools to check configuration status

Provider Misconfiguration

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

Fix: Set missing API keys in .env file or environment variables

Connection Test Failures

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

Fix: Verify API keys are valid and have necessary permissions

Full Documentation

Quick reference: promptheus --help

Comprehensive guides:

Development

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

See CLAUDE.md for detailed development guidance.

License

MIT License - see LICENSE for details

Contributing

Contributions welcome! Please see our development guide for contribution guidelines.

Questions? Open an issue | Live demo: promptheus web

Promptheus

Promptheus

Quick Start

Python library usage

What is Promptheus?

Supported Providers

Core Features

Configuration

Examples

MCP Server

What the MCP Server Does

Starting the MCP Server

Available MCP Tools

refine_prompt

tweak_prompt

list_models

list_providers

validate_environment

Prompt Refinement Workflow with Q&A

Step 1: Initial Refinement Request

Step 2: Handle Clarification Response

Step 3: Collect User Answers

Step 4: Final Refinement with Answers

AskUser Integration Contract

Troubleshooting MCP

Full Documentation

Development

License

Contributing

Promptheus

Quick Start

Python library usage

What is Promptheus?

Supported Providers

Core Features

Configuration

Examples

MCP Server

What the MCP Server Does

Starting the MCP Server

Available MCP Tools

refine_prompt

tweak_prompt

list_models

list_providers

validate_environment

Prompt Refinement Workflow with Q&A

Step 1: Initial Refinement Request

Step 2: Handle Clarification Response

Step 3: Collect User Answers

Step 4: Final Refinement with Answers

AskUser Integration Contract

Troubleshooting MCP

Full Documentation

Development

License

Contributing

`refine_prompt`

`tweak_prompt`

`list_models`

`list_providers`

`validate_environment`

`refine_prompt`

`tweak_prompt`

`list_models`

`list_providers`

`validate_environment`