Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

​
What is Instructor?

Instructor is a Python library that makes it easy to get structured data like JSON from LLMs using Pydantic models. Use Instructor with Respan tracing to monitor your structured LLM outputs.

​
Setup

1

Install packages

pip install instructor openai respan-tracing python-dotenv
2

Set environment variables

.env
OPENAI_API_KEY=your-openai-api-key
RESPAN_API_KEY=your-respan-api-key
3

Initialize Respan tracing and run a structured extraction

import asyncio
import os
from pydantic import BaseModel, Field
import instructor
from openai import AsyncOpenAI
from respan_tracing import RespanTelemetry, Instruments
from respan_tracing.decorators import task
from dotenv import load_dotenv

load_dotenv()

# Initialize Respan tracing
k_tl = RespanTelemetry(
    app_name="instructor-demo",
    instruments={Instruments.OPENAI}
)

# Set up Instructor client
async_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
instructor_client = instructor.from_openai(async_client)

# Define your model
class User(BaseModel):
    name: str = Field(description="Full name")
    age: int = Field(description="Age in years")
    email: str = Field(description="Email address")
    role: str = Field(description="Job title")

# Decorate your function
@task(name="extract_user_async")
async def extract_user(text: str) -> User:
    return await instructor_client.chat.completions.create(
        model="gpt-4o-mini",
        response_model=User,
        messages=[
            {"role": "system", "content": "Extract user information from the text."},
            {"role": "user", "content": text}
        ],
        temperature=0.1
    )

async def main():
    user_text = """
    Meet Alex Johnson, a 32-year-old Senior Software Engineer at Google.
    You can reach Alex at alex.johnson@google.com for any technical questions.
    """
    user = await extract_user(user_text)
    print(user.model_dump())

if __name__ == "__main__":
    asyncio.run(main())
4

View your trace

Open the Traces page in the Respan dashboard.

​
Observability

With this integration, Respan auto-captures:
  • Instructor calls — each @task-decorated function as a span
  • LLM calls — model, input/output messages, token usage (auto-captured via Instruments.OPENAI)
  • Structured outputs — the Pydantic model returned by Instructor
  • Errors — failed extractions and error details
View traces on the Traces page.