structured-output-doctor 0.1.0

Local CLI and desktop checker for repairing structured LLM outputs against lightweight schemas

structured-output-doctor

structured-output-doctor is a local CLI and desktop checker for pasted model outputs that are supposed to match a JSON contract.

It helps catch:

• invalid JSON hidden inside Markdown fences or surrounding prose
• missing required fields
• type drift such as "yes" where a boolean is expected
• enum values outside an allowed set
• mixed array item types
• unexpected top-level fields

The tool has no runtime dependencies.

Install

pip install structured-output-doctor

For local development:

python3 -m pip install -e .

Quick Start

Check a model output against a lightweight schema:

structured-output-doctor examples/model-output.txt --schema examples/support-schema.json

Write a Markdown handoff report:

structured-output-doctor examples/model-output.txt \
  --schema examples/support-schema.json \
  --format markdown \
  --output-file structured-output-report.md

Read output from stdin:

cat response.txt | structured-output-doctor --schema schema.json --fail-under 80

Open the desktop paste-and-check app:

structured-output-doctor-gui

Schema Format

Use a compact fields array:

{
  "additional_fields": "warn",
  "fields": [
    { "path": "summary", "type": "string", "non_empty": true },
    { "path": "priority", "type": "string", "enum": ["low", "medium", "high"] },
    { "path": "actions", "type": "array", "items": "string" },
    { "path": "needs_human_review", "type": "boolean" }
  ]
}

Supported types are any, array, boolean, float, integer, null, number, object, and string. Nested paths use dotted names and array indexes, such as choices[0].message.content.

Basic JSON Schema-style objects with properties and required are also accepted for simple field checks.

Report Formats

structured-output-doctor response.txt -s schema.json --format text
structured-output-doctor response.txt -s schema.json --format markdown
structured-output-doctor response.txt -s schema.json --format json
structured-output-doctor response.txt -s schema.json --format html --output-file report.html

Exit codes:

• 0: parsed and passed the configured score threshold
• 1: validation failed or the score is below --fail-under
• 2: command usage or file loading failed

Development

Run tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Build and check package artifacts:

python3 -m build --no-isolation
python3 -m twine check dist/*

Contributing

Issues and pull requests are welcome. Keep changes focused, include tests for behavior changes, and update this README when command behavior changes.