567-labs--instructor/CHANGELOG.md

Changelog

All notable changes to instructor are documented here.

Format: Keep a Changelog Versioning: Semantic Versioning

---

[Unreleased]

Fixed

• Mistral/Vertex AI partial streaming: Avoid forwarding iterable-only parser arguments into completed Partial responses, preventing final Pydantic validation errors for sync and async streams.
• Batch providers: Handle missing optional SDKs safely, validate OpenAI batch input before client setup, report exhausted output-file retries clearly, and remove unreachable fallbacks.
• OpenAI/Writer tools: Raise clear response-parsing errors for completions with no choices or tool calls instead of leaking attribute and index errors.
• Fireworks streaming: Keep non-streaming async calls non-streaming and return streaming async generators without incorrectly awaiting them.
• GenAI uploads: Respect max_retries=0 without an unwanted sleep or polling request, allow recovery on the final permitted retry, and report nameless pending uploads clearly before polling.
• Gemini/GenAI messages: Honor an explicit system message for unstructured requests, remove the unsupported raw system argument, and reject invalid scalar message content clearly.
• Templating: Use populated contents when messages is empty, avoid mutating nested caller input, and preserve uncopyable metadata during template expansion.
• Anthropic system messages: Reject invalid new system-message values even when no existing system message is present.
• Python 3.9: Include the required type-evaluation backport in minimal installs, keep overload metadata available, and avoid runtime evaluation of unsupported union syntax in the core response path and offline tests.

Tests / CI

• Coverage and test quality: Run the complete offline suite on Python 3.9-3.13, enforce fork-safe statement and branch coverage plus supported-version type checks in pull-request CI, add strict resource and thread warning checks, and provide a manual retry-mutation workflow. Consolidate typed response, stream, and SDK fixtures; remove duplicate tests and unreachable provider paths; and replace coverage-only stubs with meaningful edge-case and transport-backed provider checks.

[1.15.5] - 2026-06-28

Fixed

• v2 imports: Defer OpenAI SDK imports from core v2 modules until an OpenAI-specific path actually needs them, reducing import side effects for non-OpenAI usage. (#2390)
• v2 response models: Treat list[A | B] PEP 604 unions of Pydantic models as iterable response models, matching list[Union[A, B]] schema behavior. (#2377)
• OpenAI Responses API: Align RESPONSES_TOOLS text.format with the forced tool schema and add targeted retry guidance when tool calls return empty {} arguments. (#2300, #2304)

---

[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)
• 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)
• 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)
• Docs: Refresh stale OpenAI and Ollama model strings in documentation examples. (#2395)

---

[1.15.3] - 2026-06-15

Fixed

• Bedrock: Route top_k/topK through additionalModelRequestFields instead of leaving it as a top-level Converse kwarg. AWS InferenceConfiguration only supports maxTokens/stopSequences/temperature/topP, so a leftover top_k reached client.converse(top_k=...) and boto3 raised ParamValidationError: Unknown parameter "top_k".
• Gemini/GenAI: Fold generation_config (and safety_settings/thinking_config) into config when response_model=None, so plain-text calls no longer raise generate_content() got an unexpected keyword argument 'generation_config' (#2366).
• 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, and multimodal autodetection.

Tests / CI

• Type checking: Upgrade to ty 0.0.44, enforce warning-free checks with GitHub annotations, cover V2 tests, validate supported Python versions and platforms, and strengthen installed-package public API typing tests.

---

[1.15.2] - 2026-05-10

Security

• Logging: Redact sensitive request fields from debug logs, including nested auth headers such as Authorization and x-api-key. (#2297)

Fixed

• Templating (GenAI/VertexAI): process_message no longer crashes with TypeError: Can't compile non template nodes when multimodal messages contain image/URI/bytes Parts alongside validation_context. Non-text Parts (where part.text is None) now pass through unchanged. (#2253)
• Retry: IncompleteOutputException now propagates directly to the caller without being wrapped in InstructorRetryException, making except IncompleteOutputException catch blocks work as documented. Applies to both sync and async paths. (#2273)
• Anthropic/Bedrock: Omit None fields from Anthropic tool-use retry payloads so Bedrock reasks no longer fail with HTTP 400 when caller=None. (#2301)
• Responses streaming: Surface reasoning-summary events in RESPONSES_TOOLS partial streaming and await callback return values when they are awaitable. (#2299)

[1.15.1] - 2026-04-03

Security

• Bedrock: Block remote HTTP(S) image URL fetching in _openai_image_part_to_bedrock — only data: URLs are now accepted, preventing SSRF via user-controlled image URLs
• Bedrock/PDF: Block remote URL and local file fetching in PDF.to_bedrock — only base64 data or s3:// sources are now supported, preventing SSRF and local file disclosure

Added

• Hooks: completion:error and completion:last_attempt handlers now receive attempt_number, max_attempts, and is_last_attempt as keyword arguments. Old-style handlers remain fully backward-compatible.
• Anthropic: from_provider("anthropic/...") now sets a User-Agent: instructor/<version> header on the Anthropic client

Fixed

• Anthropic usage: Initialize usage correctly for ANTHROPIC_REASONING_TOOLS and ANTHROPIC_PARALLEL_TOOLS modes — previously fell through to OpenAI usage tracking with wrong field names
• OpenRouter: Use reask_md_json for OPENROUTER_STRUCTURED_OUTPUTS retries instead of reask_default (tool-call format), fixing malformed retry prompts
• Templating: Return kwargs unchanged instead of None in handle_templating when message list is empty or format is unrecognized; process_message also now returns the original message unchanged for unrecognized formats instead of None
• from_openai: Allow Mode.JSON_SCHEMA for the OpenAI provider — it was incorrectly blocked by the mode validation check
• Bedrock: Pass through cachePoint dicts in message content unchanged — previously raised ValueError: Unsupported dict content for Bedrock, breaking prompt caching (regression since v1.13.0)
• Bedrock: Allow Mode.MD_JSON in from_bedrock
• Parallel tools: ParallelBase generator now consumed into ListResponse in both sync and async paths, fixing AttributeError when setting _raw_response on a generator

---

[1.15.0] - 2026-04-02

Security

• Pin litellm to <=1.82.6 to block compromised versions 1.82.7 and 1.82.8 (#2219)
• Make diskcache an optional dependency, removing it from all users' transitive dependency trees and mitigating CVE-2025-69872 (#2211)

Fixed

• Usage tracking: Preserve response.usage subclass type (e.g. LiteLLM, Langfuse) when accumulating token counts across retries — fixes downstream .get() method loss (#2217, #2199)
• Gemini: Exclude HARM_CATEGORY_IMAGE_* safety categories from standard Gemini API calls — these are Vertex AI-only and caused 400 INVALID_ARGUMENT errors (#2174)
• Gemini: Detect truncated responses (finish_reason=MAX_TOKENS) in GENAI_STRUCTURED_OUTPUTS mode and raise IncompleteOutputException immediately instead of retrying with malformed JSON (#2232)
• create_with_completion: Handle List[Model] response models that lack _raw_response attribute — previously raised AttributeError, now returns None for the completion (#2167)
• Partial streaming: Preserve default Literal field values (e.g. type: Literal["Person"] = "Person") during streaming instead of emitting None before the field arrives (#2204)
• Partial streaming: Support PEP 604 union syntax (str | int) in Partial models on Python 3.10+ (#2200)
• Validators: Fix allow_override=True in llm_validator — the override branch was unreachable due to a misplaced assertion, so fixed_value was never returned (#2215)
• Parallel tools: ParallelBase responses now return ListResponse (consistent with IterableBase) instead of a raw generator with _raw_response set on it (#2216)
• Multimodal: Add missing continue in convert_messages after handling typed (audio/image) messages — previously fell through to message["role"] causing KeyError (#2139)
• Anthropic: Fix dead code path for ANTHROPIC_REASONING_TOOLS mode — the mode was shadowed by a duplicate ANTHROPIC_TOOLS check and never routed correctly (#2140)

Added

• Models: Add Claude 4 (Opus, Sonnet, Haiku), OpenAI GPT-4.1 series, o3/o4 reasoning models, xAI Grok 3, and DeepSeek R1/V3 to KnownModelName type (#2235)

Docs

• Update GitHub organization links in README from instructor-ai to 567-labs (#2149)

Tests / CI

• Fix test_xai_optional_dependency tests to use monkeypatch so they pass regardless of whether xai-sdk is installed
• Update deprecated Anthropic model names (claude-3-5-haiku-latest -> claude-haiku-4-0-20250414, claude-3-7-sonnet-latest -> claude-sonnet-4-5-20250514)
• Update deprecated OpenAI model names (gpt-3.5-turbo -> gpt-4.1-mini) across unit tests
• Update stale provider model strings in shared_config.py: Writer palmyra-x5, Fireworks llama-v3p3, Perplexity sonar-pro

---

[1.14.5] - 2026-01-29

Fixed

• Google GenAI: thought_signature is now preserved across validation retries for thinking models (#2001)
• Metadata: pyproject.toml author field corrected so PyPI correctly populates the Author field (#2015)
• Deps: Dev dependencies moved to the correct [dependency-groups] section in pyproject.toml (#2030)

---

[1.14.4] - 2026-01-16

Fixed

• Responses API: Validation errors during structured output parsing are now caught and retried correctly (#2002)
• Google GenAI: User-provided GenerationConfig labels and custom fields are no longer silently dropped when merging configs (#2005)
• Google GenAI: SafetySettings now applied correctly when request contains image content (#2007)
• List responses: Response wrappers no longer crash on attribute-style access (#2011)
• _raw_response: Attribute access on list response wrappers works correctly (#2012)

Changed

• json_tracker: Sibling-heuristic algorithm simplified for improved partial-streaming reliability (#2000)

---

[1.14.3] - 2026-01-13

Added

• Partial streaming: Completeness-based streaming validation — fields are validated progressively rather than failing mid-stream (#1999)

Fixed

• Streaming reask: Stream objects in reask handlers are now consumed correctly before retry, preventing stale-stream errors (#1992)

---

[1.14.2] - 2026-01-13

Fixed

• Partial streaming: Model validators now skip during partial streaming and run only once on the final complete object, preventing spurious errors (#1994)
• Partial: Infinite recursion with self-referential models (e.g. TreeNode with children: List["TreeNode"]) is now prevented (#1997)

Tests / CI

• Provider tests skipped in CI when API secrets are not available (#1990)

---

[1.14.1] - 2026-01-08

Fixed

• Google GenAI: cached_content parameter now correctly forwarded to support Google context caching (#1987)

---

[1.14.0] - 2026-01-04

Added

• Bedrock: Document support — pass PDFs and text files directly to Bedrock models (#1936)

Fixed

• from_provider(): Now respects the base_url keyword argument for OpenAI-compatible providers (#1971)
• from_provider(): Runtime ImportError exceptions are no longer masked, making misconfigured installs easier to diagnose (#1975)
• Google GenAI: Union types now allowed in structured output schemas (#1973)
• Google GenAI: thinking_config and additional user-provided GenerationConfig fields now correctly preserved (#1972, #1974)
• Cohere: Streaming and V2 API version detection issues resolved (#1983, #1844)
• xAI: Tools-mode validation fixed (#1983)
• Exception handling: Standardized across all providers (#1897)

Changed

• Type checker: Switched from Pyright to ty for faster incremental type checking (#1978)
• Provider factories: from_openai, from_anthropic, etc. signatures standardized (#1898)

---

[1.13.0] - 2025-11-03

Added

• Bedrock: Image input support — converts OpenAI-style image parts to Bedrock's native format
• py.typed: Marker file restored for PEP 561 type-checking support (#1868)

Fixed

• disable_pydantic_error_url(): Now correctly suppresses Pydantic validation error URLs via monkey-patching ValidationError.__str__() (environment variable approach had no effect post-import)
• JSON mode: JSON decode errors now trigger retry logic instead of surfacing as unhandled exceptions (#1856)
• Gemini: Streaming fixed for the Google GenAI SDK (#1864)
• Gemini: HARM_CATEGORY_JAILBREAK safety category and Anthropic tool_result content blocks now handled correctly (#1867)
• Partial: Fields with default_factory no longer retain the factory when made optional during streaming
• OpenAI: Dependency version constraint updated to support v2 (#1858)

---

[1.12.0] - 2025-10-27

Fixed

• Python 3.13: Compatibility issues and import path corrections in multimodal processing
• Bedrock: OpenAI-compatible models now correctly parse responses where reasoning appears before text content
• Gemini: chunk.text ValueError when finish_reason=1 no longer crashes streaming
• Gemini: thinking_config no longer unintentionally passed to the tools helper
• OpenAI: parse:error hook now correctly fires for InstructorValidationError
• JSON parsing: Broken regex patterns removed from JSON extraction function
• Cohere: V2 API version detection improved (#1844)

---

[1.11.3] - 2025-09-04

Added

• Hooks: Hook combination via __add__ / combine() — merge multiple hook handlers together
• Hooks: Per-call hooks — pass hooks directly to individual .create() calls without registering globally
• Retry: InstructorRetryException now tracks all failed attempts including exceptions and raw completions for better introspection
• Docs: llms.txt support via mkdocs-llmstxt plugin for AI/LLM consumers

Fixed

• InstructorError.__str__(): Now correctly formats failed-attempt details
• Retry: Failed attempts propagated through reask handlers
• Imports: Backward compatibility imports restored for function_calls and validators modules

---

[1.11.1] - 2025-08-27

Changed

• Upgraded all dependencies to latest versions

---

[1.11.0] - 2025-08-27

Added

• OpenRouter: Provider support in from_provider() using OPENROUTER_API_KEY
• LiteLLM: Provider support in from_provider() (#1723)
• xAI: Provider utilities following standard provider structure (#1728)
• Batch API: In-memory batching support with improved error handling for OpenAI and Anthropic (#1746)
• Hooks: completion:error and completion:last_attempt hooks now fully implemented (#1729)

Changed

• Codebase reorganized from flat structure to modular provider-based architecture (#1730)
• Provider-specific message conversion logic moved to dedicated handlers (#1724)

Fixed

• Pydantic v2 deprecation warnings resolved by migrating from class Config to ConfigDict (#1782)