ZerdaZerda

output_parser

On this page

A production-grade output parsing, validation, fault-tolerance, and retry engine for LLM/RAG/agent pipelines.

output_parser turns messy, unpredictable raw text coming out of a language model into structured, validated, optionally typed Python data — without you having to hand-write regexes or brittle json.loads() calls for every prompt.

It ships two complementary layers that can be used independently or together:

  1. The single-format parser toolkit — small, focused parser classes (JSONOutputParser, YAMLOutputParser, CSVOutputParser, ListOutputParser, StructuredOutputParser, PydanticOutputParser) built on a shared BaseOutputParser interface. You pick the parser for the format you expect.
  2. The orchestration engine (OutputParser in parser.py) — a full pipeline that automatically detects the format of unknown text, parses it, repairs it if broken, optionally retries against a live LLM with escalating prompts, validates the result (schema, business rules, safety), and returns everything as a ParseResult with a complete ParseTrace audit log.

Why this exists

LLMs are asked to "return JSON" and instead return JSON wrapped in prose, wrapped in a code fence, with a trailing comma, or as YAML, or as a numbered list. Traditional json.loads(response) breaks immediately. output_parser is built around the assumption that malformed output is the normal case, not the exception, and gives you a layered strategy to recover a usable answer anyway.

Module map

ModuleResponsibility
parser.pyMain orchestrator (OutputParser) and the detect → parse → fix → retry → validate pipeline; also holds the per-format parse functions and the create_*_parser factories.
schema.pyAll enums (OutputFormat, ParseMode, ValidationStatus, FixStrategy), dataclasses (ParseResult, ParseTrace, ValidationResult, FieldSchema), and built-in Pydantic schemas (AnswerSchema, ToolCallSchema, RetrievalResultSchema, RankedAnswersSchema).
format_detector.pyFormatDetector — multi-signal heuristic scoring that guesses the format of raw text (JSON, YAML, CSV, Markdown table, lists, XML, tool call, key-value, plain text).
validator.pyOutputValidator — four-layer validation: field completeness/typing, custom business rules, safety checks (hallucination markers, data leakage, prompt injection), Pydantic validation.
fixer.pyOutputFixer — four-strategy repair pipeline for malformed output: regex repair, field injection, fallback key-value parse, LLM reformat.
retry_handler.pyRetryHandler — re-prompts a live LLM with escalating strategies (stricter format instructions → JSON-only → simplified question) when parsing keeps failing.
base_parser.pyBaseOutputParser abstract interface, ParsingError, and two composable wrappers: AutoFixingParser and ChainedParser.
json_parser.pyJSONOutputParser — standalone JSON extraction/parsing with optional Pydantic validation.
yaml_parser.pyYAMLOutputParser — standalone YAML extraction/parsing with optional Pydantic validation.
csv_parser.pyCSVOutputParser — standalone CSV table extraction with delimiter auto-detection and column typing.
list_parser.pyListOutputParser — extracts numbered/bulleted/comma-separated lists.
structured_parser.pyStructuredOutputParser + ResponseSchema — extracts named key: value fields from free text via regex patterns.
pydantic_parser.pyPydanticOutputParser — JSON extraction directly into a validated Pydantic model instance.

Two ways to use this library

A. Single-format parsers — use when you know exactly what format you're expecting from the LLM:

Python · 5 lines
from output_parser import JSONOutputParser

parser = JSONOutputParser()
result = parser.parse('Here is the data: {"name": "John", "age": 30}')
# {'name': 'John', 'age': 30}

B. The orchestrator — use when the format is unpredictable, you want automatic repair/retry, or you need a full audit trail:

Python · 6 lines
from output_parser import OutputParser

parser = OutputParser()
result = parser.parse('{"answer": "Paris", "confidence": 0.98}')
print(result.data)   # {'answer': 'Paris', 'confidence': 0.98}
print(result.trace.summary())

Continue to Installation and Quickstart.

[!NOTE] Scope of this documentation This documentation was generated directly from the output_parser package source (14 modules, ~3,700 lines). Every signature, parameter, exception, and behavior described here reflects the actual implementation. Where a behavior could not be determined from the source (e.g. exact upstream pydantic/pyyaml version compatibility), it is explicitly noted rather than assumed.