Metadata-Version: 2.4
Name: structured-output-doctor
Version: 0.1.0
Summary: Local CLI and desktop checker for repairing structured LLM outputs against lightweight schemas
Author: Haider Sattar
License-Expression: MIT
Project-URL: Homepage, https://github.com/iwaheedsattar/structured-output-doctor
Project-URL: Repository, https://github.com/iwaheedsattar/structured-output-doctor
Project-URL: Issues, https://github.com/iwaheedsattar/structured-output-doctor/issues
Keywords: llm,json,schema,validation,structured-output,cli
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Text Processing :: General
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

![Terminal report screenshot](docs/terminal-report.svg)

# 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

```bash
pip install structured-output-doctor
```

For local development:

```bash
python3 -m pip install -e .
```

## Quick Start

Check a model output against a lightweight schema:

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

Write a Markdown handoff report:

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

Read output from stdin:

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

Open the desktop paste-and-check app:

```bash
structured-output-doctor-gui
```

## Schema Format

Use a compact `fields` array:

```json
{
  "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

```bash
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:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests
```

Build and check package artifacts:

```bash
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.
