[bot] Add Instructor native integration for multi-provider structured output instrumentation

[braintrust-bot]

Summary

instructor is the de facto Python library for structured output extraction from LLMs, with 3M+ monthly PyPI downloads and 10K+ GitHub stars. It wraps provider clients (OpenAI, Anthropic, Google, Cohere, Mistral, Groq, Together, and 10+ others) to return validated Pydantic models. This repository has zero native instrumentation for the instructor execution surface — no integration directory, no wrap_instructor() function, no patcher, no auto_instrument() support.

Braintrust currently documents a manual workaround: instructor.patch(wrap_openai(OpenAI())). This approach is:

1. OpenAI-only — users of instructor.from_anthropic(), instructor.from_cohere(), instructor.from_google_generativeai(), instructor.from_mistral(), and 10+ other provider backends get zero Braintrust tracing.
2. Layer-blind — the Instructor retry loop, validation failures, and response_model metadata are never captured as span attributes. Users see only the raw provider LLM call, not the structured extraction context.

What needs to be instrumented

The instructor package (v1.15.1) exposes these execution surfaces, none of which have native instrumentation:

Primary execution API

Method	Description
client.chat.completions.create(response_model=..., ...)	Patched create() — the core structured output call with Pydantic validation and retry logic
client.chat.completions.create_with_completion(response_model=..., ...)	Returns both the extracted model and raw completion
client.chat.completions.create_partial(response_model=..., ...)	Streams partial Pydantic objects progressively
client.chat.completions.create_iterable(response_model=..., ...)	Streams multiple Pydantic objects sequentially

All methods have async variants via AsyncInstructor clients.

Initialization surfaces (15+ providers)

Function	Backend
instructor.from_openai(client)	OpenAI
instructor.from_anthropic(client)	Anthropic
instructor.from_cohere(client)	Cohere
instructor.from_google_generativeai(client)	Google GenAI
instructor.from_mistral(client)	Mistral
instructor.from_groq(client)	Groq
instructor.from_together(client)	Together AI
instructor.from_litellm(client)	LiteLLM
instructor.from_provider("openai/gpt-4o")	Unified provider string API

Instructor-specific span attributes not captured by existing integrations

Even when the underlying provider is already instrumented (e.g., OpenAI), Instructor adds unique context that is not captured:

• response_model — the Pydantic class being extracted (type name and schema)
• max_retries — configured retry limit
• retry_count — actual number of retries performed (validation failures)
• validation_errors — Pydantic validation errors from failed attempts
• mode — Instructor mode (e.g., TOOLS, JSON, MD_JSON, FUNCTIONS)

A user who makes 3 LLM calls due to validation failures currently sees 3 raw provider spans with no shared Instructor context. A native integration would create a parent Instructor span wrapping all retries.

No coverage in any instrumentation layer

• No integration directory (py/src/braintrust/integrations/instructor/)
• No wrapper function (e.g. wrap_instructor())
• No patcher in any existing integration
• No nox test session (test_instructor)
• No version entry in py/src/braintrust/integrations/versioning.py
• No mention in py/src/braintrust/integrations/__init__.py

A grep for instructor (case-insensitive) across py/src/braintrust/integrations/ returns zero matches in integration code.

Braintrust docs status

unclear — The Braintrust integrations directory lists Instructor as a supported SDK integration. The Instructor-specific docs page describes a manual wrap_openai() workaround for OpenAI-backed Instructor only. No auto_instrument() support is documented, and non-OpenAI provider backends (Anthropic, Google, Cohere, Mistral, etc.) are not mentioned.

Upstream references

• instructor on PyPI: https://pypi.org/project/instructor/
• instructor on GitHub: https://github.com/instructor-ai/instructor (10K+ stars, 3M+ monthly downloads)
• instructor documentation: https://python.useinstructor.com/
• Multi-provider support: https://python.useinstructor.com/integrations/
• Retry and validation docs: https://python.useinstructor.com/concepts/retrying/

Local repo files inspected

• py/src/braintrust/integrations/ — no instructor/ directory exists on main
• py/src/braintrust/wrappers/ — no Instructor wrapper
• py/noxfile.py — no test_instructor session
• py/src/braintrust/integrations/__init__.py — Instructor not listed in integration registry
• py/src/braintrust/integrations/versioning.py — no Instructor version matrix
• py/pyproject.toml — no Instructor entries in [tool.braintrust.matrix]
• Full repo grep for instructor (case-insensitive) across py/src/braintrust/integrations/ — zero matches