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

# Instructor

> Trace Instructor structured-output calls in Braintrust to debug extractions, evaluate models, and monitor retries

[Instructor](https://python.useinstructor.com/) is a Python library for extracting structured, validated data from LLMs using Pydantic models. Braintrust traces each extraction call, including the retries and validation failures Instructor handles under the hood.

**Python**

## Setup

Install the Braintrust SDK and Instructor alongside your provider SDK:

```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
pip install braintrust instructor openai
```

Set your API keys before you run your app:

```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-openai-api-key>
```

> [!NOTE]
>
> Tracing Instructor requires `instructor` 1.11.0 or later and the Braintrust Python SDK v0.23.0 or later.

## Auto-instrumentation

To trace Instructor without wrapping each client, call `init_logger()` and `auto_instrument()` once at startup. `auto_instrument()` patches Instructor's `create` methods along with the underlying provider SDK, so each extraction appears as a task span with the provider's LLM call nested beneath it.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import braintrust
import instructor
from openai import OpenAI
from pydantic import BaseModel

braintrust.init_logger(project="instructor-example")  # Replace with your project name
braintrust.auto_instrument()

class Person(BaseModel):
    name: str
    age: int

client = instructor.from_openai(OpenAI(), mode=instructor.Mode.RESPONSES_TOOLS)

person = client.responses.create(
    model="gpt-5-mini",
    input="Extract: John is 30 years old",
    response_model=Person,
)
```

> [accordion] Instrument only Instructor
>
> To patch Instructor without enabling Braintrust's other integrations, wrap the client with `wrap_instructor()` instead. See [Manual instrumentation](#manual-instrumentation-python).

## Manual instrumentation

To trace Instructor yourself, wrap the Instructor client with `wrap_instructor()`. Wrap the underlying provider client with `wrap_openai()` first so the provider's LLM call is captured as a child of the Instructor span.

```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
import instructor
from braintrust import init_logger, wrap_instructor, wrap_openai
from openai import OpenAI
from pydantic import BaseModel

init_logger(project="instructor-example")  # Replace with your project name

class Person(BaseModel):
    name: str
    age: int

# Wrap the provider client for the LLM span, then the Instructor client for the task span
client = wrap_instructor(
    instructor.from_openai(wrap_openai(OpenAI()), mode=instructor.Mode.RESPONSES_TOOLS)
)

person = client.responses.create(
    model="gpt-5-mini",
    input="Extract: John is 30 years old",
    response_model=Person,
)
```

## What Braintrust traces

Braintrust captures:

* **Structured-output spans** (`instructor.create`, `instructor.create_with_completion`, `instructor.create_partial`, and `instructor.create_iterable`), with the request messages, response model, and Instructor mode as input, and the extracted Pydantic model as output. `create_iterable` spans log a list of the extracted models. `create_partial` spans log only the final partial model.
* **Extraction metadata**, including the model, provider, response model, Instructor mode, and configured max retries.
* **Retry details**, including the retry count and the Pydantic validation errors that triggered each retry.

Token usage stays on the provider's LLM child span, so enable provider instrumentation (`wrap_openai()` or `auto_instrument()`) to see token counts alongside the extraction.

## Resources

* [Instructor documentation](https://python.useinstructor.com/)
* [Braintrust OpenAI integration](https://docs.braintrust.dev/integrations/ai-providers/openai.md)
* [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.