[codex] consolidate docs and audio validation fixes

[jxnl]

Summary

Consolidates four compact, low-risk maintenance fixes from the open queue:

• Replaces bare assert validation in Audio.from_url() and Audio.from_path() with explicit ValueError / FileNotFoundError, matching the existing Image/PDF behavior. Supersedes fix(multimodal): raise explicit errors in Audio instead of assert #2361.
• Fixes outdated Google/GenAI/Vertex docs around legacy mode names, Union vs Optional support, streaming guidance, model wording, and the Vertex migration example syntax. Supersedes docs(google): fix incorrect mode enums and outdated limitations in Google provider docs #2389 and partially addresses Documentation (at least Google-related) is an outdated mess. #2289.
• Fixes the malformed semantic validation blog link. Supersedes docs: fix semantic validation link #2310.
• Fixes a duplicated word in the CRM example prompt. Supersedes docs(examples): fix duplicate word in CRM example prompt #2325.

Superseded PRs / Issues

• Supersedes fix(multimodal): raise explicit errors in Audio instead of assert #2361, docs(google): fix incorrect mode enums and outdated limitations in Google provider docs #2389, docs: fix semantic validation link #2310, and docs(examples): fix duplicate word in CRM example prompt #2325.
• Partially addresses Documentation (at least Google-related) is an outdated mess. #2289. I did not close Documentation (at least Google-related) is an outdated mess. #2289 because the issue is broad and may still need a follow-up pass after these focused docs corrections land.

Validation

• git diff --check
• UV_CACHE_DIR=/private/tmp/uv-cache uv run pytest tests/v2/test_core_multimodal_runtime.py -q -> 23 passed
• UV_CACHE_DIR=/private/tmp/uv-cache uv run ruff check instructor/v2/core/multimodal.py tests/v2/test_core_multimodal_runtime.py examples/crm/run.py
• pre-commit on commit: Ruff check, Ruff format, uv.lock check skipped, dependency install/export hooks skipped, ty passed
• targeted content check confirmed the old malformed docs link, duplicated CRM phrase, stale Gemini Flash-8b wording, and broken Vertex one-line call no longer appear in the touched docs/examples

Skipped Items

Skipped as too broad for this consolidation pass:

• Provider additions or large provider work: feat(azure): add Azure AI Foundry provider support #2384/Add Azure AI Foundry as a first-class v2 provider #2383 Azure AI Foundry, Mistral AI v2 support #2365/feat: support mistralai v2 #2298 Mistral v2, feat(orcarouter): add OrcaRouter provider integration #2322 OrcaRouter, feat(minimax): add MiniMax provider support #2306/feat: add MiniMax provider support #2260 MiniMax, feat(providers): add Manifest provider support #2283 Manifest, feat(batch): support for mistral api #2168 Mistral batch, feat(bedrock): add native structured outputs and strict tool use modes #2086/feat(bedrock): Add support for AWS Bedrock native structured outputs #2084/Allow MD_JSON for bedrock client #2076 Bedrock native/MD_JSON.
• Larger features or architectural changes: feat: schema complexity analyzer + automatic mode selection #2394/feat: schema complexity pre-flight analysis and automatic mode selection #2393 schema complexity mode selection, feat: expose cumulative token usage on success + budget enforcement #2392/feat: expose cumulative token usage on successful responses + budget enforcement #2391 token usage and budget enforcement, docs(v2): document provider-owned client architecture #2357/test(v2): validate provider-owned client architecture #2356/refactor(v2): centralize provider client contracts #2355 provider-owned client architecture, fix: preserve true partial streaming behavior #2263 partial streaming behavior, Token-efficient serialization to reduce structured output overhead in production pipelines #2272 token-efficient serialization, Feature request: OWASP ASI06 memory poisoning defense for structured output agents #2316 MemoryGuard/OWASP memory poisoning.
• Nontrivial security/product decisions: feat(security): add MemoryGuard and sensitive_field_guard for OWASP ASI06 prompt injection defense #2321 MemoryGuard, fix(validation): harden llm_validator prompt isolation #2307 validator prompt isolation, Security: Retry amplification and LLM validator injection findings #2056 retry amplification and validator injection findings.
• Dependency or broad maintenance updates: chore(deps): bump the poetry group across 1 directory with 35 updates #2388 Poetry dependency batch, docs(contributing): update contributing setup instructions to reflect the uv migration #2354 contributing workflow rewrite, chore: improve instructor maintenance path #2351 vague maintenance-path tests.
• Third-party/product documentation additions: docs: add Entroly reference to prompt caching guide #2346 Entroly, docs: add Doubleword integration guide #2281 Doubleword, docs(examples): add medication-adherence triage example for Anthropic Claude #2311 medication-adherence example, Add modern FastAPI integration example with dependency injection #2305 FastAPI dependency-injection example.
• fix(docs): correct Vertex AI migration, update Known Limitations, clarify Google providers #2343 remains open as a possible narrower follow-up for provider-prefix / Vertex migration wording after the smaller Google docs correction lands; it was not taken wholesale because it rewrites more than this pass needs.

Draft Release Notes

• Audio validation now raises explicit exceptions instead of relying on assert, so invalid audio inputs are rejected consistently even when Python runs with optimizations enabled.
• Google provider docs now use the current generic mode names and clarify Union, Optional, streaming, and Vertex migration guidance.
• Fixed two small docs/example quality issues: a broken semantic validation link and a duplicated word in the CRM example prompt.

Draft Tweet

small instructor cleanup this week

fixed audio validation so it does not depend on python asserts, cleaned up a few google docs lies, and patched a couple tiny docs papercuts

not flashy, but this is the kind of maintenance that keeps examples and error paths honest

---

Note

Low Risk
Runtime change is limited to clearer multimodal error paths (callers that relied on asserts under python -O now get exceptions); the rest is documentation and a trivial example string fix.

Overview
Bundles several small maintenance fixes: v2 Audio loading now matches Image/PDF by raising ValueError and FileNotFoundError (and rejecting empty files) instead of assert, with new runtime tests and an [Unreleased] changelog note.

Documentation updates correct Google/GenAI/Vertex guidance—generic Mode.TOOLS, legacy Mode.GENAI_* deprecation wording, Union vs Optional, streaming with Mode.JSON, trimmed Gemini limitations, fixed Vertex migration examples, and a broken semantic-validation blog link. patching.md drops stale provider-specific mode names. The CRM example prompt drops a duplicated word.

^{Reviewed by Cursor Bugbot for commit 15e9f4a. Configure here.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	instructor	ba72f9d	Commit Preview URL Branch Preview URL	Jul 29 2026, 03:55 AM