You know that moment when you ask an AI a clear question and get back a brilliant, sprawling answer that’s completely unusable in your code? Maybe you asked for a list of product names and got a paragraph. Or requested a specific JSON structure and received a creative variation that breaks your entire pipeline. That precise frustration is what led me here, to talk about taming that unpredictability. Getting a language model to give you consistent, structured data isn’t just a nice-to-have for hobby projects; it’s the difference between a clever demo and a robust, production-ready application. If you’re building anything that needs to connect an LLM to another system—a database, an API, a user interface—this is the fundamental skill you need. Stick with me, and I’ll show you how to turn creative text into reliable data. And if you find this useful, please consider liking, sharing, or commenting with your own experiences at the end.
So, how do we bridge the gap between free-form text and a strict data format? We need to move from asking nicely to providing a clear contract. This contract tells the model exactly what shape its response must take. Think of it like moving from saying “describe the room” to handing someone a detailed form with fields for “color,” “dimensions,” and “furniture count.”
My journey into this started with a simple task: extracting meeting action items. Without structure, the model would give me verbose summaries. I needed a list. That’s where Pydantic becomes your best friend. It’s a Python library that lets you define data models with strict types and validation rules. You’re not just hoping for a list; you’re defining a List[str] and demanding it.
from pydantic import BaseModel, Field
from typing import List
from enum import Enum
class Sentiment(str, Enum):
POSITIVE = "positive"
NEGATIVE = "negative"
NEUTRAL = "neutral"
class AnalysisResult(BaseModel):
summary: str = Field(..., min_length=20, max_length=200)
sentiment: Sentiment
action_items: List[str] = Field(..., description="A clear list of tasks")See what happened there? I defined an AnalysisResult object. It must have a summary string of a certain length. Its sentiment must be one of three specific values, thanks to the Enum. The action_items field must be a list of strings. This model is our contract. But how do we get the LLM to sign it?
This is where tools like the instructor library shine. It acts as a smart adapter between your Pydantic model and OpenAI’s API, essentially teaching the model to “think” in terms of your structure. You don’t just send a prompt; you send the prompt and the blueprint for the response.
import instructor
from openai import OpenAI
client = instructor.from_openai(OpenAI())
def get_structured_response(user_input: str) -> AnalysisResult:
result = client.chat.completions.create(
model="gpt-4-turbo",
response_model=AnalysisResult, # Here's the blueprint
messages=[
{"role": "system", "content": "Extract a summary, sentiment, and action items."},
{"role": "user", "content": user_input}
],
)
return result
# Now it returns a validated AnalysisResult object, not just text.
analysis = get_structured_response("The project is behind schedule. We need John to finalize the design by Friday and Sarah to contact the vendor.")
print(f"Sentiment: {analysis.sentiment}") # Sentiment: NEGATIVE
print(f"Actions: {analysis.action_items}") # Actions: ['John to finalize design by Friday', 'Sarah to contact vendor']Isn’t that cleaner? The response is now a Python object. You can access analysis.sentiment confidently, knowing it’s guaranteed to be “positive,” “negative,” or “neutral.” Your code downstream can now rely on this structure. But what if the model still occasionally misunderstands and tries to fill a field with the wrong type of data? The Pydantic model will catch it and raise a validation error right then and there, protecting your application from bad data.
What about more complex rules, though? Let’s say an action_item must always start with a verb, or a confidence_score must be between 0 and 1. For these logical constraints, we can add custom validators right into our Pydantic model. This is where you move from basic type safety to enforcing real business logic.
from pydantic import validator, confloat
class AdvancedAnalysis(AnalysisResult):
confidence: confloat(ge=0.0, le=1.0) # Constrained float type
@validator('action_items', each_item=True)
def action_must_start_with_verb(cls, v):
# A simplistic check for illustration
if not v.split()[0].endswith('s'):
raise ValueError(f"Action '{v}' should be a clear instruction")
return vNow, the validation is even stricter. But what if you need to guide the model before it generates a response, to reduce these errors in the first place? Or validate formats like dates, URLs, or SQL queries? This is the territory of Guardrails.
Think of Guardrails as setting up the guardrails on a bowling lane. You define the “rail” (a validation rule) and specify what happens if the ball hits it: maybe it gets corrected (“filter”), maybe you get a warning (“fix”), or maybe you ask the model to try again (“reask”).
import guardrails as gd
from guardrails.validators import ValidLength, ValidRange, ValidSQL
# Define your output structure with inline validators
spec = """
<rail version="0.1">
<output>
<string name="summary" validators="ValidLength(min=30, max=200)"/>
<float name="score" validators="ValidRange(min=0, max=10)"/>
<string name="query" validators="ValidSQL(dialect='sqlite')" />
</output>
</rail>
"""
guard = gd.Guard.from_rail_string(spec)
# When you run the LLM call through `guard`, it will enforce these rules.
raw_llm_output, validated_output, *rest = guard(
llm_api=openai.completions.create,
prompt="Summarize the text and score its complexity from 1-10..."
)Here, ValidSQL would actually check if the generated string is valid SQLite syntax. This proactive guidance can be incredibly powerful for ensuring technical correctness. Which approach should you use? instructor with Pydantic is often the simplest and most elegant for most structured data tasks, tightly integrating with Python’s type system. Guardrails offers more specialized, syntax-focused validators and a different way of defining specs. You might even use them together.
So, where does this leave us? We started with a mess of unstructured text and built a pipeline that delivers validated, typed objects. This is not just about convenience; it’s about building systems that are reliable and maintainable. You can now write unit tests against your data models. You can version your output schemas. Your application logic becomes simpler because it trusts the shape of the data.
Have you ever spent more time parsing an AI’s response than you did building the feature that uses it? That time is over. By defining a clear contract and using these tools to enforce it, you shift your effort from cleaning up messes to building on a solid foundation. This is how you move from prototypes to products. I’d love to hear what you’re building with structured outputs—share your thoughts or questions below
As a best-selling author, I invite you to explore my books on Amazon. Don’t forget to follow me on Medium and show your support. Thank you! Your support means the world!
101 Books
101 Books is an AI-driven publishing company co-founded by author Aarav Joshi. By leveraging advanced AI technology, we keep our publishing costs incredibly low—some books are priced as low as $4—making quality knowledge accessible to everyone.
Check out our book Golang Clean Code available on Amazon.
Stay tuned for updates and exciting news. When shopping for books, search for Aarav Joshi to find more of our titles. Use the provided link to enjoy special discounts!
📘 Checkout my latest ebook for free on my channel!
Be sure to like, share, comment, and subscribe to the channel!
Our Creations
Be sure to check out our creations:
Investor Central | Investor Central Spanish | Investor Central German | Smart Living | Epochs & Echoes | Puzzling Mysteries | Hindutva | Elite Dev | JS Schools
We are on Medium
Tech Koala Insights | Epochs & Echoes World | Investor Central Medium | Puzzling Mysteries Medium | Science & Epochs Medium | Modern Hindutva
