Promptheus Development Guide

Promptheus Development Guide

This document outlines development environment setup, testing procedures, code standards, and architectural patterns for Promptheus contributors.

Development Environment Setup

Installation from Source

# Clone repository
git clone https://github.com/abhichandra21/Promptheus.git
cd Promptheus

# Install in editable mode with development dependencies
pip install -e ".[dev]"

# Configure environment
cp .env.example .env
# Add provider API keys to .env file

Verification

# Verify installation
promptheus --version
python -m promptheus.main --version

Testing Procedures

Manual Testing

Standard CLI Execution:

promptheus "Draft a release note"

Module Entry Point:

python -m promptheus.main --skip-questions "Smoke test"

Provider Validation:

promptheus validate --providers google
promptheus validate --test-connection

Automated Testing

Execute Test Suite:

pytest -q

Test Development Guidelines:

• Add new tests to tests/ directory following test_<module>.py naming convention
• Implement lightweight unit tests with mocked providers
• Ensure tests execute without network dependencies
• Maintain test coverage for critical paths

Code Standards

Python Conventions

Language Features:

• Python 3.10+ syntax and features
• Type hints for function signatures
• 4-space indentation
• snake_case naming convention for functions and variables
• PascalCase for class names

Module Organization:

• Maximum module length: 300 lines
• Extract utility functions to src/promptheus/ modules
• Maintain clear separation of concerns

Code Formatting:

# Format code before committing
black .

# Verify import organization
# Imports should be grouped: standard library, third-party, local

Dependencies

Core Dependencies:

• fastapi: Web framework for the UI server
• uvicorn: ASGI server for running the web application
• rich: Terminal rendering and formatting
• questionary: Interactive CLI prompts
• pyperclip: Cross-platform clipboard operations
• prompt-toolkit: Advanced terminal input handling
• python-dotenv: Environment configuration management
• filelock: File locking utilities
• aiohttp: Async HTTP client for models.dev API

Provider SDKs:

• Google Gemini SDK (google-genai or google-generativeai)
• Anthropic SDK (anthropic)
• OpenAI SDK (openai)
• Groq SDK (groq)
• Alibaba Cloud DashScope SDK (dashscope)
• Zhipu AI SDK (zhipu)

Model Discovery:

• models_dev_service.py: Service for fetching and caching model information from models.dev API
• Cache location: ~/.promptheus/models_cache.json
• Cache duration: 24 hours (86400 seconds)

Python Version Compatibility

Python 3.14 Support:

• Gemini provider: Full support via google-genai SDK
• Other providers: Compatibility varies by SDK version

Development Recommendations:

• Test with target Python version before committing
• Use virtual environments for version-specific testing
• Document provider-specific compatibility constraints

Architectural Overview

Module Structure

Command-Line Interface Layer:

• src/promptheus/cli.py: Argument parsing and subcommand dispatch

Core Processing Logic:

• src/promptheus/main.py: Primary prompt processing orchestration

Interactive Mode (REPL):

• src/promptheus/repl/session.py: Main REPL loop and session state management
• src/promptheus/repl/commands.py: Slash command implementation (/set, /toggle, etc.)
• src/promptheus/repl/completer.py: Tab completion for slash commands
• src/promptheus/repl/history_view.py: History display functionality

Provider Integration:

• src/promptheus/providers.py: LLM provider implementations and abstractions
• src/promptheus/providers.json: Provider configurations and model definitions

Configuration and Utilities:

• src/promptheus/config.py: Environment configuration and provider detection
• src/promptheus/utils.py: Shared utility functions
• src/promptheus/history.py: Session history persistence
• src/promptheus/logging_config.py: Logging configuration

Contribution Guidelines

Code Changes

Scope:

1. Maintain focused changes (single feature, refactor, or documentation update per pull request)
2. Avoid mixing unrelated changes in a single commit

Commit Messages:

• Use imperative mood: "Add static mode docs" not "Added static mode docs"
• Keep first line under 72 characters
• Provide detailed explanation in commit body if necessary

Pull Request Requirements:

1. Include behavior description
2. Document testing performed
3. Update relevant documentation
4. Add tests for new functionality

Security Considerations

API Key Handling:

• Never log raw API keys
• Use masked output for display (as implemented in validator)
• Sanitize error messages containing credentials

Adding New Providers

OpenAI-Compatible Providers: If the provider exposes an OpenAI-compatible endpoint, extend the OpenAICompatibleProvider base class in src/promptheus/providers.py (reference implementations: OpenAI, Groq, Qwen, GLM).

Provider-Specific Implementations: For providers requiring custom integration (e.g., Gemini, Anthropic):

1. Implement provider-specific adapter in providers.py
2. Add configuration to providers.json
3. Update environment detection in config.py
4. Update validation utilities
5. Document provider setup in README.md

MCP Server Development

MCP Server Architecture

The MCP server implementation (src/promptheus/mcp_server.py) provides:

Core Components:

• FastMCP Integration: Uses FastMCP framework for tool exposure
• Tool Registry: Five exposed tools (refine_prompt, tweak_prompt, list_models, list_providers, validate_environment)
• AskUserQuestion Integration: Supports both interactive and structured modes
• Error Handling: Consistent error response format across all tools

Key Design Patterns:

# Tool registration pattern
@mcp.tool()
def refine_prompt(prompt: str, answers: Optional[Dict[str, str]] = None, ...) -> RefineResult:
    # Tool implementation
    
# Response type pattern
Union[RefinedResponse, ClarificationResponse, ErrorResponse]

MCP Development Guidelines

Adding New MCP Tools:

1. Implement tool function with proper type hints
2. Use consistent response format (success/error/clarification)
3. Add comprehensive docstring with examples
4. Test with both interactive and structured modes
5. Update documentation with tool usage examples

AskUserQuestion Integration:

# Interactive mode (when AskUserQuestion available)
interactive_answers = _try_interactive_questions(questions)
if interactive_answers:
    return _build_refined_response(refined_prompt)

# Structured mode (fallback)
return _format_clarification_response(questions, task_type, mapping)

Error Handling Pattern:

return {
    "type": "error",
    "error_type": type(e).__name__,
    "message": sanitize_error_message(str(e)),
}

Testing MCP Server

Unit Testing:

# Test individual MCP tools
pytest tests/test_mcp_server.py -v

# Test with mock providers
pytest tests/test_mcp_server.py::test_refine_prompt_mock -v

Integration Testing:

# Test MCP server startup
python -m promptheus.mcp_server

# Test with actual MCP client
# Use MCP-compatible client to call tools
# Verify response formats and error handling

Manual Testing Workflow:

# 1. Start MCP server
promptheus mcp

# 2. Test basic refinement (should work without questions)
promptheus mcp  # Then test refine_prompt with "Explain recursion"

# 3. Test clarification workflow
# Use prompt that triggers questions: "Write a blog post"

# 4. Test error handling
# Try with invalid provider or missing API keys

MCP Client Integration Testing

Test AskUserQuestion Flow:

# Test structured clarification response
# Verify questions_for_ask_user_question format
# Test answer mapping and second refinement call

# Expected workflow:
# 1. Call refine_prompt("Write something")
# 2. Receive clarification_needed response
# 3. Use AskUserQuestion with provided questions
# 4. Call refine_prompt again with answers
# 5. Receive refined prompt

MCP Documentation Requirements

When Adding MCP Features:

1. Update tool docstrings with usage examples
2. Add examples to README.md MCP section
3. Update troubleshooting.md with new error cases
4. Add integration examples to usage.md
5. Update architecture documentation in CLAUDE.md

Documentation Standards:

• Include JSON request/response examples
• Document error conditions and handling
• Provide workflow diagrams for complex interactions
• Include troubleshooting steps for common issues

Communication Channels

Issue Reporting:

• Open issues at https://github.com/abhichandra21/Promptheus/issues
• Include reproduction steps
• Provide environment details (Python version, provider, OS)

Pull Request Feedback:

• Submit draft PRs for early feedback on significant changes
• Request review before marking PR as ready
• Respond to review comments promptly

Release Process

1. Run the full test suite (pytest -q) and a manual CLI smoke test (promptheus --skip-questions "Smoke test").
2. Update pyproject.toml and src/promptheus/constants.py with the new semantic version.
3. Refresh the Release Notes section in README.md with a short bullet list of key changes.
4. Commit the changes, tag the release (for example git tag v0.2.0 && git push origin v0.2.0).
5. Build artifacts locally using poetry build and inspect the wheel/sdist outputs.
6. Publish to PyPI (or TestPyPI first) with poetry publish --build after exporting the appropriate credentials.