ndcorder/outputguard: Validate, repair, and retry LLM structured outputs. 13 repair strategies for common JSON malformations, JSON Schema validation, and retry-with-feedback prompts.

Validate, repair, and retry LLM structured outputs. 13 repair strategies for common JSON malformations, JSON Schema validation, and retry-with-feedback prompts. - ndcorder/outputguard

Summary

outputguard is a Python library that validates, repairs, and retries structured outputs from large language models. It applies fifteen repair strategies to common JSON, YAML, TOML, and Python-literal malformations before validating the result against a schema and optionally sending a correction prompt back to the model. The package is provider-agnostic and ships with a CLI for command-line workflows.

What it is useful for

outputguard addresses a recurring problem when building on top of LLMs: models frequently return broken structured output, wrapped in markdown code fences, with trailing commas, single quotes, Python-style booleans, truncated objects, or surrounding prose. Most teams end up writing their own parser-plus-regex cleanup, wiring in a separate JSON Schema validator, and writing a retry loop that re-prompts on errors. outputguard consolidates that step into one call. Beyond JSON it supports YAML, TOML, Python literals, an auto mode, and a forced-json-off mode for models not constrained to JSON. Because it operates on strings and schemas, it plugs into OpenAI, Anthropic, local models, or any client that returns text.

How engineers can use it

Install with pip install outputguard or uv add outputguard. The most common pattern is outputguard.validate_and_repair(text, schema), which returns a result exposing valid, data, repaired, strategies_applied, and errors. To wrap an LLM call with validation, repair, and retry in one call, use outputguard.guarded_generate(prompt, schema, generate=lambda p, ctx: llm.generate(p), max_retries=3); the async variant guarded_generate_async works the same way for async clients. When repair alone cannot fix the output, outputguard.retry_prompt(text, schema, errors) produces a correction prompt that names the missing fields and schema violations; pass include_message_history=False to omit the prior output from the prompt. For eval sets or log audits, use validate_batch and repair_batch, or run outputguard batch outputs.json -s schema.json --repair from the CLI. The CLI also exposes validate, repair, retry-prompt, and strategies, accepts - for stdin, and supports --input-format for non-JSON data. Strategy selection and repair depth are configurable through the OutputGuard class (for example, strategies=["strip_fences", "fix_commas"] for a strict mode).

Documented limitations to keep in mind: the RepairReport.confidence value is described as a heuristic and should be treated as guidance rather than a guarantee, and schema validation relies on jsonschema. The README points to troubleshooting and migration guides for edge cases not covered here.