Instructor

Learn how to integrate KeywordsAI tracing with Instructor to monitor and analyze your structured LLM outputs. Step-by-step guide for setting up tracing with async Instructor workflows.

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 keywordsai-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
   KEYWORDSAI_API_KEY=your_keywordsai_api_key_here
   
3. Initialize KeywordsAI tracing

   Python

   import os
   from keywordsai_tracing import KeywordsAITelemetry, Instruments
   from dotenv import load_dotenv
   
   load_dotenv()
   
   # Initialize KeywordsAI tracing (one line!)
   k_tl = KeywordsAITelemetry(
       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 keywordsai_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 [e-mail] 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 KeywordsAI tracing:

Python

"""
Simple Async Instructor + KeywordsAI Tracing Example

This example shows how easy it is to add KeywordsAI 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 keywordsai_tracing import KeywordsAITelemetry, Instruments
from keywordsai_tracing.decorators import task
from dotenv import load_dotenv

load_dotenv()

# 1️⃣ Initialize KeywordsAI tracing (one line!)
k_tl = KeywordsAITelemetry(
    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 [e-mail] for any technical questions.
    """
    
    # Extract user (automatically traced!)
    user = await extract_user(user_text)
    
    print(user.model_dump())

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