Metadata-Version: 2.4
Name: prompthealth
Version: 0.1.0a1
Summary: A health checker for LLM prompts and conversations.
License-Expression: MIT
Keywords: health,llm,prompts,quality
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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.

```python
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`](/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`](/docs/axes.md) — Definitions, scoring logic, and calibration notes for each axis. Includes the labeled prompt dataset used for threshold tuning.
- [`/docs/rules.md`](/docs/rules.md) — Full catalog of rule-based heuristics: pattern matchers, keyword lists, scoring functions, and edge cases per axis.
- [`/docs/api-layer.md`](/docs/api-layer.md) — Prompt templates sent to the LLM for semantic scoring, response parsing, fallback behavior when API is unavailable.
- [`/docs/extending.md`](/docs/extending.md) — How to add new axes, new rules, or new checker types (response checker, conversation checker) against the base interface.

## Install

```bash
pip install prompthealth
```