Repository Guidelines

Repository Guidelines

Project Structure & Module Organization

Runtime code lives under src/promptheus/. main.py owns the CLI entry point, providers.py wraps the adapters for multiple LLM providers (Gemini, Claude, OpenAI, Groq, Qwen, GLM), config.py manages environment-driven settings, and history.py persists prompt sessions. Shared assets (e.g., models.json, logging_config.py, utils.py) sit alongside. Tests mirror this layout in tests/, while helper tools such as sample_prompts.txt remain at the repository root. Add new runtime modules inside src/promptheus/ and keep provider-specific helpers beside existing integrations to simplify discovery.

Build, Test, and Development Commands

Install dependencies in editable mode before contributing:

pip install -e .[dev]
pip install -r requirements.txt  # extras for env_validator

Run the CLI locally with either binary or module syntax:

promptheus "Draft an onboarding email"
python -m promptheus.main --skip-questions "Smoke test"

# Quiet mode for scripting (clean stdout/stderr separation)
promptheus "Generate a report" > output.txt  # Auto-quiet when piping
promptheus "Write code" | cat  # Auto-quiet when piping

# Different output formats
promptheus -o json "Create function" | jq .
promptheus -o plain "Write haiku"

Validate credentials before hitting remote APIs:

promptheus validate --providers google
promptheus validate --test-connection  # to test actual API connectivity

Coding Style & Naming Conventions

Target Python 3.8+ with four-space indentation, snake_case for functions/variables, and CapWords for classes. Mirror existing type hints (see main.py) and keep modules under ~300 lines by extracting helpers where needed. Format with black ., keep imports sorted, and align terminal output with the rich styles already used in the CLI panels/table helpers.

Testing Guidelines

Tests live in tests/ and follow the test_<module>.py naming pattern. Prefer fast, offline unit tests that stub provider calls rather than exercising live APIs. Run pytest -q before sending a PR, and supplement with a manual CLI smoke test (promptheus --skip-questions "Smoke test") when you touch interactive flows or history features.

Commit & Pull Request Guidelines

Use concise, imperative commit messages (e.g., Add OpenAI provider guard, Tighten question validation). PRs should summarize behavioral changes, reference related issues, list tests run, and include CLI transcripts or screenshots whenever user-facing output changes. Keep changes focused—split feature work and refactors into separate PRs for easier review.

Security & Configuration Tips

Store provider secrets in .env (bootstrap from .env.example) and never log raw tokens. Run promptheus validate after updating credentials to ensure required keys are present. Honor the default timeout settings in constants.py, and mask sensitive values when printing exceptions (use sanitize_error_message to stay consistent).

Supported Providers

Promptheus supports 6 major LLM providers:

• Google (formerly Gemini) - using GOOGLE_API_KEY
• Claude (Anthropic) - using ANTHROPIC_API_KEY
• OpenAI - using OPENAI_API_KEY
• Groq - using GROQ_API_KEY
• Qwen (Alibaba/DashScope) - using DASHSCOPE_API_KEY
• GLM (Zhipu) - using ZHIPUAI_API_KEY

Model information is dynamically fetched from the models.dev API and cached locally for 24 hours. Cache location: ~/.promptheus/models_cache.json

Each provider has its own configuration in models.json and respective adapter in providers.py.

History Management

The system automatically tracks all prompt refinements in a local history file. Users can access:

• CLI command: promptheus history
• Interactive commands: /history, /load <n>, /clear-history
• History includes timestamps, task types, and both original and refined prompts.

Quiet Mode & Piping

Promptheus supports clean stdout/stderr separation for scripting and piping:

• Auto-quiet mode: Automatically enabled when stdout is not a TTY (e.g., when piping)
• Prompt processing unchanged: Questions are still asked based on LLM's decision, regardless of output mode
• Output formats: -o/--output-format supports plain (default) and json
• Behavior: In quiet mode, all UI (status, warnings, spinners, questions) goes to stderr, only the refined prompt goes to stdout
• Limitations: Interactive tweaks and clipboard (--copy) are disabled in quiet mode

MCP Server Integration

Promptheus includes a Model Context Protocol (MCP) server for integration with MCP-compatible clients and AI toolchains.

Starting the MCP Server

# Start MCP server
promptheus mcp

# Or direct Python execution
python -m promptheus.mcp_server

Available MCP Tools

• refine_prompt: Intelligent prompt refinement with Q&A workflow
• tweak_prompt: Surgical prompt modifications
• list_models: Provider model discovery
• list_providers: Configuration status checking
• validate_environment: Environment validation with connectivity testing

MCP Integration Workflow

1. Initial Request: Call refine_prompt with basic prompt
2. Clarification Handling: Process clarification_needed responses with AskUserQuestion
3. Final Refinement: Submit answers for optimized prompt generation
4. Tool Integration: Use refined prompts with client's native LLM capabilities

MCP Development Guidelines

• Tools return consistent response formats (success/clarification/error)
• Support both interactive and structured AskUserQuestion modes
• Maintain comprehensive error handling with sanitized messages
• Document all tools with JSON examples and usage patterns

For detailed MCP documentation, see the MCP Server section in README.md.