feat: Add Instructor integration (#465)

ref https://python.useinstructor.com/
resolves
#460

Users can enable Instructor tracing either globally with
auto-instrumentation:

```python
import braintrust

braintrust.auto_instrument()
```

or explicitly for Instructor only:

```python
from braintrust.integrations import InstructorIntegration

InstructorIntegration.setup()
```

Manual wrapping is also supported for direct client/class wrapping:

```python
from braintrust import wrap_instructor

client = wrap_instructor(client)
```

The integration instruments sync and async Instructor structured-output
APIs, including `create`, `create_with_completion`, `create_partial`,
and `create_iterable`.

It emits `task` spans for Instructor structured-output work. Each span
captures the response model, mode, messages, max retries, retry count,
validation errors, and the extracted Pydantic output (or collected
iterable/partial outputs):

```python
{
    "input": {
        "response_model": "Person",
        "mode": "TOOLS",
        "messages": [...],
    },
    "output": {"name": "Grace", "age": 45},
    "metadata": {
        "response_model": "Person",
        "mode": "TOOLS",
        "max_retries": 3,
        "retry_count": 0,
        "validation_errors": [],
    },
}
```

Token usage and LLM request/response spans remain owned by the
underlying provider integrations such as OpenAI or Anthropic to avoid
double-counting.

Author: AbhiPrasad

py/noxfile.py

@@ -230,6 +230,21 @@ def test_cohere(session, version):
     _run_tests(session, f"{INTEGRATION_DIR}/cohere/test_cohere.py", version=version)
 
 
+INSTRUCTOR_VERSIONS = _get_matrix_versions("instructor")
+
+
+@nox.session()
+@nox.parametrize("version", INSTRUCTOR_VERSIONS, ids=INSTRUCTOR_VERSIONS)
+def test_instructor(session, version):
+    """Test the native Instructor structured-output integration."""
+    _install_test_deps(session)
+    _install_matrix_dep(session, "instructor", version)
+    # Instructor wraps a provider client; we exercise it against an OpenAI
+    # client via VCR cassettes recorded against ``api.openai.com``.
+    _install_matrix_dep(session, "openai", LATEST)
+    _run_tests(session, f"{INTEGRATION_DIR}/instructor/test_instructor.py", version=version)
+
+
 OPENAI_VERSIONS = _get_matrix_versions("openai")
 
 

py/pyproject.toml

@@ -232,6 +232,7 @@ lint = [
     "dspy",
     "google-adk",
     "google-genai",
+    "instructor",
     "litellm>=1.83.10",
     "livekit-agents",
     "livekit-plugins-openai",
@@ -378,6 +379,10 @@ latest = "pydantic-ai==1.102.0"
 latest = "autoevals==0.2.0"
 "0.0.129" = "autoevals==0.0.129"
 
+[tool.braintrust.matrix.instructor]
+latest = "instructor==1.15.1"
+"1.11.0" = "instructor==1.11.0"
+
 [tool.braintrust.matrix.google-genai]
 latest = "google-genai==2.6.0"
 "1.75.0" = "google-genai==1.75.0"
@@ -465,6 +470,7 @@ crewai = ["crewai"]
 dspy = ["dspy"]
 google_genai = ["google-genai"]
 huggingface_hub = ["huggingface-hub"]
+instructor = ["instructor"]
 langchain = ["langchain-core"]
 litellm = ["litellm"]
 livekit_agents = ["livekit-agents"]

py/src/braintrust/__init__.py

@@ -68,6 +68,7 @@ def is_equal(expected, output):
 from .functions.stream import *
 from .generated_types import *
 from .integrations.anthropic import wrap_anthropic as wrap_anthropic
+from .integrations.instructor import wrap_instructor as wrap_instructor
 from .integrations.litellm import wrap_litellm as wrap_litellm
 from .integrations.openai import wrap_openai as wrap_openai
 from .integrations.openrouter import wrap_openrouter as wrap_openrouter

py/src/braintrust/auto.py

@@ -19,6 +19,7 @@
     DSPyIntegration,
     GoogleGenAIIntegration,
     HuggingFaceHubIntegration,
+    InstructorIntegration,
     LangChainIntegration,
     LiteLLMIntegration,
     LiveKitAgentsIntegration,
@@ -57,6 +58,7 @@ def auto_instrument(
     litellm: bool = True,
     pydantic_ai: bool = True,
     google_genai: bool = True,
+    instructor: bool = True,
     openrouter: bool = True,
     mistral: bool = True,
     huggingface_hub: bool = True,
@@ -90,6 +92,7 @@ def auto_instrument(
         litellm: Enable LiteLLM instrumentation (default: True)
         pydantic_ai: Enable Pydantic AI instrumentation (default: True)
         google_genai: Enable Google GenAI instrumentation (default: True)
+        instructor: Enable Instructor (structured-output) instrumentation (default: True)
         openrouter: Enable OpenRouter instrumentation (default: True)
         mistral: Enable Mistral instrumentation (default: True)
         huggingface_hub: Enable HuggingFace Hub instrumentation (default: True)
@@ -164,6 +167,8 @@ def auto_instrument(
         results["pydantic_ai"] = _instrument_integration(PydanticAIIntegration)
     if google_genai:
         results["google_genai"] = _instrument_integration(GoogleGenAIIntegration)
+    if instructor:
+        results["instructor"] = _instrument_integration(InstructorIntegration)
     if openrouter:
         results["openrouter"] = _instrument_integration(OpenRouterIntegration)
     if mistral:

py/src/braintrust/integrations/__init__.py

@@ -9,6 +9,7 @@
 from .dspy import DSPyIntegration
 from .google_genai import GoogleGenAIIntegration
 from .huggingface_hub import HuggingFaceHubIntegration
+from .instructor import InstructorIntegration
 from .langchain import LangChainIntegration
 from .litellm import LiteLLMIntegration
 from .livekit_agents import LiveKitAgentsIntegration
@@ -34,6 +35,7 @@
     "DSPyIntegration",
     "GoogleGenAIIntegration",
     "HuggingFaceHubIntegration",
+    "InstructorIntegration",
     "LiteLLMIntegration",
     "LiveKitAgentsIntegration",
     "LangChainIntegration",

py/src/braintrust/integrations/auto_test_scripts/test_auto_instructor.py

@@ -0,0 +1,58 @@
+"""Test auto_instrument for Instructor."""
+
+import instructor
+import openai
+from braintrust.auto import auto_instrument
+from braintrust.integrations.test_utils import autoinstrument_test_context
+from pydantic import BaseModel
+
+
+class Person(BaseModel):
+    name: str
+    age: int
+
+
+# 1. Instrument
+results = auto_instrument()
+assert results.get("instructor") is True, results
+
+# 2. Idempotent
+results2 = auto_instrument()
+assert results2.get("instructor") is True
+
+# 3. Drive a real instructor.from_openai call against a recorded cassette and
+#    verify a parent task-typed Instructor span shows up alongside the OpenAI
+#    llm child span.  Cassette is shared with the in-process test suite under
+#    integrations/instructor/cassettes/<version>/.
+with autoinstrument_test_context(
+    "TestInstructorOpenAISpans.test_instructor_openai_single_success",
+    integration="instructor",
+) as memory_logger:
+    client = openai.OpenAI(api_key="sk-test-dummy-api-key-for-vcr-tests")
+    patched = instructor.from_openai(client, mode=instructor.Mode.TOOLS)
+    result = patched.chat.completions.create(
+        model="gpt-4o-mini",
+        response_model=Person,
+        max_retries=3,
+        messages=[{"role": "user", "content": "Extract Grace, age 45."}],
+    )
+    assert isinstance(result, Person)
+    assert result.model_dump() == {"name": "Grace", "age": 45}
+
+    raw = memory_logger.pop()
+    spans = []
+    for s in raw:
+        if isinstance(s, list):
+            spans.extend(s)
+        else:
+            spans.append(s)
+    types = [s["span_attributes"].get("type") for s in spans]
+    assert "task" in types, f"missing instructor parent (task) span: {types}"
+    assert "llm" in types, f"missing openai child (llm) span: {types}"
+    parent = next(s for s in spans if s["span_attributes"].get("type") == "task")
+    assert parent["span_attributes"]["name"] == "instructor.create"
+    assert parent["metadata"]["response_model"] == "Person"
+    assert parent["metadata"]["mode"] == "TOOLS"
+    assert parent["metadata"]["retry_count"] == 0
+
+print("SUCCESS")

py/src/braintrust/integrations/instructor/__init__.py

@@ -0,0 +1,28 @@
+"""Braintrust integration for the Instructor structured-output library."""
+
+from typing import Any
+
+from .integration import InstructorIntegration
+from .patchers import InstructorPatcher
+
+
+def wrap_instructor(client: Any) -> Any:
+    """Instrument an ``instructor.Instructor`` / ``AsyncInstructor`` client in place.
+
+    The Instructor client returned by ``instructor.from_openai(...)`` (and
+    the other ``from_<provider>`` factories) is mutated to emit a Braintrust
+    ``task``-typed span per ``create``/``create_with_completion``/
+    ``create_partial``/``create_iterable`` call.  The underlying provider
+    client is left untouched — combine with ``wrap_openai`` /
+    ``wrap_anthropic`` / ``auto_instrument`` to also see the LLM child span.
+
+    Returns *client* for chaining.
+    """
+    InstructorPatcher.wrap_target(type(client))
+    return client
+
+
+__all__ = [
+    "InstructorIntegration",
+    "wrap_instructor",
+]

py/src/braintrust/integrations/instructor/cassettes/1.11.0/TestInstructorOpenAISpans.test_instructor_openai_retries_then_succeeds.yaml

@@ -0,0 +1,34 @@
+interactions:
+- request:
+    body: '{"messages":[{"role":"user","content":"Extract Ada, age 30."}],"model":"gpt-4o-mini","tool_choice":{"type":"function","function":{"name":"Person"}},"tools":[{"type":"function","function":{"name":"Person","description":"Correctly extracted `Person` with all the required parameters with correct types","parameters":{"properties":{"name":{"description":"The person''s name","title":"Name","type":"string"},"age":{"description":"The person''s age","title":"Age","type":"integer"}},"required":["age","name"],"type":"object"}}}]}'
+    headers: {}
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: '{"id":"chatcmpl-instructor-ada-1","object":"chat.completion","created":1779735568,"model":"gpt-4o-mini-2024-07-18","choices":[{"index":0,"message":{"role":"assistant","content":null,"tool_calls":[{"id":"call_ada_1","type":"function","function":{"name":"Person","arguments":"{\"name\":\"Ada\"}"}}],"refusal":null,"annotations":[]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":80,"completion_tokens":8,"total_tokens":88},"service_tier":"default","system_fingerprint":"fp_test"}'
+    headers:
+      content-type:
+      - application/json
+      x-request-id:
+      - req_instructor_ada_1
+    status:
+      code: 200
+      message: OK
+- request:
+    body: '{"messages":[{"role":"user","content":"Extract Ada, age 30."},{"role":"assistant","tool_calls":[{"id":"call_ada_1","type":"function","function":{"name":"Person","arguments":"{\"name\":\"Ada\"}"}}]},{"role":"tool","tool_call_id":"call_ada_1","name":"Person","content":"Validation Error found:\n1 validation error for Person\nage\n  Field required [type=missing, input_value={''name'': ''Ada''}, input_type=dict]\n    For further information visit https://errors.pydantic.dev/2.12/v/missing\nRecall the function correctly, fix the errors"}],"model":"gpt-4o-mini","tool_choice":{"type":"function","function":{"name":"Person"}},"tools":[{"type":"function","function":{"name":"Person","description":"Correctly extracted `Person` with all the required parameters with correct types","parameters":{"properties":{"name":{"description":"The person''s name","title":"Name","type":"string"},"age":{"description":"The person''s age","title":"Age","type":"integer"}},"required":["age","name"],"type":"object"}}}]}'
+    headers: {}
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: '{"id":"chatcmpl-instructor-ada-2","object":"chat.completion","created":1779735569,"model":"gpt-4o-mini-2024-07-18","choices":[{"index":0,"message":{"role":"assistant","content":null,"tool_calls":[{"id":"call_ada_2","type":"function","function":{"name":"Person","arguments":"{\"name\":\"Ada\",\"age\":30}"}}],"refusal":null,"annotations":[]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":120,"completion_tokens":12,"total_tokens":132},"service_tier":"default","system_fingerprint":"fp_test"}'
+    headers:
+      content-type:
+      - application/json
+      x-request-id:
+      - req_instructor_ada_2
+    status:
+      code: 200
+      message: OK
+version: 1

py/src/braintrust/integrations/instructor/cassettes/1.11.0/TestInstructorOpenAISpans.test_instructor_openai_single_success.yaml

@@ -0,0 +1,18 @@
+interactions:
+- request:
+    body: '{"messages":[{"role":"user","content":"Extract Grace, age 45."}],"model":"gpt-4o-mini","tool_choice":{"type":"function","function":{"name":"Person"}},"tools":[{"type":"function","function":{"name":"Person","description":"Correctly extracted `Person` with all the required parameters with correct types","parameters":{"properties":{"name":{"description":"The person''s name","title":"Name","type":"string"},"age":{"description":"The person''s age","title":"Age","type":"integer"}},"required":["age","name"],"type":"object"}}}]}'
+    headers: {}
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: '{"id":"chatcmpl-instructor-grace","object":"chat.completion","created":1779735568,"model":"gpt-4o-mini-2024-07-18","choices":[{"index":0,"message":{"role":"assistant","content":null,"tool_calls":[{"id":"call_grace","type":"function","function":{"name":"Person","arguments":"{\"name\":\"Grace\",\"age\":45}"}}],"refusal":null,"annotations":[]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":80,"completion_tokens":12,"total_tokens":92,"prompt_tokens_details":{"cached_tokens":0,"audio_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"service_tier":"default","system_fingerprint":"fp_test"}'
+    headers:
+      content-type:
+      - application/json
+      x-request-id:
+      - req_instructor_grace
+    status:
+      code: 200
+      message: OK
+version: 1

py/src/braintrust/integrations/instructor/cassettes/1.11.0/TestInstructorParentIsNotLLM.test_parent_span_type_is_task_not_llm.yaml

@@ -0,0 +1,18 @@
+interactions:
+- request:
+    body: '{"messages":[{"role":"user","content":"Extract Grace, age 45."}],"model":"gpt-4o-mini","tool_choice":{"type":"function","function":{"name":"Person"}},"tools":[{"type":"function","function":{"name":"Person","description":"Correctly extracted `Person` with all the required parameters with correct types","parameters":{"properties":{"name":{"description":"The person''s name","title":"Name","type":"string"},"age":{"description":"The person''s age","title":"Age","type":"integer"}},"required":["age","name"],"type":"object"}}}]}'
+    headers: {}
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: '{"id":"chatcmpl-instructor-grace","object":"chat.completion","created":1779735568,"model":"gpt-4o-mini-2024-07-18","choices":[{"index":0,"message":{"role":"assistant","content":null,"tool_calls":[{"id":"call_grace","type":"function","function":{"name":"Person","arguments":"{\"name\":\"Grace\",\"age\":45}"}}],"refusal":null,"annotations":[]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":80,"completion_tokens":12,"total_tokens":92,"prompt_tokens_details":{"cached_tokens":0,"audio_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"service_tier":"default","system_fingerprint":"fp_test"}'
+    headers:
+      content-type:
+      - application/json
+      x-request-id:
+      - req_instructor_grace
+    status:
+      code: 200
+      message: OK
+version: 1