Promptheus: Instructions file for Codex

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.