Promptheus Project Context

Promptheus Project Context

This document provides a comprehensive overview of the Promptheus project, its architecture, and development conventions to be used as instructional context.

1. Project Overview

Promptheus is a sophisticated, AI-powered command-line interface (CLI) tool written in Python. Its primary purpose is to help users craft and refine prompts. The tool takes a user's initial prompt and, through a series of AI-driven steps, outputs a better, more effective prompt for the user to then take and use with any Large Language Model (LLM).

Core Features:

• Multi-Provider Support: It uses LLM backends (Google, Anthropic Claude, OpenAI, Groq, Qwen, GLM) for its internal refinement process.
• Adaptive Interaction: The tool intelligently detects the user's task type:
  • Generation Tasks: It offers to ask clarifying questions to add detail.
  • Analysis Tasks: It performs an automatic, non-interactive "light refinement" to improve the prompt's clarity.
• Iterative Refinement: Users can "tweak" a generated prompt with natural language commands in an interactive loop.
• Rich Interactive UI: The interface is built with rich and questionary, providing a polished and user-friendly experience.
• Flexible Configuration: Configuration is handled via a clear hierarchy: CLI arguments (--provider), environment variables (PROMPTHEUS_PROVIDER), and .env files.
• Prompt History: All refined prompts are automatically saved to a history file for later reference and reuse.
• Subcommand Interface: Provides dedicated subcommands for utility functions like list-models, validate, and history for a clean and modern CLI experience.
• Dynamic Model Discovery: Model information is dynamically fetched from the models.dev API and cached locally for 24 hours.

Architecture:

The project follows a modular and modern Python architecture:

• src/promptheus/main.py: The main application entry point. It handles parsing command-line arguments, orchestrates the refinement workflow, and manages the user interface.
• src/promptheus/cli.py: Defines the entire command-line interface, including all subcommands and their arguments, using Python's argparse module.
• src/promptheus/commands.py: Implements the logic for the utility subcommands (list-models, validate, template, history).
• src/promptheus/config.py: A dedicated configuration manager that detects and validates API keys and settings from environment variables and .env files. It uses providers.json for provider-specific metadata.
• src/promptheus/providers.py: The core abstraction layer. It defines an LLMProvider abstract base class and concrete implementations (GeminiProvider, AnthropicProvider, OpenAICompatibleProvider, etc.).
• src/promptheus/prompts.py: Stores the system instruction templates that guide the internal LLM calls for question generation, refinement, and tweaking.
• src/promptheus/history.py: Manages persistent storage of prompt history with timestamp tracking.

2. Building and Running

The project uses standard Python packaging tools (setuptools, pyproject.toml).

Installation

To set up the project for development, clone the repository and install it in editable mode.

# Install dependencies and the tool in editable mode
pip install -e .

Configuration

The application requires at least one API key for an LLM provider to power its internal refinement features.

1. Copy the example .env file: cp .env.example .env
2. Edit the .env file to add your API key (e.g., GOOGLE_API_KEY=..., ANTHROPIC_API_KEY=..., etc.).

Running the Application

The tool is installed as a command-line script named promptheus. Its function is to output a refined prompt.

• Interactive Mode (REPL):

  promptheus
  

• Single-Shot Mode:

  promptheus "Your initial prompt goes here"
  

• Utility Subcommands:

  promptheus list-models
  promptheus validate --test-connection
  promptheus history
  

• Running via Python module (for development):

  python -m promptheus.main "Your initial prompt goes here"
  

3. Development Conventions

• Code Style: The codebase uses modern Python (3.8+) with type hints, f-strings, and dataclasses.
• Dependencies: Project dependencies are managed in pyproject.toml.
• Provider Abstraction: All provider-specific logic is encapsulated within classes that inherit from LLMProvider.
• UI and Logic Separation: Core logic does not print to the console. It returns data or uses a MessageSink callable that the UI layer in main.py implements.
• Logging: Use the standard logging module for application logs. Do not use print() for logging.
• CLI Design: The CLI is built around a main entry point for prompting and a set of subcommands for utility functions. Global options like --verbose are available for all commands.
• Workflow for Analysis vs. Generation Tasks:
  • Default (Analysis): The tool performs a non-interactive "light refinement" using the light_refine provider method.
  • Default (Generation): The tool offers to ask clarifying questions.
  • --skip-questions: This flag forces the non-interactive "light refinement" workflow for any task type.
  • --refine: This flag forces the full, interactive Q&A workflow for any task type. These two flags are mutually exclusive.
• Testing: The project includes an automated testing suite using pytest. Run tests with pytest -q before submitting changes.