ProseHound

ProseHound is a command-line tool that finds review candidates in prose. It is for people and agents working with documentation, Markdown, release notes, UI copy, and other reader-facing text.

The default hedge check reports configured intensifiers such as very, really, and clearly. The opt-in clarity check uses a local or cloud model to review ambiguity and needless complexity for a stated audience. Findings and proposed replacements are review candidates; the tool does not edit files.

Requirements

• Rust 1.86 or newer

Run

Check one or more files:

cargo run -- README.md

Check text from standard input:

printf 'This is very useful.\n' | cargo run -- --stdin

Check all Git-tracked files selected by the default configuration:

cargo run -- --all

Use --format json for machine-readable output. List compiled checks with:

cargo run -- checks list

Evaluate a check against a curated dataset:

cargo run -- evaluate tests/datasets/hedge-v1 --check hedge

For CI, use --fail-on warning to return exit code 1 when a warning is found; the default threshold is error.

Configuration

ProseHound reads .prosehound.toml from the working directory when present. Defaults include Markdown, MDX, and text files; exclude vendor/ and target/; and enable the hedge check.

[checks.hedge]
phrases = ["almost", "very", "really"]

Contextual review

Configure a model endpoint that supports the chat-completions API and JSON object responses. Replace your-model-id with an installed or available model:

[checks.clarity]
enabled = true
endpoint_kind = "local"
base_url = "http://127.0.0.1:11434/v1"
model = "your-model-id"
audience = "Developers installing this project for the first time"
retention_note = "Local server; check its logging settings."
timeout_seconds = 30
max_segment_bytes = 8192
max_tokens = 2048
model_failure = "error"

For a cloud endpoint, set endpoint_kind = "cloud", use an HTTPS base_url, and supply a retention_note describing the provider's policy. If credentials are required, set api_key_env = "PROSE_HOUND_MODEL_KEY" and provide the key through that environment variable. URLs cannot contain credentials, query parameters, or fragments. HTTP is allowed only for local loopback endpoints. Requests do not follow redirects or use environment-configured proxies.

Run only clarity, or repeat --check to select both checks:

cargo run -- README.md --check clarity --format json
cargo run -- --changed --base main --check hedge --check clarity

Clarity sends one extracted prose segment per request, with the audience, document format, and sentence units. It excludes code and link destinations. Each candidate must quote a unique substring of a supplied sentence. Quotes and replacements cannot cross extraction boundaries. Overlapping candidates are rejected; competing proposals across checks are withheld.

JSON reports include effective configuration, SHA-256 fingerprints, endpoint and model metadata, request sizes, token usage when reported, timing, and failures. Credentials and raw request/response bodies are not recorded. Findings themselves contain the quoted prose and any proposed replacement.

Model failures return exit code 3 and remain visible in the report. Setting model_failure = "skip" lets an ordinary check run continue without failing for model errors. Evaluation always returns 3 and suppresses precision/recall when any review fails. Oversized segments fail explicitly; they are not silently truncated.

Evaluate checks

Evaluation uses the same check and validation pipeline as ordinary runs. It loads the working-directory configuration or an explicit --config file and runs only the requested check:

cargo run -- evaluate tests/datasets/hedge-v1 --check hedge --format json
cargo run -- evaluate tests/datasets/clarity-v1 --check clarity --config model.toml --format json

Each dataset contains dataset.json and one prose fixture. Expectations name a unique id, an exact anchor, an optional zero-based occurrence, and a label: actionable or exception. Anchors must be nonempty, nonoverlapping, and contained in extracted prose. Fixture paths must stay inside the dataset.

Findings are matched one-to-one in source order. Exact ranges win; otherwise, at least half the expectation's bytes must overlap. Greater overlap wins, with expectation ID as the tie-breaker. A matched exception counts as a false positive. Reports retain individual matches, unmatched findings, configuration, fixture fingerprints, and the complete run. Zero denominators are null.

The default hedge seed scores 4 true positives, 1 false positive, and no false negatives (precision 0.8, recall 1.0). The clarity corpus includes two problems and three legitimate exceptions. Tests replay a fixed response to verify scoring; those replay scores do not measure a live model's quality. Pin a model revision where the endpoint permits it and retain separate JSON reports from repeated evaluations to assess consistency.

Clarity currently has limited context at Markdown formatting boundaries and uses punctuation-based sentence units, which can split abbreviations. Source validation does not establish semantic faithfulness. Cost accounting, human proposal assessments, and larger corpora remain future evaluation work.

Development

cargo test

The project direction is described in the manifesto and the alpha plan.

License and reference material

The original contents of this repository are available under the MIT License.

The project links to, but does not redistribute, the SEC's A Plain English Handbook. The SEC's official edition states that the handbook is not copyrighted; the handbook remains an external reference rather than part of this license.