v1.15.4

What's Changed

Instructor 1.15.4 is a patch release that consolidates the latest small fixes and docs cleanup after 1.15.3.

Runtime Fixes

• Fixed v2 response-model preparation so list and primitive response models are normalized before provider handler dispatch. This fixes crashes such as AttributeError: type object 'list' has no attribute 'model_json_schema' for list[Model] and scalar response models.
• Fixed streamed JSON extraction so backticks inside JSON string values are preserved instead of being interpreted as markdown fence delimiters.
• Fixed Image.autodetect() to accept raw JPEG, PNG, GIF, and WebP bytes, while raising clear errors for unsupported image inputs.
• Added regression coverage for the existing Gemini empty-message path.
• Fixed list[BaseModel] simple-type detection so model lists route through iterable handling instead of scalar wrapping.

CLI

• Fixed fine-tuning job creation from local files to pass the uploaded validation file ID to OpenAI instead of the local validation file path.
• Refreshed the CLI fine-tuning default model string in code and docs.

Docs

• Updated stale OpenAI model strings across docs and tutorials.
• Updated the Ollama example to use llama3.2, including the ollama pull command and from_provider() example.

Release

• Bumped package metadata to 1.15.4 in pyproject.toml, instructor/__init__.py, and uv.lock.
• Published the release to PyPI as both wheel and sdist.

Validation

PR #2398 passed Ruff, type-check, core tests, provider tests, live provider tests, auto client tests, and the Workers build before release.

Full Changelog: v1.15.3...v1.15.4

v1.15.3

What's Changed

• fix(templating): skip non-text Parts in GENAI/VertexAI mode by @jxnl in #2259
• chore(deps): bump the poetry group across 1 directory with 6 updates by @dependabot[bot] in #2258
• fix: preserve descriptions in responses tools mode by @jxnl in #2261
• test: cover partial streaming for PEP 604 unions by @jxnl in #2262
• build(docs): use uv for pages deploy by @jxnl in #2266
• fix(streaming): surface reasoning summary events in RESPONSES_TOOLS mode by @ayushh0110 in #2299
• fix(logging): redact api_key and sensitive keys in handle_response_model debug log by @xodn348 in #2297
• fix(anthropic): exclude None fields when serialising tool-use blocks on reask by @xodn348 in #2301
• build: bump litellm upper bound to 1.83.7 by @Kcstring in #2292
• fix(retry): let IncompleteOutputException propagate without wrapping by @RudrenduPaul in #2280
• refactor(v2): complete migration cleanup and typing coverage by @jxnl-oai in #2303
• ci: replace ai labeler with oss triage workflows by @jxnl-oai in #2349
• chore(types): strengthen ty coverage by @jxnl-oai in #2348
• fix(v2): consolidate minor runtime fixes by @jxnl in #2340
• fix(v2): consolidate latest runtime and docs fixes by @jxnl in #2373

New Contributors

• @ayushh0110 made their first contribution in #2299
• @xodn348 made their first contribution in #2297
• @Kcstring made their first contribution in #2292
• @RudrenduPaul made their first contribution in #2280
• @jxnl-oai made their first contribution in #2303

Full Changelog: v1.15.1...v1.15.3

v1.15.1

Security

• Bedrock: Block remote HTTP(S) image URL fetching in _openai_image_part_to_bedrock — only data: URLs 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 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
• OpenRouter: Use reask_md_json for OPENROUTER_STRUCTURED_OUTPUTS retries instead of reask_default (tool-call format)
• Templating: Return kwargs unchanged instead of None in handle_templating when message list is empty or unrecognized
• from_openai: Allow Mode.JSON_SCHEMA for the OpenAI provider
• Bedrock: Pass through cachePoint dicts in message content unchanged (regression since v1.13.0)
• Bedrock: Allow Mode.MD_JSON in from_bedrock
• Parallel tools: ParallelBase generator consumed into ListResponse in both sync and async paths, fixing AttributeError

Dependencies

• Bump anthropic 0.76.0 → 0.88.0
• Bump litellm upper bound to ≤1.83.0
• Bump aiohttp 3.13.3 → 3.13.5

v1.15.0

What's Changed

• Validation: Fix Validator to require is_valid field (#2230)
• Gemini: Handle GEMINI_TOOLS in async streaming paths (#2135)
• CLI: Add --full-id flag to show complete batch IDs (#2068)
• Providers: Remove opinionated system prompt from JSON mode (#2069)
• Mode: Add missing GENAI and Responses modes to tool_modes() (#2072)
• xAI: Make xai-sdk optional at runtime (#2043, #2094)
• Docs: Add canonical OpenAI starter example (#2117)
• Deps: Bump dependencies (#2042)

Full diff: v1.14.5...v1.15.0

v1.14.5

Changes

• fix(metadata): populate author field for PyPI stats

Separate author names from emails so hatchling populates the Author metadata field correctly. pypistats.org reads this field and was showing "None" because the names were only in author_email.

v1.14.4

What's Changed

• refactor(json_tracker): simplify using sibling heuristic by @thomasnormal in #2000
• Responses API validation error by @jxnl in #2002
• GenAI config labels loss by @jxnl in #2005
• GenAI SafetySettings image content by @jxnl in #2007
• List object crashes fix by @jxnl in #2011
• New release preparation by @jxnl in #2013

Full Changelog: v1.14.3...v1.14.4

v1.14.3

Added

• Completeness-based validation for Partial streaming - only validates JSON structures that are structurally complete (#1999)
• New JsonCompleteness class in instructor/dsl/json_tracker.py for tracking JSON completeness during streaming (#1999)

Fixed

• Fixed Stream objects crashing reask handlers when using streaming with max_retries > 1 (#1992)
• Field constraints (min_length, max_length, ge, le, etc.) now work correctly during streaming (#1999)

Deprecated

• PartialLiteralMixin is now deprecated - completeness-based validation handles Literal/Enum types automatically (#1999)

Full Changelog: v1.14.2...v1.14.3

v1.14.2

Fixed

• Fixed model validators crashing during partial streaming by skipping them until streaming completes (#1994)
• Fixed infinite recursion with self-referential models in Partial (e.g., TreeNode with children: List["TreeNode"]) (#1997)

Added

• Added PartialLiteralMixin documentation for handling Literal/Enum types during streaming (#1994)
• Added final validation against original model after streaming completes to enforce required fields (#1994)
• Added tests for recursive Partial models (#1997)

Full Changelog: v1.14.1...v1.14.2

v1.14.1

What's Changed

• fix(genai): Support cached_content for Google context caching by @b-antosik-marcura in #1987

New Contributors

• @b-antosik-marcura made their first contribution in #1987

Full Changelog: v1.14.0...v1.14.1

v1.14.0

What's Changed

• Audit and standardize exception handling in instructor library by @jxnl in #1897
• Standardize provider imports in documentation by @jxnl in #1896
• Fix the issue by @jxnl in #1914
• Standardize provider factory methods in codebase by @jxnl in #1898
• Update image base URL in ipnb tutorials by @jxnl in #1922
• docs: comprehensive documentation audit and SEO optimization by @jxnl in #1944
• Update documentation for responses API mode by @jxnl in #1946
• Doc / Removed model reference in client.create of extraction example. by @grokthetech-netizen in #1951
• fix(auto_client): stop masking runtime ImportErrors in from_provider by @yurekami in #1975
• fix: OpenAI provider in from_provider ignores base_url kwarg by @gardner in #1971
• fix(genai): allow Union types for Google GenAI structured outputs by @majiayu000 in #1973
• fix(genai): extract thinking_config and other fields from user-provided config object by @majiayu000 in #1974
• fix(genai): extract thinking_config from user-provided config object by @majiayu000 in #1972
• Fix typo in reask_validation.md by @mak2508 in #1956
• Feature/bedrock document support by @lucagobbi in #1936
• chore(typing): replace pyright with ty by @jxnl in #1978
• Fix Cohere streaming and xAI tools validation by @jxnl in #1983

New Contributors

• @grokthetech-netizen made their first contribution in #1951
• @yurekami made their first contribution in #1975
• @gardner made their first contribution in #1971
• @majiayu000 made their first contribution in #1973
• @mak2508 made their first contribution in #1956
• @lucagobbi made their first contribution in #1936

Full Changelog: v1.13.0...v1.14.0