How to beginner · 3 min read

How to use guidance library for structured outputs

Quick answer

Use the guidance Python library to define structured output schemas with templates and parse AI responses into Python objects. This enables reliable extraction of structured data from models like gpt-4o by specifying output formats and validation rules.

PREREQUISITES

Python 3.8+
OpenAI API key (free tier works)
pip install guidance openai

Setup

Install the guidance library and set your OpenAI API key as an environment variable.

bash

pip install guidance openai

Step by step

Define a structured output schema using guidance templates and parse the AI model's response into Python objects for reliable structured data extraction.

python

import os
import guidance

# Set your OpenAI API key in environment variable OPENAI_API_KEY

guidance.llm = guidance.llms.OpenAI(
    model="gpt-4o",
    api_key=os.environ["OPENAI_API_KEY"]
)

# Define a schema for structured output
schema = guidance.Struct(
    name=guidance.String(),
    age=guidance.Integer(),
    email=guidance.String()
)

# Create a prompt template with structured output
prompt = guidance("""
You are a helpful assistant.
Extract the user's name, age, and email from the text below.

Text: {{text}}

{{#schema}}
""", schema=schema)

# Input text to parse
input_text = "My name is Alice, I am 30 years old, and my email is alice@example.com."

# Run the guidance prompt
output = prompt(text=input_text)

# Access structured output as a Python dict
result = output["schema"]
print(result)

output

{'name': 'Alice', 'age': 30, 'email': 'alice@example.com'}

Common variations

You can use different models by changing guidance.llm initialization, or run asynchronously with asyncio. The guidance library supports nested structures and lists for complex schemas.

python

import os
import guidance

# Use a different model
guidance.llm = guidance.llms.OpenAI(
    model="gpt-4o-mini",
    api_key=os.environ["OPENAI_API_KEY"]
)

# Define nested schema example
address_schema = guidance.Struct(
    street=guidance.String(),
    city=guidance.String(),
    zip=guidance.Integer()
)

user_schema = guidance.Struct(
    name=guidance.String(),
    age=guidance.Integer(),
    address=address_schema
)

prompt = guidance("""
Extract user info:

{{#user_schema}}
""", schema=user_schema)

input_text = "John Doe, 45 years old, lives at 123 Main St, Springfield, 12345."

output = prompt(text=input_text)
print(output["user_schema"])

output

{'name': 'John Doe', 'age': 45, 'address': {'street': '123 Main St', 'city': 'Springfield', 'zip': 12345}}

Troubleshooting

If the output is not parsed correctly, ensure your prompt clearly instructs the model to follow the schema.
Check that your API key is set correctly in os.environ["OPENAI_API_KEY"].
Use print(output) to debug raw responses.
For complex schemas, validate your template syntax matches guidance documentation.

✅

Key Takeaways

Use guidance.Struct to define structured output schemas for AI responses.
Set guidance.llm with your OpenAI API key and preferred model before running prompts.
Structured outputs enable reliable parsing of AI-generated data into Python objects.
You can nest schemas and handle complex data structures with guidance.
Clear prompt instructions improve schema adherence and parsing accuracy.

Verified 2026-04 · gpt-4o, gpt-4o-mini

Verify ↗