refactor(v2): centralize provider client contracts

[jxnl-oai]

Summary

• replace provider-local client construction with declarative ProviderSpec and ClientSpec contracts
• centralize sync/async selection, mode validation, streaming method resolution, retries, hooks, and error propagation
• preserve provider-specific SDK behavior through thin adapters and explicit compatibility exceptions

Stack

1. Core architecture (this PR)
2. Documentation and parity inventory (targets this branch)
3. Shared behavioral contract tests (targets this branch)

The documentation and tests PRs are independent siblings and can be reviewed in parallel after this PR.

Verification

• ruff check instructor examples/v2-model-mode-benchmark/run.py
• ruff format --check instructor examples/v2-model-mode-benchmark/run.py
• ty check --python .venv
• Full deterministic parity is supplied by the sibling tests PR.

Supersedes #2315.

[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	b3c4409	Commit Preview URL Branch Preview URL	Jun 08 2026, 12:39 AM