{
  "markdown": "# Promptheus\n\n**Refine and optimize prompts for LLMs**\n\n<!-- mcp-name: io.github.abhichandra21/promptheus -->\n\n[![Python Version](https://img.shields.io/badge/python-3.10+-blue)](https://www.python.org/downloads/) [![PyPI Version](https://img.shields.io/pypi/v/promptheus)](https://pypi.org/project/promptheus/) [![Release Version](https://img.shields.io/badge/release-v0.3.2-brightgreen)](CHANGELOG.md) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![GitHub Stars](https://img.shields.io/github/stars/abhichandra21/Promptheus?style=social)](https://github.com/abhichandra21/Promptheus)\n\n[![Deploy GitHub Pages](https://github.com/abhichandra21/Promptheus/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/abhichandra21/Promptheus/actions/workflows/deploy-pages.yml) [![Docker Build & Test](https://github.com/abhichandra21/Promptheus/actions/workflows/docker-test.yml/badge.svg)](https://github.com/abhichandra21/Promptheus/actions/workflows/docker-test.yml) [![Publish Python Package](https://github.com/abhichandra21/Promptheus/actions/workflows/publish.yml/badge.svg)](https://github.com/abhichandra21/Promptheus/actions/workflows/publish.yml)\n\n## Quick Start\n\n```bash\npip install promptheus\n```\n\n```bash\n# Interactive session\npromptheus\n\n# Single prompt\npromptheus \"Write a technical blog post\"\n\n# Skip clarifying questions\npromptheus -s \"Explain Kubernetes\"\n\n# Use web UI\npromptheus web\n```\n\n### Python library usage\n\n```python\nfrom promptheus import refine_prompt\n\nresult = refine_prompt(\"Write a technical blog post\", skip_questions=True)\nprint(result[\"refined_prompt\"])\n```\n\nIf you're already in an async application (e.g., FastAPI), call `refine_prompt_async` instead of the sync helper.\n\n## What is Promptheus?\n\nPromptheus analyzes your prompts and refines them with:\n- **Adaptive questioning**: Smart detection of what information you need to provide\n- **Multi-provider support**: Works with Google, OpenAI, Anthropic, Groq, Qwen, and more\n- **Interactive refinement**: Iteratively improve outputs through natural conversation\n- **Session history**: Automatically track and reuse past prompts\n- **CLI and Web UI**: Use from terminal or browser\n\n## Supported Providers\n\n| Provider | Models | Setup |\n|----------|--------|-------|\n| **Google Gemini** | gemini-2.0-flash, gemini-1.5-pro | [API Key](https://aistudio.google.com) |\n| **Anthropic Claude** | claude-3-5-sonnet, claude-3-opus | [Console](https://console.anthropic.com) |\n| **OpenAI** | gpt-4o, gpt-4-turbo | [API Key](https://platform.openai.com/api-keys) |\n| **Groq** | llama-3.3-70b, mixtral-8x7b | [Console](https://console.groq.com) |\n| **Alibaba Qwen** | qwen-max, qwen-plus | [DashScope](https://dashscope.aliyun.com) |\n| **Zhipu GLM** | glm-4-plus, glm-4-air | [Console](https://open.bigmodel.cn) |\n| **OpenRouter** | openrouter/auto (auto-routing) | [Dashboard](https://openrouter.ai) |\n\nOpenRouter integration in Promptheus is optimized around the `openrouter/auto` routing model:\n- Model listing is intentionally minimal: Promptheus does not expose your full OpenRouter account catalog.\n- You can still specify a concrete model manually with `OPENROUTER_MODEL` or `--model` if your key has access.\n\n## Core Features\n\n**🧠 Adaptive Task Detection**\nAutomatically detects whether your task needs refinement or direct optimization\n\n**⚡ Interactive Refinement**\nAsk targeted questions to elicit requirements and improve outputs\n\n**📝 Pipeline Integration**\nWorks seamlessly in Unix pipelines and shell scripts\n\n**🔄 Session Management**\nTrack, load, and reuse past prompts automatically\n\n**📊 Telemetry & Analytics**\nAnonymous usage and performance metrics tracking for insights (local storage only, can be disabled)\n\n**🌐 Web Interface**\nBeautiful UI for interactive prompt refinement and history management\n\n## Configuration\n\nCreate a `.env` file with at least one provider API key:\n\n```bash\nGOOGLE_API_KEY=your_key_here\nANTHROPIC_API_KEY=your_key_here\nOPENAI_API_KEY=your_key_here\n```\n\nOr run the interactive setup:\n\n```bash\npromptheus auth\n```\n\n## Examples\n\n**Content Generation**\n```bash\npromptheus \"Write a blog post about async programming\"\n# System asks: audience, tone, length, key topics\n# Generates refined prompt with all specifications\n```\n\n**Code Analysis**\n```bash\npromptheus -s \"Review this function for security issues\"\n# Skips questions, applies direct enhancement\n```\n\n**Interactive Session**\n```bash\npromptheus\n/set provider anthropic\n/set model claude-3-5-sonnet\n# Process multiple prompts, switch providers/models with /commands\n```\n\n**Pipeline Integration**\n```bash\necho \"Create a REST API schema\" | promptheus | jq '.refined_prompt'\ncat prompts.txt | while read line; do promptheus \"$line\"; done\n```\n\n**Testing & Examples**: See [sample_prompts.md](sample_prompts.md) for test prompts demonstrating adaptive task detection (analysis vs generation).\n\n**Telemetry & Analytics**\n```bash\n# View telemetry summary (anonymous metrics about usage and performance)\npromptheus telemetry summary\n\n# Disable telemetry if desired\nexport PROMPTHEUS_TELEMETRY_ENABLED=0\n\n# Customize history storage location\nexport PROMPTHEUS_HISTORY_DIR=~/.custom_promptheus\n```\n\n## MCP Server\n\nPromptheus includes a **Model Context Protocol (MCP) server** that exposes prompt refinement capabilities as standardized tools for integration with MCP-compatible clients.\n\n### What the MCP Server Does\n\nThe Promptheus MCP server provides:\n- **Prompt refinement with Q&A**: Intelligent prompt optimization through adaptive questioning\n- **Prompt tweaking**: Surgical modifications to existing prompts  \n- **Model/provider inspection**: Discovery and validation of available AI providers\n- **Environment validation**: Configuration checking and connectivity testing\n\n### Starting the MCP Server\n\n```bash\n# Start the MCP server\npromptheus mcp\n\n# Or run directly with Python\npython -m promptheus.mcp_server\n```\n\n**Prerequisites:**\n- MCP package installed: `pip install mcp` (included in requirements.txt)\n- At least one provider API key configured (see [Configuration](#configuration))\n\n### Available MCP Tools\n\n#### `refine_prompt`\nIntelligent prompt refinement with optional clarification questions.\n\n**Inputs:**\n- `prompt` (required): The initial prompt to refine\n- `answers` (optional): Dictionary mapping question IDs to answers `{q0: \"answer\", q1: \"answer\"}`\n- `answer_mapping` (optional): Maps question IDs to original question text\n- `provider` (optional): Override provider (e.g., \"google\", \"openai\")\n- `model` (optional): Override model name\n\n**Response Types:**\n- `{\"type\": \"refined\", \"prompt\": \"...\", \"next_action\": \"...\"}`: Success with refined prompt\n- `{\"type\": \"clarification_needed\", \"questions_for_ask_user_question\": [...], \"answer_mapping\": {...}}`: Questions needed\n- `{\"type\": \"error\", \"error_type\": \"...\", \"message\": \"...\"}`: Error occurred\n\n#### `tweak_prompt`\nApply targeted modifications to existing prompts.\n\n**Inputs:**\n- `prompt` (required): Current prompt to modify\n- `modification` (required): Description of changes (e.g., \"make it shorter\")\n- `provider`, `model` (optional): Provider/model overrides\n\n**Returns:**\n- `{\"type\": \"refined\", \"prompt\": \"...\"}`: Modified prompt\n\n#### `list_models`\nDiscover available models from configured providers.\n\n**Inputs:**\n- `providers` (optional): List of provider names to query\n- `limit` (optional): Max models per provider (default: 20)\n- `include_nontext` (optional): Include vision/embedding models\n\n**Returns:**\n- `{\"type\": \"success\", \"providers\": {\"google\": {\"available\": true, \"models\": [...]}}}`\n\n#### `list_providers`\nCheck provider configuration status.\n\n**Returns:**\n- `{\"type\": \"success\", \"providers\": {\"google\": {\"configured\": true, \"model\": \"...\"}}}`\n\n#### `validate_environment`\nTest environment configuration and API connectivity.\n\n**Inputs:**\n- `providers` (optional): Specific providers to validate\n- `test_connection` (optional): Test actual API connectivity\n\n**Returns:**\n- `{\"type\": \"success\", \"validation\": {\"google\": {\"configured\": true, \"connection_test\": \"passed\"}}}`\n\n### Prompt Refinement Workflow with Q&A\n\nThe MCP server supports a structured clarification workflow for optimal prompt refinement:\n\n#### Step 1: Initial Refinement Request\n```json\n{\n  \"tool\": \"refine_prompt\",\n  \"arguments\": {\n    \"prompt\": \"Write a blog post about machine learning\"\n  }\n}\n```\n\n#### Step 2: Handle Clarification Response\n```json\n{\n  \"type\": \"clarification_needed\",\n  \"task_type\": \"generation\",\n  \"message\": \"To refine this prompt effectively, I need to ask...\",\n  \"questions_for_ask_user_question\": [\n    {\n      \"question\": \"Who is your target audience?\",\n      \"header\": \"Q1\",\n      \"multiSelect\": false,\n      \"options\": [\n        {\"label\": \"Technical professionals\", \"description\": \"Technical professionals\"},\n        {\"label\": \"Business executives\", \"description\": \"Business executives\"}\n      ]\n    }\n  ],\n  \"answer_mapping\": {\n    \"q0\": \"Who is your target audience?\"\n  }\n}\n```\n\n#### Step 3: Collect User Answers\nUse your MCP client's `AskUserQuestion` tool with the provided questions, then map answers to question IDs.\n\n#### Step 4: Final Refinement with Answers\n```json\n{\n  \"tool\": \"refine_prompt\", \n  \"arguments\": {\n    \"prompt\": \"Write a blog post about machine learning\",\n    \"answers\": {\"q0\": \"Technical professionals\"},\n    \"answer_mapping\": {\"q0\": \"Who is your target audience?\"}\n  }\n}\n```\n\n**Response:**\n```json\n{\n  \"type\": \"refined\",\n  \"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...\",\n  \"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...\"\n}\n```\n\n### AskUser Integration Contract\n\nThe MCP server operates in two modes:\n\n**Interactive Mode** (when AskUserQuestion is available):\n- Automatically asks clarification questions via injected AskUserQuestion function\n- Returns refined prompt immediately after collecting answers\n- Seamless user experience within supported clients\n\n**Structured Mode** (fallback for all clients):\n- Returns `clarification_needed` response with formatted questions\n- Client responsible for calling AskUserQuestion tool\n- Answers mapped back via `answer_mapping` dictionary\n\n**Question Format:**\nEach question in `questions_for_ask_user_question` includes:\n- `question`: The question text to display\n- `header`: Short identifier (Q1, Q2, etc.)\n- `multiSelect`: Boolean for multi-select options\n- `options`: Array of `{label, description}` for radio/checkbox questions\n\n**Answer Mapping:**\n- Question IDs follow pattern: `q0`, `q1`, `q2`, etc.\n- Answers dictionary uses these IDs as keys: `{\"q0\": \"answer\", \"q1\": \"answer\"}`\n- `answer_mapping` preserves original question text for provider context\n\n### Troubleshooting MCP\n\n**MCP Package Not Installed**\n```\nError: The 'mcp' package is not installed. Please install it with 'pip install mcp'.\n```\n**Fix:** `pip install mcp` or install Promptheus with dev dependencies: `pip install -e .[dev]`\n\n**Missing Provider API Keys**\n```json\n{\n  \"type\": \"error\",\n  \"error_type\": \"ConfigurationError\", \n  \"message\": \"No provider configured. Please set API keys in environment.\"\n}\n```\n**Diagnosis:** Use `list_providers` or `validate_environment` tools to check configuration status\n\n**Provider Misconfiguration**\n```json\n{\n  \"type\": \"success\",\n  \"providers\": {\n    \"google\": {\"configured\": false, \"error\": \"GOOGLE_API_KEY not found\"},\n    \"openai\": {\"configured\": true, \"model\": \"gpt-4o\"}\n  }\n}\n```\n**Fix:** Set missing API keys in `.env` file or environment variables\n\n**Connection Test Failures**\n```json\n{\n  \"type\": \"success\", \n  \"validation\": {\n    \"google\": {\n      \"configured\": true,\n      \"connection_test\": \"failed: Authentication error\"\n    }\n  }\n}\n```\n**Fix:** Verify API keys are valid and have necessary permissions\n\n## Full Documentation\n\n**Quick reference**: `promptheus --help`\n\n**Comprehensive guides**:\n- 📖 [Installation & Setup](docs/documentation.html#installation)\n- 🚀 [Usage Guide](docs/documentation.html#quick-start)\n- 🔧 [Configuration](docs/documentation.html#configuration)\n- ⌨️ [CLI Reference](docs/documentation.html#cli-basics)\n- 🌐 [Web UI Guide](docs/documentation.html#web-overview)\n- 🔌 [Provider Setup](docs/documentation.html#providers)\n\n## Development\n\n```bash\ngit clone https://github.com/abhichandra21/Promptheus.git\ncd Promptheus\npip install -e \".[dev]\"\npytest -q\n```\n\nSee [CLAUDE.md](CLAUDE.md) for detailed development guidance.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## Contributing\n\nContributions welcome! Please see our [development guide](docs/documentation.html) for contribution guidelines.\n\n---\n\n**Questions?** [Open an issue](https://github.com/abhichandra21/Promptheus/issues) | **Live demo**: `promptheus web`\n",
  "bytes": 12944,
  "sha": "3f10330e1c970fefc05dec9839efb79084e80c97d286781359aee9b76e405f7a",
  "repo_slug": "abhichandra21/promptheus",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_abhichandra21_promptheus_f2f0d422/readme"
}