fix(v2): consolidate additional runtime fixes

Author: jxnl-oai

CHANGELOG.md

@@ -10,7 +10,7 @@ Versioning: [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 ## [Unreleased]
 
 ### Fixed
-- **v2 cleanup**: Consolidate small provider/runtime fixes for Gemini JSON prompts, Cohere templating, JSON array extraction, iterable streaming, missing `jsonref` dependency guidance, and retry hook attempt metadata.
+- **v2 cleanup**: Consolidate small provider/runtime fixes for Gemini JSON prompts, Cohere templating, JSON array extraction, iterable streaming, missing `jsonref` dependency guidance, retry semantics and hook metadata, multimodal autodetection, and the Google GenAI default model.
 
 ---
 

instructor/v2/core/json.py

@@ -19,13 +19,12 @@ def extract_json_from_codeblock(content: str) -> str:
         for end_index in range(start_index + 1, len(content)):
             char = content[end_index]
 
-            if char == '"' and not escape_next:
-                in_string = not in_string
+            if escape_next:
+                escape_next = False
             elif char == "\\" and in_string:
                 escape_next = True
-                continue
-            else:
-                escape_next = False
+            elif char == '"':
+                in_string = not in_string
 
             if in_string:
                 continue
@@ -86,14 +85,14 @@ def extract_json_from_stream(chunks: Iterable[str]) -> Generator[str, None, None
                 continue
 
             if json_started:
-                if char == '"' and not escape_next:
-                    in_string = not in_string
+                if escape_next:
+                    escape_next = False
                 elif char == "\\" and in_string:
                     escape_next = True
                     buffer.append(char)
                     continue
-                else:
-                    escape_next = False
+                elif char == '"':
+                    in_string = not in_string
 
                 if in_codeblock and not in_string:
                     if char == "`":
@@ -174,14 +173,14 @@ async def extract_json_from_stream_async(
                 continue
 
             if json_started:
-                if char == '"' and not escape_next:
-                    in_string = not in_string
+                if escape_next:
+                    escape_next = False
                 elif char == "\\" and in_string:
                     escape_next = True
                     buffer.append(char)
                     continue
-                else:
-                    escape_next = False
+                elif char == '"':
+                    in_string = not in_string
 
                 if in_codeblock and not in_string:
                     if char == "`":

instructor/v2/core/multimodal.py

@@ -16,12 +16,15 @@
 from pathlib import Path
 from urllib.parse import urlparse
 import mimetypes
+
 import requests
 from pydantic import BaseModel, Field
 
 from instructor.v2.core.errors import MultimodalError
 from instructor.v2.core.mode import Mode
 
+mimetypes.add_type("image/webp", ".webp")
+
 F = TypeVar("F", bound=Callable[..., Any])
 K = TypeVar("K", bound=Hashable)
 V = TypeVar("V")
@@ -91,6 +94,8 @@ def autodetect(cls, source: str | Path) -> Image:
         if isinstance(source, Path):
             return cls.from_path(source)
 
+        raise ValueError(f"Unsupported image source type: {type(source).__name__}")
+
     @classmethod
     def autodetect_safely(cls, source: Union[str, Path]) -> Union[Image, str]:  # noqa: UP007
         """Safely attempt to autodetect an image from a source string or path.
@@ -280,6 +285,8 @@ def autodetect(cls, source: str | Path) -> Audio:
         if isinstance(source, Path):
             return cls.from_path(source)
 
+        raise ValueError(f"Unsupported audio source type: {type(source).__name__}")
+
     @classmethod
     def autodetect_safely(cls, source: Union[str, Path]) -> Union[Audio, str]:  # noqa: UP007
         """Safely attempt to autodetect an audio from a source string or path.
@@ -471,6 +478,8 @@ def autodetect(cls, source: str | Path) -> PDF:
         elif isinstance(source, Path):
             return cls.from_path(source)
 
+        raise ValueError(f"Unsupported PDF source type: {type(source).__name__}")
+
     @classmethod
     def autodetect_safely(cls, source: Union[str, Path]) -> Union[PDF, str]:  # noqa: UP007
         """Safely attempt to autodetect a PDF from a source string or path.

instructor/v2/core/provider_specs.py

@@ -204,7 +204,7 @@ def _openai_compat_spec(
             from_function="from_genai",
             client_module="instructor.v2.providers.genai.client",
             sdk_module="google.genai",
-            provider_string="google/gemini-2.0-flash",
+            provider_string="google/gemini-2.5-flash",
             basic_modes=(Mode.TOOLS, Mode.JSON),
             async_modes=(Mode.TOOLS, Mode.JSON),
         ),

instructor/v2/core/retry.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import json
 import logging
 from typing import TYPE_CHECKING, Any, TypeVar
 
@@ -21,9 +22,11 @@
 from instructor.v2.core.mode import Mode
 from instructor.v2.core.providers import Provider
 from instructor.v2.core.errors import (
+    AsyncValidationError,
     FailedAttempt,
     IncompleteOutputException,
     InstructorRetryException,
+    ResponseParsingError,
 )
 from instructor.v2.dsl.iterable import IterableBase
 from instructor.v2.dsl.response_list import ListResponse
@@ -41,10 +44,16 @@
 logger = logging.getLogger("instructor.v2.retry")
 
 T_Model = TypeVar("T_Model", bound=BaseModel)
+_RETRYABLE_PARSE_ERRORS = (
+    ValidationError,
+    json.JSONDecodeError,
+    AsyncValidationError,
+    ResponseParsingError,
+)
 
 
 def _max_attempts(max_retries: int | Retrying | AsyncRetrying) -> int | None:
-    return max(max_retries, 1) if isinstance(max_retries, int) else None
+    return max(max_retries, 0) + 1 if isinstance(max_retries, int) else None
 
 
 def _attempt_metadata(
@@ -121,7 +130,7 @@ def retry_sync_v2(
         provider: Provider enum
         mode: Mode enum
         context: Validation context
-        max_retries: Max retry attempts or Retrying instance
+        max_retries: Maximum retries after the initial attempt, or Retrying instance
         args: Positional args for func
         kwargs: Keyword args for func
         strict: Strict validation mode
@@ -143,13 +152,13 @@ def retry_sync_v2(
 
     # Setup retrying
     if isinstance(max_retries, int):
-        stop_condition = stop_after_attempt(max(max_retries, 1))
+        stop_condition = stop_after_attempt(max(max_retries, 0) + 1)
         timeout = kwargs.get("timeout")
         if isinstance(timeout, (int, float)):
             stop_condition = stop_condition | stop_after_delay(timeout)
         max_retries_instance = Retrying(
             stop=stop_condition,
-            retry=retry_if_exception_type(ValidationError),
+            retry=retry_if_exception_type(_RETRYABLE_PARSE_ERRORS),
             reraise=True,
         )
     else:
@@ -217,7 +226,7 @@ def retry_sync_v2(
 
                 except IncompleteOutputException:
                     raise
-                except ValidationError as e:
+                except _RETRYABLE_PARSE_ERRORS as e:
                     logger.debug(f"Validation error on attempt {attempt_number}: {e}")
                     failed_attempts.append(
                         FailedAttempt(
@@ -237,15 +246,6 @@ def retry_sync_v2(
                                 is_last_attempt=max_attempts == attempt_number,
                             ),
                         )
-                        hooks.emit_completion_error(
-                            e,
-                            **_attempt_metadata(
-                                attempt_number=attempt_number,
-                                max_attempts=max_attempts,
-                                is_last_attempt=max_attempts == attempt_number,
-                            ),
-                        )
-
                     # Prepare reask using registry
                     kwargs = handlers.reask_handler(
                         kwargs=kwargs,
@@ -260,11 +260,10 @@ def retry_sync_v2(
         raise
     except Exception as e:
         # Max retries exceeded or non-validation error occurred
-        if last_exception is None:
-            last_exception = e
+        last_exception = e
 
         logger.error(
-            f"Max retries exceeded. Total attempts: {len(failed_attempts)}, "
+            f"Max retries exceeded. Total attempts: {last_attempt_number}, "
             f"Last error: {last_exception}"
         )
         if hooks:
@@ -280,7 +279,7 @@ def retry_sync_v2(
         raise InstructorRetryException(
             str(last_exception),
             last_completion=failed_attempts[-1].completion if failed_attempts else None,
-            n_attempts=len(failed_attempts),
+            n_attempts=last_attempt_number,
             total_usage=total_usage,
             messages=extract_messages(kwargs),
             create_kwargs=kwargs,
@@ -292,7 +291,7 @@ def retry_sync_v2(
     raise InstructorRetryException(
         str(last_exception) if last_exception else "Unknown error",
         last_completion=failed_attempts[-1].completion if failed_attempts else None,
-        n_attempts=len(failed_attempts),
+        n_attempts=last_attempt_number,
         total_usage=total_usage,
         messages=extract_messages(kwargs),
         create_kwargs=kwargs,
@@ -376,7 +375,7 @@ async def retry_async_v2(
         provider: Provider enum
         mode: Mode enum
         context: Validation context
-        max_retries: Max retry attempts or AsyncRetrying instance
+        max_retries: Maximum retries after the initial attempt, or AsyncRetrying instance
         args: Positional args for func
         kwargs: Keyword args for func
         strict: Strict validation mode
@@ -398,13 +397,13 @@ async def retry_async_v2(
 
     # Setup retrying
     if isinstance(max_retries, int):
-        stop_condition = stop_after_attempt(max(max_retries, 1))
+        stop_condition = stop_after_attempt(max(max_retries, 0) + 1)
         timeout = kwargs.get("timeout")
         if isinstance(timeout, (int, float)):
             stop_condition = stop_condition | stop_after_delay(timeout)
         max_retries_instance = AsyncRetrying(
             stop=stop_condition,
-            retry=retry_if_exception_type(ValidationError),
+            retry=retry_if_exception_type(_RETRYABLE_PARSE_ERRORS),
             reraise=True,
         )
     else:
@@ -472,7 +471,7 @@ async def retry_async_v2(
 
                 except IncompleteOutputException:
                     raise
-                except ValidationError as e:
+                except _RETRYABLE_PARSE_ERRORS as e:
                     logger.debug(f"Validation error on attempt {attempt_number}: {e}")
                     failed_attempts.append(
                         FailedAttempt(
@@ -492,15 +491,6 @@ async def retry_async_v2(
                                 is_last_attempt=max_attempts == attempt_number,
                             ),
                         )
-                        hooks.emit_completion_error(
-                            e,
-                            **_attempt_metadata(
-                                attempt_number=attempt_number,
-                                max_attempts=max_attempts,
-                                is_last_attempt=max_attempts == attempt_number,
-                            ),
-                        )
-
                     # Prepare reask using registry
                     kwargs = handlers.reask_handler(
                         kwargs=kwargs,
@@ -515,11 +505,10 @@ async def retry_async_v2(
         raise
     except Exception as e:
         # Max retries exceeded or non-validation error occurred
-        if last_exception is None:
-            last_exception = e
+        last_exception = e
 
         logger.error(
-            f"Max retries exceeded. Total attempts: {len(failed_attempts)}, "
+            f"Max retries exceeded. Total attempts: {last_attempt_number}, "
             f"Last error: {last_exception}"
         )
         if hooks:
@@ -535,7 +524,7 @@ async def retry_async_v2(
         raise InstructorRetryException(
             str(last_exception),
             last_completion=failed_attempts[-1].completion if failed_attempts else None,
-            n_attempts=len(failed_attempts),
+            n_attempts=last_attempt_number,
             total_usage=total_usage,
             messages=extract_messages(kwargs),
             create_kwargs=kwargs,
@@ -547,7 +536,7 @@ async def retry_async_v2(
     raise InstructorRetryException(
         str(last_exception) if last_exception else "Unknown error",
         last_completion=failed_attempts[-1].completion if failed_attempts else None,
-        n_attempts=len(failed_attempts),
+        n_attempts=last_attempt_number,
         total_usage=total_usage,
         messages=extract_messages(kwargs),
         create_kwargs=kwargs,

instructor/v2/dsl/iterable.py

@@ -176,13 +176,13 @@ def get_object(s: str, stack: int) -> tuple[Optional[str], str]:
         in_string = False
         escape_next = False
         for i, c in enumerate(s):
-            if c == '"' and not escape_next:
-                in_string = not in_string
+            if escape_next:
+                escape_next = False
             elif c == "\\" and in_string:
                 escape_next = True
                 continue
-            else:
-                escape_next = False
+            elif c == '"':
+                in_string = not in_string
 
             if in_string:
                 continue

tests/llm/test_gemini/util.py

@@ -1,5 +1,5 @@
 import os
 import instructor
 
-models: list[str] = [os.getenv("GOOGLE_GENAI_MODEL", "google/gemini-2.0-flash")]
+models: list[str] = [os.getenv("GOOGLE_GENAI_MODEL", "google/gemini-2.5-flash")]
 modes = [instructor.Mode.GENAI_STRUCTURED_OUTPUTS]

tests/llm/test_genai/test_reask.py

@@ -9,7 +9,7 @@ def test_genai_tools_validation_retry_preserves_model_content(mode):
     """Ensure GENAI_TOOLS validation retries are wired end-to-end."""
     from instructor.core.exceptions import InstructorRetryException
 
-    model = os.getenv("GOOGLE_GENAI_MODEL", "gemini-2.0-flash")
+    model = os.getenv("GOOGLE_GENAI_MODEL", "gemini-2.5-flash")
 
     class AlwaysInvalid(BaseModel):
         value: int

tests/llm/test_genai/util.py

@@ -1,5 +1,5 @@
 import os
 import instructor
 
-models = [os.getenv("GOOGLE_GENAI_MODEL", "google/gemini-2.0-flash")]
+models = [os.getenv("GOOGLE_GENAI_MODEL", "google/gemini-2.5-flash")]
 modes = [instructor.Mode.GENAI_STRUCTURED_OUTPUTS]

tests/v2/test_core_multimodal_runtime.py

@@ -44,6 +44,29 @@ def test_convert_contents_rejects_unknown_object() -> None:
         convert_contents([object()], Mode.TOOLS)  # type: ignore[list-item]
 
 
+@pytest.mark.parametrize(
+    ("media_type", "autodetect"),
+    [
+        ("image", Image.autodetect),
+        ("audio", Audio.autodetect),
+        ("PDF", PDF.autodetect),
+    ],
+)
+def test_autodetect_rejects_unsupported_source_types(
+    media_type: str, autodetect: Any
+) -> None:
+    with pytest.raises(
+        ValueError, match=rf"Unsupported {media_type} source type: bytes"
+    ):
+        autodetect(b"not a string or path")
+
+
+def test_webp_mime_type_is_registered() -> None:
+    import mimetypes
+
+    assert mimetypes.guess_type("image.webp")[0] == "image/webp"
+
+
 def test_autodetect_media_uses_mime_type_shortcut(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None: