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

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

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.

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

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

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

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

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

What's Changed

• fix: Gemini HARM_CATEGORY_JAILBREAK and Anthropic tool_result blocks by @jxnl in #1867
• fix(genai): fix Gemini streaming by @DaveOkpare in #1864
• fix(processing): ensure JSON decode errors are caught by retry; add regression tests for JSON mode (#1856) by @devin-ai-integration[bot] in #1857
• fix: resolve type checking diagnostics by @jxnl in #1854
• fix: update openai dependency version constraints in pyproject.toml and uv.lock to support v2 by @vishnu-itachi in #1858
• feat: add py.typed marker for type checking by @jxnl in #1868
• feat(Bedrock): add image support to Bedrock by @geekbass in #1874
• chore(deps): bump the poetry group across 1 directory with 162 updates by @dependabot[bot] in #1859
• Fix/ci uv migration by @jxnl in #1886

New Contributors

• @vishnu-itachi made their first contribution in #1858
• @geekbass made their first contribution in #1874

Full Changelog: v1.12.0...v1.13.0

What's Changed

• feat: add mkdocs-llmstxt plugin and llms.txt support by @jxnl in #1795
• Restore multimodal import compatibility by @jxnl in #1797
• feat(retry): add comprehensive tracking of all failed attempts and exceptions by @jxnl in #1802
• feat(hooks): add hook combination and per-call hooks support by @jxnl in #1803
• feat(retry): propagate failed attempts through reask handlers by @jxnl in #1804
• fix(responses): generalize tool call parsing for reasoning models by @sapountzis in #1799
• feat(xai): add streaming support for xAI provider by @jeongyoonm in #1758
• fix(openai): reask functionality broken in JSON mode since v1.9.0 by @pnkvalavala in #1793
• fix(openai): remove duplicate schema from messages in JSON_SCHEMA mode by @pnkvalavala in #1761
• Handle Anthropic tool_use retries on ValidationError by @kelvin-tran in #1810
• Investigate instructor client import errors by @jxnl in #1818
• fix: replace deprecated gpt-3.5-turbo-0613 with gpt-4o-mini by @sergiobayona in #1830
• Update blog post link for LLM validation examples by @Mr-Ruben in #1824
• Debug parse error hook not emitted by @jxnl in #1819
• only use thinking_config in GenerateContentConfig by @jonbuffington in #1751
• fix: Handle Gemini chunk.text ValueError when finish_reason=1 by @jxnl in #1809
• docs: replace deprecated validation_context with context parameter by @devin-ai-integration[bot] in #1831
• docs(validation): add context parameter examples and fix error output by @devin-ai-integration[bot] in #1833
• also add pop thinking_config to handle_genai_tools by @oegedijk in #1834
• update cohere text models. by @phlogisticfugu in #1840
• fix(cohere): improve V2 API version detection and add documentation by @jxnl in #1844
• doc(openrouter): use explicit async_client=False by @wongjiahau in #1847
• Fix json parsing by @NicolasPllr1 in #1836
• fix: Bedrock OpenAI models response parsing (reasoning before text) by @len-foss in #1860
• fix: Python 3.13 compatibility and import path corrections by @jxnl in #1866

New Contributors

• @sapountzis made their first contribution in #1799
• @jeongyoonm made their first contribution in #1758
• @pnkvalavala made their first contribution in #1793
• @kelvin-tran made their first contribution in #1810
• @sergiobayona made their first contribution in #1830
• @Mr-Ruben made their first contribution in #1824
• @jonbuffington made their first contribution in #1751
• @phlogisticfugu made their first contribution in #1840
• @wongjiahau made their first contribution in #1847
• @NicolasPllr1 made their first contribution in #1836
• @len-foss made their first contribution in #1860

Full Changelog: 1.11.2...v1.12.0