Skip to main content

​
Start with the pre-built example

We have built a pre-built example for you to get started quickly. You can find the example in Github.

​
Quick Start

1

Install dependencies

pip install instructor openai respan-tracing python-dotenv
2

Set up environment variables

Create a .env file in your project root:
.env
OPENAI_API_KEY=your_openai_api_key_here
RESPAN_API_KEY=your_respan_api_key_here
3

Initialize Respan tracing

Python
import os
from respan_tracing import RespanTelemetry, Instruments
from dotenv import load_dotenv

load_dotenv()

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

Set up your Instructor client

Python
import instructor
from openai import AsyncOpenAI

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

Define your Pydantic models

Python
from pydantic import BaseModel, Field

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")
6

Add @task decorator to your functions

Python
from respan_tracing.decorators import task

@task(name="extract_user_async")
async def extract_user(text: str) -> User:
    """Extract user information using async Instructor."""
    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
    )
7

Run your workflow

Python
import asyncio

async def main():
    """Demo the async extraction with tracing."""
    
    # Sample text
    user_text = """
    Meet Alex Johnson, a 32-year-old Senior Software Engineer at Google.
    You can reach Alex at [email protected] for any technical questions.
    """
    
    # Extract user (automatically traced!)
    user = await extract_user(user_text)
    
    print(user.model_dump())

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

​
Complete Example

Here’s a complete example that demonstrates async Instructor with Respan tracing:
Python
"""
Simple Async Instructor + Respan Tracing Example

This example shows how easy it is to add Respan tracing to your async Instructor workflows.
Just 3 lines of setup, then your structured outputs are automatically traced!
"""

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()

# 1️⃣ Initialize Respan tracing (one line!)
k_tl = RespanTelemetry(
    app_name="async-instructor-demo", 
    instruments={Instruments.OPENAI}
)

# 2️⃣ Set up your async Instructor client (your existing code)
async_client = AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))
instructor_client = instructor.from_openai(async_client)

# 3️⃣ Define your Pydantic models (your existing code)
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")

# 4️⃣ Add @task decorator to your functions (one line per function!)
@task(name="extract_user_async")
async def extract_user(text: str) -> User:
    """Extract user information using async Instructor."""
    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():
    """Demo the async extraction with tracing."""
    
    # Sample text
    user_text = """
    Meet Alex Johnson, a 32-year-old Senior Software Engineer at Google.
    You can reach Alex at [email protected] for any technical questions.
    """
    
    # Extract user (automatically traced!)
    user = await extract_user(user_text)
    
    print(user.model_dump())

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