[codex] consolidate latest fixes and docs (#2398)

Author: jxnl

CHANGELOG.md

@@ -7,6 +7,17 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
 ---
 
+## [1.15.4] - 2026-06-27
+
+### Fixed
+- **CLI fine-tuning**: Use the uploaded validation file ID when creating a fine-tuning job from local files, instead of passing the local validation file path through to OpenAI. ([#2397](https://github.com/567-labs/instructor/pull/2397))
+- **v2 core**: Prepare list and primitive response models before provider handler dispatch, fixing `list[Model]` and scalar response-model crashes such as `AttributeError: type object 'list' has no attribute 'model_json_schema'`. ([#2374](https://github.com/567-labs/instructor/issues/2374))
+- **v2 streaming**: Preserve backticks inside JSON string values during streamed JSON extraction.
+- **v2 multimodal**: Accept raw bytes in `Image.autodetect()` for JPEG, PNG, GIF, and WebP, while raising clear errors for unsupported image inputs. ([#2344](https://github.com/567-labs/instructor/issues/2344))
+- **Docs**: Refresh stale OpenAI and Ollama model strings in documentation examples. ([#2395](https://github.com/567-labs/instructor/issues/2395))
+
+---
+
 ## [1.15.3] - 2026-06-15
 
 ### Fixed

README.md

@@ -55,7 +55,7 @@ Getting structured data from LLMs is hard. You need to:
 
 ```python
 response = openai.chat.completions.create(
-    model="gpt-4",
+    model="gpt-5.4-mini",
     messages=[{"role": "user", "content": "..."}],
     tools=[
         {
@@ -88,7 +88,7 @@ if "name" not in user_data:
 <td>
 
 ```python
-client = instructor.from_provider("openai/gpt-4")
+client = instructor.from_provider("openai/gpt-5.4-mini")
 
 user = client.chat.completions.create(
     response_model=User,

docs/blog/posts/best_framework.md

@@ -40,7 +40,7 @@ class User(BaseModel):
 client = instructor.from_provider("openai/gpt-5-nano")
 
 user = client.create(
-    model="gpt-3.5-turbo",
+    model="gpt-5.4-mini",
     response_model=User,  # (1)!
     messages=[
         {

docs/blog/posts/caching.md

@@ -123,7 +123,7 @@ class UserDetail(BaseModel):
 
 def extract(data) -> UserDetail:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": data},
@@ -156,7 +156,7 @@ import functools
 @functools.cache
 def extract(data):
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": data},
@@ -240,7 +240,7 @@ import functools
 
 
 @functools.lru_cache(maxsize=1000)  # Limit cache to 1000 entries
-def extract_with_limit(data: str, model: str = "gpt-3.5-turbo") -> UserDetail:
+def extract_with_limit(data: str, model: str = "gpt-5.4-mini") -> UserDetail:
     return client.create(
         model=model,
         response_model=UserDetail,
@@ -379,7 +379,7 @@ class UserDetail(BaseModel):
 @instructor_cache
 def extract(data) -> UserDetail:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": data},
@@ -542,7 +542,7 @@ class UserDetail(BaseModel):
 def extract(data) -> UserDetail:
     # Assuming client.chat.completions.create returns a UserDetail instance
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": data},
@@ -649,7 +649,7 @@ def extract_l2(data: str) -> UserDetail:
 @redis_decorator  # L3
 def extract_l3(data: str) -> UserDetail:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[{"role": "user", "content": data}],
     )
@@ -725,7 +725,7 @@ cache = AsyncInstructorCache()
 @cache.cache(ttl=3600)
 async def extract_async(data: str) -> UserDetail:
     return await client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[{"role": "user", "content": data}],
     )
@@ -742,7 +742,7 @@ Combine caching with [streaming responses](../../concepts/partial.md) for optima
 def extract_streamable(data: str) -> UserDetail:
     """Cache the final result while still allowing streaming for new requests."""
     return client.create_partial(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[{"role": "user", "content": data}],
         stream=True,

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

@@ -294,7 +294,7 @@ def summarize_article(article: str, summary_steps: int = 3):
     summary_chain = []
     # We first generate an initial summary
     summary: InitialSummary = client.create(  # (2)!
-        model="gpt-4-0613",
+        model="gpt-5.4-mini",
         response_model=InitialSummary,
         messages=[
             {
@@ -323,7 +323,7 @@ def summarize_article(article: str, summary_steps: int = 3):
             ]
         )
         new_summary: RewrittenSummary = client.create( # (3)!
-            model="gpt-4-0613",
+            model="gpt-5.4-mini",
             messages=[
                 {
                     "role": "system",
@@ -478,14 +478,14 @@ instructor jobs create-from-file generated.jsonl
 Once the job is complete, all we need to do is to then change the annotation in the function call to `distil_summarization` in our original file above to start using our new model.
 
 ```py
-@instructions.distil(model='gpt-3.5-turbo:finetuned-123', mode="dispatch")  # (1)!
+@instructions.distil(model='gpt-5.4-mini:finetuned-123', mode="dispatch")  # (1)!
 def distil_summarization(text: str) -> GeneratedSummary:
     summary_chain: List[str] = summarize_article(text)
     return GeneratedSummary(summary=summary_chain[-1])
 ```
 
 1. Don't forget to replace this with your new model id. OpenAI identifies fine tuned models with an id of
-   ft:gpt-3.5-turbo-0613:personal::<id> under their Fine-tuning tab on their dashboard
+   ft:gpt-5.4-mini:personal::<id> under their Fine-tuning tab on their dashboard
 
 With that, you've now got your own fine-tuned model ready to go and serve data in production. We've seen how Instructor can make your life easier, from fine-tuning to distillation.
 

docs/blog/posts/citations.md

@@ -122,7 +122,7 @@ class Statements(BaseModel):
                     "content": f"Does the following citation exist in the following context?\n\nCitation: {self.substring_quote}\n\nContext: {context}",
                 }
             ],
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
         )
 
         if resp.is_valid:
@@ -228,7 +228,7 @@ class AnswerWithCitaton(BaseModel):
                     "content": f"Does the following answers match the question and the context?\n\nQuestion: {self.question}\n\nAnswer: {self.answer}\n\nContext: {context}",
                 }
             ],
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
         )
 
         if resp.is_valid:

docs/blog/posts/distilation-part1.md

@@ -154,7 +154,7 @@ instructions = Instructions(
 )
 
 
-@instructions.distil(model='gpt-3.5-turbo:finetuned-123', mode="dispatch")  # (2)!
+@instructions.distil(model='gpt-5.4-mini:finetuned-123', mode="dispatch")  # (2)!
 def fn(a: int, b: int) -> Multiply:
     resp = a + b
     return Multiply(a=a, b=b, result=resp)
@@ -164,7 +164,7 @@ def fn(a: int, b: int) -> Multiply:
     automatically serialize the content back into the `Pydantic`` model that we're looking for.
 
 2.  Don't forget to replace this with your new model id. OpenAI identifies fine tuned models with an id
-    of `ft:gpt-3.5-turbo-0613:personal::<id>` under their **Fine-tuning** tab on their dashboard
+    of `ft:gpt-5.4-mini:personal::<id>` under their **Fine-tuning** tab on their dashboard
 
 With this, you can swap the function implementation, making it backward compatible. You can even imagine using the different models for different tasks or validating and running evals by using the original function and comparing it to the distillation.
 

docs/blog/posts/fake-data.md

@@ -40,7 +40,7 @@ client = instructor.from_provider("openai/gpt-5-nano")
 
 def generate_fake_users(count: int) -> Iterable[UserDetail]:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=Iterable[UserDetail],
         messages=[
             {"role": "user", "content": f"Generate a {count} synthetic users"},
@@ -79,7 +79,7 @@ client = instructor.from_provider("openai/gpt-5-nano")
 
 def generate_fake_users(count: int) -> Iterable[UserDetail]:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=Iterable[UserDetail],
         messages=[
             {"role": "user", "content": f"Generate a {count} synthetic users"},
@@ -100,7 +100,7 @@ By incorporating names of celebrities as examples, we have shifted towards gener
 
 ## Leveraging Complex Example
 
-To effectively generate synthetic examples with more nuance, lets upgrade to the "gpt-4-turbo-preview" model, use model level examples rather than attribute level examples:
+To effectively generate synthetic examples with more nuance, lets upgrade to the "gpt-5.4-mini" model, use model level examples rather than attribute level examples:
 
 ```Python
 import instructor
@@ -132,7 +132,7 @@ client = instructor.from_provider("openai/gpt-5-nano")
 
 def generate_fake_users(count: int) -> Iterable[UserDetail]:
     return client.create(
-        model="gpt-4-turbo-preview",
+        model="gpt-5.4-mini",
         response_model=Iterable[UserDetail],
         messages=[
             {"role": "user", "content": f"Generate `{count}` synthetic examples"},
@@ -175,7 +175,7 @@ client = instructor.from_provider("openai/gpt-5-nano")
 
 def generate_fake_users(count: int) -> Iterable[UserDetail]:
     return client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=Iterable[UserDetail],
         messages=[
             {"role": "user", "content": f"Generate `{count}` synthetic users"},

docs/blog/posts/full-fastapi-visibility.md

@@ -64,7 +64,7 @@ client = instructor.from_provider("openai/gpt-5-nano", async_client=True)
 @app.post("/user", response_model=UserDetail)
 async def endpoint_function(data: UserData) -> UserDetail:
     user_detail = await client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": f"Extract: `{data.query}`"},
@@ -103,7 +103,7 @@ client = instructor.from_provider("openai/gpt-4o")
 @app.post("/user", response_model=UserDetail)
 async def endpoint_function(data: UserData) -> UserDetail:
     user_detail = await client.create(
-        model="gpt-3.5-turbo",
+        model="gpt-5.4-mini",
         response_model=UserDetail,
         messages=[
             {"role": "user", "content": f"Extract: `{data.query}`"},
@@ -158,7 +158,7 @@ Sometimes, we might need to run multiple jobs in parallel. Let's see how we can
     async def extract_many_users(data: MultipleUserData):
         async def extract_user(query: str):
             user_detail = await client.create(
-                model="gpt-3.5-turbo",
+                model="gpt-5.4-mini",
                 response_model=UserDetail,
                 messages=[
                     {"role": "user", "content": f"Extract: `{query}`"},
@@ -205,7 +205,7 @@ Sometimes, we might need to run multiple jobs in parallel. Let's see how we can
     @app.post("/user", response_model=UserDetail)
     async def endpoint_function(data: UserData) -> UserDetail:
         user_detail = await client.create(
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
             response_model=UserDetail,
             messages=[
                 {"role": "user", "content": f"Extract: `{data.query}`"},
@@ -219,7 +219,7 @@ Sometimes, we might need to run multiple jobs in parallel. Let's see how we can
     async def extract_many_users(data: MultipleUserData):
         async def extract_user(query: str):
             user_detail = await client.create(
-                model="gpt-3.5-turbo",
+                model="gpt-5.4-mini",
                 response_model=UserDetail,
                 messages=[
                     {"role": "user", "content": f"Extract: `{query}`"},
@@ -277,7 +277,7 @@ Let's add a new endpoint to our server to see how this might work
         )  # (1)!
         client = instructor.from_provider("openai/gpt-4o")
         users = await client.create(
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
             response_model=Iterable[UserDetail],
             stream=True,
             messages=[
@@ -334,7 +334,7 @@ Let's add a new endpoint to our server to see how this might work
     @app.post("/user", response_model=UserDetail)
     async def endpoint_function(data: UserData) -> UserDetail:
         user_detail = await client.create(
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
             response_model=UserDetail,
             messages=[
                 {"role": "user", "content": f"Extract: `{data.query}`"},
@@ -348,7 +348,7 @@ Let's add a new endpoint to our server to see how this might work
     async def extract_many_users(data: MultipleUserData):
         async def extract_user(query: str):
             user_detail = await client.create(
-                model="gpt-3.5-turbo",
+                model="gpt-5.4-mini",
                 response_model=UserDetail,
                 messages=[
                     {"role": "user", "content": f"Extract: `{query}`"},
@@ -367,7 +367,7 @@ Let's add a new endpoint to our server to see how this might work
         logfire.instrument_openai(suppressed_client, suppress_other_instrumentation=False)
         client = instructor.from_provider("openai/gpt-4o")
         users = await client.create(
-            model="gpt-3.5-turbo",
+            model="gpt-5.4-mini",
             response_model=Iterable[UserDetail],
             stream=True,
             messages=[

docs/blog/posts/generator.md

@@ -138,7 +138,7 @@ client = OpenAI(
 )
 
 response_generator = client.create(
-    model='gpt-3.5-turbo',
+    model='gpt-5.4-mini',
     messages=[{'role': 'user', 'content': "What are some good reasons to smile?"}],
     temperature=0,
     stream=True,
@@ -268,7 +268,7 @@ prompt = (
 
 start_perf = time.perf_counter()
 recommendations_stream = client.create(
-    model="gpt-3.5-turbo-1106",
+    model="gpt-5.4-mini",
     temperature=0.1,
     response_model=Iterable[ProductRecommendation],
     stream=True,
@@ -297,7 +297,7 @@ Time for first result (generator): 4.33 seconds
 ```python
 start_perf = time.perf_counter()
 recommendations_list = client.create(
-    model="gpt-3.5-turbo-1106",
+    model="gpt-5.4-mini",
     temperature=0.1,
     response_model=Iterable[ProductRecommendation],
     stream=False,