ZerdaZerda

Quickstart

On this page

This page walks through the two main entry points: single-format parsers and the full OutputParser orchestrator.

1. Parsing a known format

If you know your prompt asks the LLM for JSON, use JSONOutputParser directly:

Python · 6 lines
from output_parser import JSONOutputParser

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

JSONOutputParser (and every other single-format parser) also exposes get_format_instructions(), meant to be injected into your prompt so the LLM knows exactly what shape to return:

Python · 4 lines
print(parser.get_format_instructions())
# Return ONLY valid JSON with no surrounding text.
# Use double quotes for keys and string values.
# Example: {"key": "value", "number": 42}

Validate directly into a Pydantic model:

Python · 10 lines
from pydantic import BaseModel
from output_parser import JSONOutputParser

class User(BaseModel):
    name: str
    age: int

parser = JSONOutputParser(pydantic_model=User)
user = parser.parse('{"name": "John", "age": 30}')
# User(name='John', age=30)

2. Parsing unknown / unpredictable formats

When you don't control (or can't fully guarantee) what format the LLM returns, use the OutputParser orchestrator. It detects the format, parses it, and — if that fails — attempts repair before giving up:

Python · 8 lines
from output_parser import OutputParser

parser = OutputParser()
result = parser.parse('{"answer": "Paris", "confidence": 0.98}')

result.ok              # True — result.data is not None
result.data            # {'answer': 'Paris', 'confidence': 0.98}
result.trace.summary() # dict audit trail: detected format, fix strategy, timing, validations

3. Typed output with a schema

Python · 9 lines
from output_parser import OutputParser, ParseMode
from output_parser.schema import AnswerSchema

parser = OutputParser(schema=AnswerSchema, mode=ParseMode.STRICT)
result = parser.parse('{"answer": "Paris", "sources": ["wikipedia"], "confidence": 0.9}')

answer: AnswerSchema = result.data
print(answer.answer)      # "Paris"
print(answer.confidence)  # 0.9

In ParseMode.STRICT, if every recovery attempt fails, parser.parse(...) raises ParseError instead of silently falling back — see Concepts → Parse modes.

4. Adding LLM-backed retry

If you pass an llm_fn (any Callable[[str], str] that calls your model), the orchestrator can re-prompt the LLM with progressively stricter instructions when parsing keeps failing:

Python · 11 lines
def my_llm(prompt: str) -> str:
    # call your model here, return its raw text response
    ...

parser = OutputParser(
    schema=AnswerSchema,
    llm_fn=my_llm,
    max_retries=3,
    original_prompt="What is the capital of France?",
)
result = parser.parse(raw_llm_output)

This activates both OutputFixer's LLM_REFORMAT strategy and the full RetryHandler escalation ladder (STRICT_FORMAT → JSON_STRICT → SIMPLIFIED → GRACEFUL_FAIL).

5. Pre-built convenience factories

parser.py ships three factory functions for the most common cases:

Python · 5 lines
from output_parser import create_answer_parser, create_json_parser, create_tool_call_parser

answer_parser = create_answer_parser(llm_fn=my_llm)      # pre-wired for AnswerSchema
json_parser   = create_json_parser(schema=MyModel)         # pre-wired for JSON + optional schema
tool_parser   = create_tool_call_parser(llm_fn=my_llm)      # pre-wired for tool/function calls

See api/output_parser.md for full parameter details.

Where to go next

  • Architecture — how the pipeline stages fit together.
  • Concepts — parse modes, format detection, fix strategies, retry strategies.
  • API Reference — every class and function, documented individually.
  • Cookbook — practical recipes (chaining parsers, custom validation rules, safety checks).

Related pages