Standardize provider imports in documentation (#1896)

Author: jxnl

CLAUDE.md

@@ -165,6 +165,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Configuration**: Uses `pyproject.toml` settings for type checking
 - Run `uv run ty check` before committing - aim for zero errors
 
+### Code Quality Checks Before Committing
+Always run these checks before committing code:
+1. **Ruff linting**: `uv run ruff check .` - Fix all errors
+2. **Ruff formatting**: `uv run ruff format .` - Apply consistent formatting
+3. **Type checking**: `uv run ty check` - Aim for zero type errors
+4. **Tests**: Run relevant tests to ensure changes don't break functionality
+
 ### Type Patterns
 - **Bounded TypeVars**: Use `T = TypeVar("T", bound=Union[BaseModel, ...])` for constraints
 - **Version Compatibility**: Handle Python 3.9 vs 3.10+ typing differences explicitly

docs/architecture.md

@@ -61,7 +61,7 @@ class User(BaseModel):
     name: str
     age: int
 
-client = instructor.from_openai(openai.OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 
 model = client.chat.completions.create(
     model="gpt-4o-mini",
@@ -87,7 +87,7 @@ class User(BaseModel):
     age: int
 
 async def main():
-    aclient = instructor.from_openai(openai.AsyncOpenAI())
+    aclient = instructor.from_provider("openai/gpt-5-nano", async_client=True)
     model = await aclient.chat.completions.create(
         model="gpt-4o-mini",
         messages=[{"role": "user", "content": "{\"name\": \"Ada\", \"age\": 37}"}],

docs/blog/posts/announcing-gemini-tool-calling-support.md

@@ -64,9 +64,7 @@ class User(BaseModel):
     age: int
 
 
-client = instructor.from_gemini(
-    client=genai.GenerativeModel(
-        model_name="models/gemini-1.5-flash-latest",  # (1)!
+client = instructor.from_provider("google/gemini-2.5-flash")
     )
 )
 
@@ -104,8 +102,7 @@ class User(BaseModel):
     age: int
 
 
-client = instructor.from_vertexai(
-    client=GenerativeModel("gemini-1.5-pro-preview-0409"),  # (1)!
+client = instructor.from_provider("google/gemini-2.5-flash", vertexai=True),  # (1)!
 )
 
 

docs/blog/posts/announcing-unified-provider-interface.md

@@ -42,7 +42,7 @@ The `from_provider()` function is designed to streamline several common workflow
 
 ## How it Works: A Look Under the Hood
 
-Internally, `from_provider()` (located in `instructor/auto_client.py`) parses the model string (e.g., `"openai/gpt-4o-mini"`) to identify the provider and model name. It then uses conditional logic to import the correct libraries, instantiate the client, and apply the appropriate Instructor patch. For instance, the conceptual handling for an OpenAI client would involve importing the `openai` SDK and `instructor.from_openai`.
+Internally, `from_provider()` (located in `instructor/auto_client.py`) parses the model string (e.g., `"openai/gpt-5-nano"`) to identify the provider and model name. It then uses conditional logic to import the correct libraries, instantiate the client, and apply the appropriate Instructor patch. For instance, the conceptual handling for an OpenAI client would involve importing the `openai` SDK and `instructor.from_openai`.
 
 ```python
 # Conceptual illustration of internal logic for OpenAI:

docs/blog/posts/best_framework.md

@@ -37,7 +37,7 @@ class User(BaseModel):
     age: int
 
 
-client = instructor.from_openai(openai.OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 
 user = client.chat.completions.create(
     model="gpt-3.5-turbo",

docs/blog/posts/caching.md

@@ -109,11 +109,9 @@ Let's first consider our canonical example, using the `OpenAI` Python client to
 
 ```python
 import instructor
-from openai import OpenAI
 from pydantic import BaseModel
-
 # Enables `response_model`
-client = instructor.from_openai(OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 
 
 class UserDetail(BaseModel):
@@ -336,10 +334,8 @@ import inspect
 import instructor
 import diskcache
 
-from openai import OpenAI
 from pydantic import BaseModel
-
-client = instructor.from_openai(OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 cache = diskcache.Cache('./my_cache_directory')
 
 
@@ -503,9 +499,7 @@ import inspect
 import instructor
 
 from pydantic import BaseModel
-from openai import OpenAI
-
-client = instructor.from_openai(OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 cache = redis.Redis("localhost")
 
 

docs/blog/posts/chain-of-density.md

@@ -287,10 +287,8 @@ def min_entity_density(cls, v: str):
 Now that we have our models and the rough flow figured out, let's implement a function to summarize a piece of text using `Chain Of Density` summarization.
 
 ```python hl_lines="4 9-24 38-68"
-from openai import OpenAI
 import instructor
-
-client = instructor.from_openai(OpenAI()) #(1)!
+client = instructor.from_provider("openai/gpt-5-nano") #(1)!
 
 def summarize_article(article: str, summary_steps: int = 3):
     summary_chain = []
@@ -399,9 +397,7 @@ import csv
 import logging
 import instructor
 from pydantic import BaseModel
-from openai import OpenAI
-
-client = instructor.from_openai(OpenAI()) # (2)!
+client = instructor.from_provider("openai/gpt-5-nano") # (2)!
 
 logging.basicConfig(level=logging.INFO) #(3)!
 

docs/blog/posts/chat-with-your-pdf-with-gemini.md

@@ -49,11 +49,7 @@ from pydantic import BaseModel
 import time
 
 # Initialize the client
-client = instructor.from_gemini(
-    client=genai.GenerativeModel(
-        model_name="models/gemini-1.5-flash-latest",
-    )
-)
+client = instructor.from_provider("google/gemini-2.5-flash")
 
 
 # Define your output structure

docs/blog/posts/citations.md

@@ -33,11 +33,9 @@ In this example, we use the `Statements` class to verify if a given substring qu
 
 ```python
 from typing import List
-from openai import OpenAI
 from pydantic import BaseModel, ValidationInfo, field_validator
 import instructor
-
-client = instructor.from_openai(OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 
 
 class Statements(BaseModel):

docs/blog/posts/extracting-model-metadata.md

@@ -170,7 +170,7 @@ With our inbuilt support for `jinja` formatting using the `context` keyword that
 import openai
 import instructor
 
-client = instructor.from_openai(openai.OpenAI())
+client = instructor.from_provider("openai/gpt-5-nano")
 
 resp = client.chat.completions.create(
     model="gpt-4o",