Instructor v1.17.0

Includes the fixes previously planned for 1.16.1, which was not published. The
previous published version is 1.16.0.

Upgrade Notes

• Cached responses use new keys and isolated per-client namespaces. Existing cache entries will miss. Set the same explicit cache_namespace only when clients are intended to share results; keep accounts, endpoints, and tenants isolated.
• Response models with Instructor async-validator decorators are rejected before provider calls or cache lookup, including nested models. Use Pydantic validators or explicitly await application-level validation after extraction; automatic async-validator execution is deferred.
• Remote media URLs must resolve to public addresses and cannot contain credentials. Redirects and connected peers are checked, and downloads have size limits.

Fixed

• Cache isolation: Include provider identity and prepared generation settings, including nested GenAI and Bedrock configuration; reuse the lookup key when storing after retries. Cache hits preserve current validation context and strictness. Clients have separate namespaces by default; use an explicit cache_namespace for intentional reuse across instances. Requests with unsupported opaque values bypass caching rather than using ambiguous identities. (#2585, #2586)

• GenAI cached content: Omit conflicting system instructions and tool declarations after resolving cached-content configuration, including plain responses, and preserve caller-owned configuration. Consolidates #2581, #2582, and #2591 for #2580.

• GenAI request configuration: Preserve caller-owned generation_config dictionaries when preparing tools and JSON requests, so repeated requests retain their sampling settings and token limits. (#2596)

• OpenAI SDK compatibility: Support OpenAI 3.x and its HTTPX2 transport when constructing sync and async clients through from_provider, while retaining OpenAI 2.x support on Python 3.9. (#2553)

• Async validation policy: Fail closed for @async_field_validator and @async_model_validator response models instead of silently skipping policy checks. The proposed automatic execution in #2588 is deferred in favor of main's security fix for #2528.

• Anthropic local PDFs: Read local PDF sources from disk instead of trying to fetch them over HTTP. (#2577)

Security

• Route Anthropic PDF downloads through the bounded public-network fetcher and pin each media connection to a validated IP before sending HTTP.
• Key cached responses by the complete prepared request, provider, validation context and strictness. Clients have isolated cache namespaces by default; cache_namespace explicitly enables sharing and must identify the endpoint and tenant. Revalidate cache hits with the current context and strictness.
• Reject response models containing unsupported async-validator markers, including nested models, instead of silently skipping their policy checks.
• Bound JSON extraction to 1 MiB of characters and 128 nesting levels, and avoid repeatedly scanning malformed suffixes.

Changed

• Current model examples: Refresh 16 provider guides, including GPT-5.6 Luna, Sonnet 5, Gemini 3.8 Flash, and current hosted model IDs. Correct Luna tool-call parameters, Sonnet adaptive thinking, and audio transcription guidance; add real model-ID smoke tests and code-block lint checks. Normalize Google test model overrides and default to Gemini 3.8 Flash.
• Documentation examples: Explain OpenAI-compatible JSON endpoints; correct typos, malformed client calls, missing imports, and code-block formatting across concepts and blog examples. Label displayed output separately from executable Python. (#2578, #2579, #2584, #2587, #2593)
• CLI cost metadata: Add an explicit mapping annotation to the model-cost table so static analysis preserves its nested numeric value shape. (#2521)
• Provider documentation: Correct the Mistral installation extra and xAI Python requirement, document Cerebras request-parameter forwarding with a runnable example, repair the Langfuse tracing examples, and clean up extraction typos. (#2550, #2554, #2556, #2561, #2562)
• Live-provider CI signal: Retry only failed tests once in the mixed-provider and auto-client lanes so transient API failures do not obscure deterministic regressions, while setup, collection, repeated, and other failures remain red.

Security

• Remote multimodal fetching: Block non-public and credential-bearing media URLs, revalidate redirects and connected peers, disable ambient proxy credentials, cap image, audio, and PDF downloads, and avoid caching decoded media payloads in process memory.
• Supply-chain hardening: Require a patched urllib3 release and pin GitHub Actions to reviewed commit SHAs, including secret-bearing scheduled workflows.
• Release workflow hardening: Avoid persisting checkout credentials, disable dependency-cache restoration in the PyPI publishing job, and pass release metadata to shell steps through environment variables instead of direct expression interpolation.

Additional Fixes

• Anthropic batch messages: Preserve every system instruction when converting batch requests instead of keeping only the final system message. (#2552)
• Anthropic batch accounting: Include canceled and expired requests in reported batch totals. (#2529)
• Bedrock request safety: Reject unsupported numerical, string-length, and minItems > 1 constraints locally for native structured outputs, and preserve caller-owned nested inference configuration while normalizing requests. (#2530, #2532)
• Cache key isolation: Include provider-hoisted system prompts in sync and async cache keys so requests with different instructions cannot share a cached response. (#2524)
• Gemini safety settings: Copy caller-provided safety mappings before applying default thresholds so request preparation cannot mutate reusable application configuration. (#2551)
• Google GenAI validation retries: Use the supported user role for function-response turns so Gemini can process correction requests. (#2557)
• TypedDict response models: Preserve total=False, Required, and NotRequired key semantics for single and iterable response models so valid partial outputs do not trigger retries. (#2567, #2568)
• Provider initialization: Reject provider strings with an empty provider or model component before client construction. (#2522)
• Remote multimodal media types: Accept valid case-insensitive HTTP Content-Type values with optional parameters when loading images, audio, and PDFs. (#2525)
• Message history: Preserve tool-call and other protocol fields when normalizing consecutive messages, and keep protocol messages as separate turns. (#2527)
• v2 mode registry: Keep lazily loaded modes registered while their handlers initialize, preventing concurrent first calls from failing spuriously. (#2536, #2535)