prompthealth 0.1.0a1

A health checker for LLM prompts and conversations.

prompthealth

A health checker for LLM prompts and conversations. Catches underspecified, ambiguous, and misaligned prompts before they hit the model. Monitors conversation health as context accumulates.

prompthealth scores prompts across four axes (constraint density, solution space width, intent clarity, context sufficiency), generates actionable rewrite suggestions, recommends thinking effort levels, and predicts response quality. Works offline with rule-based heuristics. Optionally connects to an LLM API for semantic analysis.

from prompthealth import Session

s = Session(api_key="sk-...", provider="anthropic")
s.add_context("FastAPI backend, PostgreSQL, deployed on AWS ECS")

result = s.check("What's the best caching strategy?")
# result.health: 0.5
# result.axes.constraint_density: 0.6
# result.axes.solution_space: 0.3
# result.axes.intent_clarity: 0.4
# result.axes.context_sufficiency: 0.7
# result.suggestions: ["Specify what you're caching (responses, DB queries, sessions)", ...]
# result.thinking_effort: "high"

Phases

1. Core health engine. Rule-based heuristics for constraint density, intent clarity, structural analysis. Session object for context accumulation. Pydantic result models. Works fully offline.
2. Semantic analysis. API-backed scoring for solution space width and context sufficiency. LLM-generated suggestions. Requires user-provided API key.
3. Thinking effort and response prediction. Classifies prompt complexity to recommend reasoning depth. Predicts whether the prompt will produce a useful response.
4. Conversation health. Track health over a full conversation. Detect context drift, prompt degradation, and model repetition across turns.
5. Claude Code plugin. Skill or hook integration for pre-submission health checks inside Claude Code.

Docs

• /docs/architecture.md — Module dependency graph, rule engine vs semantic layer split, Session lifecycle, data flow from prompt input to HealthResult output.
• /docs/axes.md — Definitions, scoring logic, and calibration notes for each axis. Includes the labeled prompt dataset used for threshold tuning.
• /docs/rules.md — Full catalog of rule-based heuristics: pattern matchers, keyword lists, scoring functions, and edge cases per axis.
• /docs/api-layer.md — Prompt templates sent to the LLM for semantic scoring, response parsing, fallback behavior when API is unavailable.
• /docs/extending.md — How to add new axes, new rules, or new checker types (response checker, conversation checker) against the base interface.

Install

pip install prompthealth