> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keywordsai.co/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/Keywords-AI/keywordsai-example-projects/tree/main/example_scripts/python/instructor).

## Quick Start

<Steps>
  <Step title="Install dependencies">
    ```bash theme={"system"}
    pip install instructor openai keywordsai-tracing python-dotenv
    ```
  </Step>

  <Step title="Set up environment variables">
    Create a `.env` file in your project root:

    ```bash .env theme={"system"}
    OPENAI_API_KEY=your_openai_api_key_here
    KEYWORDSAI_API_KEY=your_keywordsai_api_key_here
    ```
  </Step>

  <Step title="Initialize KeywordsAI tracing">
    ```python Python theme={"system"}
    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}
    )
    ```
  </Step>

  <Step title="Set up your Instructor client">
    ```python Python theme={"system"}
    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)
    ```
  </Step>

  <Step title="Define your Pydantic models">
    ```python Python theme={"system"}
    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")
    ```
  </Step>

  <Step title="Add @task decorator to your functions">
    ```python Python theme={"system"}
    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
        )
    ```
  </Step>

  <Step title="Run your workflow">
    ```python Python theme={"system"}
    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 alex.johnson@google.com for any technical questions.
        """
        
        # Extract user (automatically traced!)
        user = await extract_user(user_text)
        
        print(user.model_dump())

    if __name__ == "__main__":
        asyncio.run(main())
    ```
  </Step>
</Steps>

## Complete Example

Here's a complete example that demonstrates async Instructor with KeywordsAI tracing:

```python Python theme={"system"}
"""
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 alex.johnson@google.com for any technical questions.
    """
    
    # Extract user (automatically traced!)
    user = await extract_user(user_text)
    
    print(user.model_dump())

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