Skip to content

armgit / dspy

Public Imported from GitHub
0

DSPy: The framework for programming—not prompting—language models

Python

Vendor lm15 as a package subtree (#10359)

Maxime Rivestd28abc9aa92a
diff --git a/.github/workflows/vendored_lm15.yml b/.github/workflows/vendored_lm15.yml
new file mode 100644
index 000000000..358bc350f
--- /dev/null
+++ b/.github/workflows/vendored_lm15.yml
@@ -0,0 +1,39 @@
+name: Verify bundled lm15
+
+on:
+ pull_request:
+ paths:
+ - 'dspy/_vendor/**'
+ - 'dspy/lm15.py'
+ - 'dspy/__init__.py'
+ - 'pyproject.toml'
+ - 'scripts/update_vendored_lm15.py'
+ - 'tests/test_vendored_lm15.py'
+ - '.github/workflows/vendored_lm15.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ installed-wheel:
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+ with:
+ persist-credentials: false
+ - uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+ with:
+ python-version: '3.12'
+ - name: Build source distribution and wheel
+ # By default, uv builds the wheel from the source distribution.
+ run: uv build
+ - name: Test the installed wheel outside the checkout
+ run: |
+ uv venv --python 3.12 "$RUNNER_TEMP/lm15-wheel-venv"
+ uv pip install --python "$RUNNER_TEMP/lm15-wheel-venv/bin/python" dist/*.whl pytest
+ mkdir "$RUNNER_TEMP/lm15-wheel-tests"
+ cp tests/test_vendored_lm15.py "$RUNNER_TEMP/lm15-wheel-tests/"
+ cd "$RUNNER_TEMP/lm15-wheel-tests"
+ "$RUNNER_TEMP/lm15-wheel-venv/bin/python" -I -m pytest -q test_vendored_lm15.py
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 7dcbe254a..5b07e462e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -9,7 +9,7 @@ repos:
name: ruff (lint)
types_or: [python, pyi]
files: ^(dspy|tests)/.*\.py$
- exclude: ^(dspy/__metadata__\.py|tests/reliability/.*\.py)$
+ exclude: ^(dspy/__metadata__\.py|dspy/_vendor/.*|tests/reliability/.*\.py)$
args: [--fix-only]
- repo: https://github.com/pre-commit/pre-commit-hooks
diff --git a/dspy/__init__.py b/dspy/__init__.py
index 3b29e08ed..418f4b518 100644
--- a/dspy/__init__.py
+++ b/dspy/__init__.py
@@ -1,3 +1,4 @@
+from dspy import lm15 as lm15
from dspy.predict import *
from dspy.primitives import *
from dspy.retrievers import *
diff --git a/dspy/_vendor/UPDATING.md b/dspy/_vendor/UPDATING.md
new file mode 100644
index 000000000..7b0923d33
--- /dev/null
+++ b/dspy/_vendor/UPDATING.md
@@ -0,0 +1,48 @@
+# Updating lm15
+
+Do not edit `lm15/` by hand. Make changes in the source repository and sync
+`cmpnd-ai/lm15-python` first.
+
+From the DSPy root, with all changes committed:
+
+```sh
+python scripts/update_vendored_lm15.py main
+```
+
+Pass a full source commit instead of `main` for a reproducible import.
+The command fetches the cmpnd fork, splits its `lm15/` package history, and
+uses `git subtree add` (first import) or `git subtree merge` (updates), with
+squashed history. It creates local commits; it never pushes.
+
+The first run replaces the old copied snapshot in a separate commit before
+adding the subtree. Review the resulting diff before pushing. If a merge
+conflicts, inspect Git's status and resolve or abort the merge before retrying;
+the tool does not discard conflicts automatically.
+
+`lm15-provenance.txt` records the source URL, package version, Python commit,
+contract pin and package split commit. The commit identifies the exact snapshot;
+several snapshots can share the same package version. `lm15-LICENSE` preserves the source repository's license.
+Both live outside the subtree to keep its contents faithful to upstream.
+The full upstream package is imported, including any non-Python files tracked
+there. Packaging determines which files ship to users.
+
+Use DSPy's normal **squash-and-merge** workflow for import/update PRs.
+The updater does not require subtree commits or their messages to survive.
+It fetches the previously recorded Python commit, reproduces its package split,
+and verifies that the existing vendor tree matches it. It then reconnects a
+package-root merge base before running the subtree merge. These extra local
+bookkeeping commits can be discarded by the next squash merge too.
+
+The recorded source commit must remain available in the source repository.
+If that commit cannot be fetched, or vendor files have been edited locally,
+the updater stops rather than guessing a merge base or overwriting changes.
+
+The `Verify bundled lm15` workflow builds a source distribution, builds a wheel
+from it, and tests a fresh installation outside the checkout. It checks public
+exports, request/response conversion, pickle round trips, and license/provenance
+files. No provider keys or network LM calls are needed.
+
+`dspy.lm15` re-exports lm15's public top-level names; it does not alias lm15's
+whole submodule tree. Use `from dspy.lm15 import Request`, not
+`from dspy.lm15.types import Request`. Existing DSPy LM behavior is unchanged
+by the vendor import.
diff --git a/dspy/_vendor/__init__.py b/dspy/_vendor/__init__.py
new file mode 100644
index 000000000..29a0a3e2a
--- /dev/null
+++ b/dspy/_vendor/__init__.py
@@ -0,0 +1,7 @@
+"""Third-party code shipped inside dspy.
+
+`lm15` is a subtree of https://github.com/cmpnd-ai/lm15-python, importable
+as `dspy.lm15`. Do not edit it here: changes go to that repository, and
+`scripts/update_vendored_lm15.py` refreshes the subtree. `lm15-provenance.txt`
+records the package version, source commit, contract pin, and package split.
+"""
diff --git a/dspy/_vendor/lm15-LICENSE b/dspy/_vendor/lm15-LICENSE
new file mode 100644
index 000000000..36e5ed963
--- /dev/null
+++ b/dspy/_vendor/lm15-LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lm15 contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/dspy/_vendor/lm15-provenance.txt b/dspy/_vendor/lm15-provenance.txt
new file mode 100644
index 000000000..9c31665f4
--- /dev/null
+++ b/dspy/_vendor/lm15-provenance.txt
@@ -0,0 +1,5 @@
+source=https://github.com/cmpnd-ai/lm15-python.git
+version=1.0.0a1
+commit=d188744accf1062a3ee119fd5c6533561f2a32a6
+contract=e24b60e24b39a3e2b7bff8335bc84330b53bff39
+split=c5ab18aaa62ce530e014a416fcca2a48d24a711c
diff --git a/dspy/_vendor/lm15/__init__.py b/dspy/_vendor/lm15/__init__.py
new file mode 100644
index 000000000..be42d5195
--- /dev/null
+++ b/dspy/_vendor/lm15/__init__.py
@@ -0,0 +1,280 @@
+"""lm15 — a provider-neutral, low-level foundation for talking to LLM APIs.
+
+lm15 is deliberately NOT a user-facing convenience layer. It is the dependency
+for libraries that want to build their own take on the right Python API for
+AI systems: one canonical representation (Request/Response/Message/Part,
+stream events, errors), exact serde for it, and adapters that translate it to
+and from each provider's wire format — stdlib-only, with its own HTTP
+transport. Build your DSL on top; let lm15 handle the providers.
+
+Conformance to the canonical representation is pinned by the lm15-contract
+corpus; this package is the reference implementation, not the spec.
+
+Quick tour:
+
+ from lm15 import AnthropicLM, Request, Message
+
+ lm = AnthropicLM(api_key="...")
+ response = lm.complete(Request(model="claude-sonnet-4-5",
+ messages=(Message.user("hello"),)))
+ response.text # canonical accessors
+ for event in lm.stream(request): ... # canonical stream events
+
+The top level is curated for application developers. Deeper audiences
+import one module (API review, 2026-07-13):
+`lm15.serde` (the complete to_dict/from_dict pairs), `lm15.providers`
+(BaseProviderLM, ProviderDialect, transports protocols, Credential),
+`lm15.errors` (map_http_error and friends), `lm15.registry` (the one
+table of named providers: PROVIDERS / ProviderDefinition — dialect,
+access policy, compat preset, console URL), `lm15.router` (the
+RouteRule/DEFAULT_RULES tables and the ADAPTERS/CHAT_PRESET_ROUTES views
+of the registry),
+`lm15.profiles` / `lm15.compat` (profile and compat-policy machinery),
+`lm15.sse`, `lm15.transports` (HTTP plumbing), `lm15.live` (realtime
+sessions; optional `websockets` dependency), `lm15.auth` (local
+subscription credentials: locked, atomic, double-checked refresh),
+`lm15.authkit` (login-flow primitives: PKCE, device-code polling,
+loopback listener, credential store), `lm15.doctor` (`explain_auth`:
+rung-by-rung credential resolution, no secrets rendered), and
+`lm15.vet` (the conformance shim CLI: `python -m lm15.vet`).
+
+Migrating from the OpenAI SDK or litellm:
+`LMRouter().complete_from_openai_chat(model, messages, **kwargs)` takes
+their supported request options (their model strings too) and answers with
+a `Response`. With `stream=True` it returns a lazy `ResponseStream`:
+iterate text, then read `.response`; use `with` for early-exit cleanup.
+`RouterConfig(api_keys={"openai": key})` supplies both OpenAI APIs;
+exact endpoint entries still override shared credentials.
+Underneath: `request_from_openai_chat(body, compat=...)` reads the JSON a
+client would POST to `/chat/completions` into a `Request`, or refuses
+with the key named (MAP-12), and
+`response_from_openai_chat(body)` reads a Chat Completions response body
+(a server's, or litellm's `ModelResponse.model_dump()`) into a `Response`
+with the same reader the OpenAI Chat adapter uses (docs/migrating-from-
+openai-chat.md). They are the only place lm15 reads a foreign format.
+
+The lowercase part-factory helpers (`text`, `image`, `tool_call`, ...) live in
+`lm15.types`, not at the top level — generic lowercase names at package top
+level invite collisions with user code.
+"""
+
+from ._version import __version__
+
+# ── Canonical types ──────────────────────────────────────────────────
+from .batch import AsyncBatchJob, BatchJob
+from .video_jobs import AsyncVideoJob, VideoJob
+from .live import Turn
+from .types import (
+ # request/response core
+ Request,
+ Response,
+ Message,
+ Usage,
+ Config,
+ CacheConfig,
+ Reasoning,
+ ToolChoice,
+ ErrorDetail,
+ ContinuationState,
+ # parts
+ TextPart,
+ ThinkingPart,
+ RefusalPart,
+ CitationPart,
+ ImagePart,
+ AudioPart,
+ VideoPart,
+ DocumentPart,
+ BinaryPart,
+ ToolCallPart,
+ ToolResultPart,
+ # tools
+ FunctionTool,
+ BuiltinTool,
+ ToolCallInfo,
+ # logprobs
+ TokenLogprob,
+ TopLogprob,
+ # streaming
+ StreamStartEvent,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ TextDelta,
+ ThinkingDelta,
+ AudioDelta,
+ ImageDelta,
+ ToolCallDelta,
+ CitationDelta,
+ ContinuationDelta,
+ # auxiliary endpoints
+ FileUploadRequest,
+ FileInfo,
+ FilePage,
+ CacheInfo,
+ CachePage,
+ CachedPrefix,
+ BatchRequest,
+ BatchEntry,
+ BatchJobInfo,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ AudioFormat,
+ # live session types
+ LiveConfig,
+ # part factory for tool results (the one lowercase factory beginners
+ # need at the top level; the rest stay in lm15.types)
+ tool_result,
+ # vocabulary aliases + constants
+ Role,
+ PartType,
+ FinishReason,
+ ReasoningEffort,
+ ErrorCode,
+ StreamEventType,
+ ROLE_VALUES,
+ FINISH_REASONS,
+ ERROR_CODES,
+)
+
+# ── Access policies (auth by composition; spec/auth.md AUTH-10) ──────
+from .features import AccessPolicy, EndpointSupport
+
+# ── Errors ───────────────────────────────────────────────────────────
+from .errors import (
+ LM15Error,
+ StreamAssemblyError,
+ TransportError,
+ LockTimeoutError,
+ ConfigurationError,
+ CapabilityError,
+ ProviderError,
+ AuthError,
+ BillingError,
+ RateLimitError,
+ InvalidRequestError,
+ ContextLengthError,
+ TimeoutError,
+ ServerError,
+ UnsupportedModelError,
+ UnsupportedFeatureError,
+ NotConfiguredError,
+ RETRYABLE_ERRORS,
+)
+
+# ── Providers ────────────────────────────────────────────────────────
+from .providers import (
+ OpenAILM,
+ OpenAIChatLM,
+ AnthropicLM,
+ GeminiLM,
+ ClaudeCodeLM,
+ OpenAICodexLM,
+ XaiLM,
+)
+from .providers.openai_chat import request_from_openai_chat, response_from_openai_chat
+from .protocols import ProviderLM
+from .providers.async_base import (
+ AsyncOpenAILM,
+ AsyncOpenAIChatLM,
+ AsyncAnthropicLM,
+ AsyncGeminiLM,
+ AsyncClaudeCodeLM,
+ AsyncOpenAICodexLM,
+ AsyncXaiLM,
+)
+
+# ── Stream assembly ──────────────────────────────────────────────────
+from .result import (
+ ResponseStream,
+ AsyncResponseStream,
+ amaterialize_response,
+ materialize_response,
+ response_to_events,
+)
+
+# ── Model metadata (catalog hydration) ──────────────────────────────
+from .models import ModelInfo, ModelRegistry
+
+# ── Router (lm15.router) ─────────────────────────────────────────────
+from .router import (
+ AmbiguousModelError,
+ AsyncLMRouter,
+ LMRouter,
+ MissingCredentialError,
+ Resolution,
+ RouterConfig,
+ UnknownModelError,
+)
+
+# ── Tool derivation (lm15.tools) ─────────────────────────────────────
+from .tools import (
+ DerivedParam,
+ ToolConfig,
+ ToolDerivation,
+ ToolDerivationError,
+ tool,
+)
+from .tools import derive as derive_tool
+
+__all__ = [
+ "__version__",
+ # core
+ "Request", "Response", "Message", "Usage", "Config", "CacheConfig",
+ "Reasoning", "ToolChoice", "ErrorDetail", "ContinuationState",
+ # parts
+ "TextPart", "ThinkingPart", "RefusalPart", "CitationPart", "ImagePart",
+ "AudioPart", "VideoPart", "DocumentPart", "BinaryPart", "ToolCallPart",
+ "ToolResultPart",
+ # tools
+ "FunctionTool", "BuiltinTool", "ToolCallInfo", "tool_result",
+ # logprobs
+ "TokenLogprob", "TopLogprob",
+ # streaming
+ "StreamStartEvent", "StreamDeltaEvent", "StreamEndEvent",
+ "StreamErrorEvent", "TextDelta", "ThinkingDelta", "AudioDelta",
+ "ImageDelta", "ToolCallDelta", "CitationDelta", "ContinuationDelta",
+ # auxiliary endpoints
+ "FileUploadRequest", "FileInfo", "FilePage",
+ "CacheInfo", "CachePage", "CachedPrefix",
+ "BatchRequest", "BatchJobInfo", "BatchEntry",
+ "VideoGenerationRequest", "VideoJobInfo", "VideoJob", "AsyncVideoJob",
+ "BatchJob", "AsyncBatchJob",
+ "ImageGenerationRequest", "ImageGenerationResponse",
+ "SpeechGenerationRequest", "SpeechGenerationResponse", "AudioFormat",
+ "LiveConfig", "Turn",
+ # vocabularies
+ "Role", "PartType", "FinishReason", "ReasoningEffort", "ErrorCode",
+ "StreamEventType", "ROLE_VALUES", "FINISH_REASONS", "ERROR_CODES",
+ # errors (the catchable taxonomy + the retry predicate)
+ "LM15Error", "TransportError", "LockTimeoutError", "StreamAssemblyError", "ConfigurationError", "CapabilityError",
+ "ProviderError", "AuthError", "BillingError", "RateLimitError",
+ "InvalidRequestError", "ContextLengthError", "TimeoutError",
+ "ServerError", "UnsupportedModelError", "UnsupportedFeatureError",
+ "NotConfiguredError", "RETRYABLE_ERRORS",
+ "AccessPolicy", "EndpointSupport",
+ # providers
+ "OpenAILM", "OpenAIChatLM", "AnthropicLM", "GeminiLM", "ClaudeCodeLM", "OpenAICodexLM", "XaiLM",
+ "ProviderLM",
+ # the Chat Completions dialect read in: a request body -> Request (MAP-12), a response body -> Response
+ "request_from_openai_chat", "response_from_openai_chat",
+ # async mirror providers
+ "AsyncOpenAILM", "AsyncOpenAIChatLM", "AsyncAnthropicLM", "AsyncGeminiLM",
+ "AsyncClaudeCodeLM", "AsyncOpenAICodexLM", "AsyncXaiLM",
+ # stream assembly
+ "ResponseStream", "AsyncResponseStream",
+ "materialize_response", "amaterialize_response", "response_to_events",
+ # model metadata (catalog hydration)
+ "ModelInfo", "ModelRegistry",
+ # router (lm15.router; the rule/preset tables live there too)
+ "LMRouter", "AsyncLMRouter", "RouterConfig", "Resolution",
+ "UnknownModelError",
+ "AmbiguousModelError", "MissingCredentialError",
+ # tool derivation (lm15.tools)
+ "tool", "derive_tool", "ToolConfig", "ToolDerivation", "DerivedParam",
+ "ToolDerivationError",
+]
diff --git a/dspy/_vendor/lm15/_authlock.py b/dspy/_vendor/lm15/_authlock.py
new file mode 100644
index 000000000..055f70ec1
--- /dev/null
+++ b/dspy/_vendor/lm15/_authlock.py
@@ -0,0 +1,177 @@
+"""
+lm15._authlock — cross-process credential-file locking and atomic writes.
+
+Internal module. Two primitives with strict semantics:
+
+- :func:`hold_file_lock` — an advisory, cross-process, exclusive lock scoped
+ to a credential file's real path. Locks live in an lm15-owned directory
+ (``$XDG_CACHE_HOME/lm15/locks`` by default), NOT next to the guarded file,
+ because credential files such as ``~/.claude/.credentials.json`` belong to
+ other tools whose directories lm15 must not populate.
+- :func:`write_private_json_atomic` — write-to-temp + fsync + ``os.replace``
+ so a crash mid-write can never leave a truncated or half-written
+ credential file. The temp file is created with mode 0600 before any secret
+ byte is written.
+
+Stated limitations (these are trade-offs, not oversights):
+
+- The lock is advisory and cooperative: it serializes lm15 processes against
+ each other. Foreign writers (the Claude Code CLI, the Codex CLI) do not
+ take this lock. Callers mitigate by re-reading the file inside the lock
+ before refreshing (double-checked refresh), so a foreign refresh that
+ landed while we waited is used instead of clobbered.
+- ``flock`` semantics are unreliable on some network filesystems (NFS).
+- On Windows the implementation falls back to ``msvcrt.locking`` byte locks;
+ same advisory semantics, best-effort.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+from .errors import LockTimeoutError
+
+_DEFAULT_LOCK_TIMEOUT_S = 60.0
+_LOCK_POLL_INTERVAL_S = 0.05
+
+
+class CredentialLockTimeout(LockTimeoutError, TimeoutError):
+ """Could not acquire the credential-file lock within the deadline.
+
+ An :class:`lm15.errors.LockTimeoutError` (ErrorCode ``lock_timeout``,
+ retryable; spec/auth.md AUTH-6) and the builtin ``TimeoutError`` at
+ once: inside the lm15 family for ``except LM15Error`` handlers, and a
+ ``TimeoutError`` for code written before the code existed.
+ """
+
+
+def _lock_dir() -> Path:
+ override = os.environ.get("LM15_LOCK_DIR")
+ if override:
+ return Path(override).expanduser()
+ cache_home = os.environ.get("XDG_CACHE_HOME")
+ base = Path(cache_home).expanduser() if cache_home else Path("~/.cache").expanduser()
+ return base / "lm15" / "locks"
+
+
+def lock_path_for(path: Path) -> Path:
+ """Deterministic lock-file path for a guarded credential file.
+
+ Keyed by the guarded file's absolute (not resolved-through-symlink
+ ``strict``) path so all lm15 processes agree on the same lock file even
+ before the credential file exists.
+ """
+ canonical = os.path.realpath(os.path.expanduser(str(path)))
+ digest = hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:32]
+ return _lock_dir() / f"{digest}.lock"
+
+
+if os.name == "posix":
+ import fcntl
+
+ def _try_lock(fd: int) -> bool:
+ try:
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+ return True
+ except OSError:
+ return False
+
+ def _unlock(fd: int) -> None:
+ fcntl.flock(fd, fcntl.LOCK_UN)
+
+else: # pragma: no cover - exercised only on Windows
+ import msvcrt
+
+ def _try_lock(fd: int) -> bool:
+ try:
+ msvcrt.locking(fd, msvcrt.LK_NBLCK, 1)
+ return True
+ except OSError:
+ return False
+
+ def _unlock(fd: int) -> None:
+ try:
+ msvcrt.locking(fd, msvcrt.LK_UNLCK, 1)
+ except OSError:
+ pass
+
+
+@contextmanager
+def hold_file_lock(
+ path: str | os.PathLike[str],
+ *,
+ timeout_s: float = _DEFAULT_LOCK_TIMEOUT_S,
+) -> Iterator[None]:
+ """Hold the exclusive advisory lock for ``path``.
+
+ Blocks up to ``timeout_s`` (polling, so it works on POSIX and Windows),
+ then raises :class:`CredentialLockTimeout`. Not re-entrant: a process
+ that already holds the lock must not re-enter; internal callers use the
+ ``*_unlocked`` write variants for that reason.
+ """
+ lock_file = lock_path_for(Path(path))
+ lock_file.parent.mkdir(parents=True, exist_ok=True)
+ fd = os.open(lock_file, os.O_RDWR | os.O_CREAT, 0o600)
+ try:
+ deadline = time.monotonic() + timeout_s
+ while not _try_lock(fd):
+ if time.monotonic() >= deadline:
+ raise CredentialLockTimeout(
+ f"Could not lock credential file {path} within {timeout_s:.0f}s "
+ f"(lock file: {lock_file}). Another process may be refreshing "
+ "the same credential; retry, or remove a stale lock only if "
+ "you are certain no other process holds it.",
+ path=str(path),
+ lock_path=str(lock_file),
+ )
+ time.sleep(_LOCK_POLL_INTERVAL_S)
+ try:
+ yield
+ finally:
+ _unlock(fd)
+ finally:
+ os.close(fd)
+
+
+def write_private_json_atomic(path: Path, data: dict[str, Any]) -> None:
+ """Atomically replace ``path`` with ``data`` as private (0600) JSON.
+
+ Durability order: write temp (created 0600 by ``mkstemp``) → flush →
+ fsync(temp) → ``os.replace`` → fsync(parent dir, POSIX). A reader
+ observes either the complete old file or the complete new file, never a
+ partial write.
+ """
+ path.parent.mkdir(parents=True, exist_ok=True)
+ fd, temp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+ try:
+ with os.fdopen(fd, "w", encoding="utf-8") as handle:
+ handle.write(json.dumps(data, indent=2) + "\n")
+ handle.flush()
+ os.fsync(handle.fileno())
+ os.replace(temp_name, path)
+ except BaseException:
+ try:
+ os.unlink(temp_name)
+ except OSError:
+ pass
+ raise
+ try:
+ os.chmod(path, 0o600)
+ except OSError: # pragma: no cover - permission oddities are best-effort
+ pass
+ if os.name == "posix":
+ try:
+ dir_fd = os.open(path.parent, os.O_RDONLY)
+ try:
+ os.fsync(dir_fd)
+ finally:
+ os.close(dir_fd)
+ except OSError: # pragma: no cover - fsync of dir is best-effort
+ pass
diff --git a/dspy/_vendor/lm15/_version.py b/dspy/_vendor/lm15/_version.py
new file mode 100644
index 000000000..06699f1bf
--- /dev/null
+++ b/dspy/_vendor/lm15/_version.py
@@ -0,0 +1,3 @@
+"""The version of this source package, also used when building distributions."""
+
+__version__ = "1.0.0a1"
diff --git a/dspy/_vendor/lm15/access.py b/dspy/_vendor/lm15/access.py
new file mode 100644
index 000000000..e28570453
--- /dev/null
+++ b/dspy/_vendor/lm15/access.py
@@ -0,0 +1,743 @@
+"""
+lm15.access — how a dialect adapter reaches a backend, as a value.
+
+An lm15 adapter is three composed things:
+
+- the **dialect**: the class that speaks a wire format (Anthropic Messages,
+ OpenAI Responses, OpenAI Chat Completions, Gemini);
+- for the chat dialect, a **compat** value describing a server's quirks
+ (``OpenAIChatCompat``);
+- an **access policy**: this module. Which credential, which headers,
+ which endpoint surfaces, which backend variant, which login hint.
+
+Before 2026-09-02 the third thing was a subclass: ``ClaudeCodeLM`` extended
+``AnthropicLM``, ``OpenAICodexLM`` extended ``OpenAILM``, ``XaiLM`` extended
+``OpenAIChatLM``, each overriding headers, payload defaults, error hints,
+and endpoint blocks. Go and Rust have no inheritance, so every port would
+have invented its own shape for the same facts. An ``AccessPolicy`` is a
+frozen value; a port copies the table below as data and consults it at the
+same named points the reference does (spec/auth.md AUTH-9).
+
+What stays behaviour, deliberately:
+
+- ``backend`` names a variant the dialect adapter switches on at a small,
+ documented set of points (the ChatGPT Codex backend answers a different
+ error envelope, a different models endpoint, and is streaming-first).
+ That is a ``match`` in every language, keyed on data.
+- Loading a stored subscription credential is per-language code, keyed by
+ ``provider`` (``_CREDENTIAL_LOADERS``); the policy says *that* a stored
+ credential is used, the loader says *how*.
+
+``ProviderManifest`` is the same class under its earlier name: an adapter's
+manifest is its access policy.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Callable
+
+from .auth import (
+ CLAUDE_CODE_LOGIN_HINT,
+ OPENAI_CODEX_LOGIN_HINT,
+ XAI_LOGIN_HINT,
+ extract_chatgpt_account_id,
+ get_claude_code_access_token,
+ get_codex_cli_access_token,
+ get_xai_access_token,
+ usable_xai_credential,
+)
+from .compat import ANTHROPIC_PRESET_BASE_URLS, OPENAI_CHAT_PRESET_BASE_URLS, OPENAI_RESPONSES_PRESET_BASE_URLS
+from .errors import NotConfiguredError
+from .credentials import AwsCredentials, BearerToken, CredentialLike, CredentialValue, coerce_credential
+from .features import ( # noqa: F401 — re-exported
+ AccessPolicy,
+ AuthHeader,
+ AuthScheme,
+ CredentialPolicy,
+ EndpointSupport,
+ HostSetting,
+ HostSpec,
+)
+
+# What ``api_key=`` accepts everywhere: a string, an AUTH-2 credential value,
+# or a zero-arg provider returning either. ``Credential`` is the historical
+# name for the same thing.
+Credential = CredentialLike
+
+# ─── The table ───────────────────────────────────────────────────────
+
+ANTHROPIC_API = AccessPolicy(
+ provider="anthropic",
+ supports=EndpointSupport(complete=True, stream=True, files=True, batches=True, models=True),
+ auth_modes=("x-api-key",),
+ env_keys=("ANTHROPIC_API_KEY",),
+ auth_scheme=("x-api-key",),
+)
+
+DEFAULT_CLAUDE_CODE_VERSION = "2.1.170"
+DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude."
+
+# models=True: the Anthropic /v1/models endpoint answers to the OAuth
+# headers (validated live 2026-08-31, HTTP 200). Files and batch are
+# API-key surfaces the subscription token does not carry.
+CLAUDE_CODE = AccessPolicy(
+ provider="claude-code",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ credential_policy="oauth",
+ auth_modes=("claude-code-oauth", "bearer-oauth"),
+ auth_scheme=("bearer",),
+ headers=(
+ ("anthropic-dangerous-direct-browser-access", "true"),
+ ("anthropic-beta", "claude-code-20250219,oauth-2025-04-20"),
+ ("x-app", "cli"),
+ ("user-agent", f"claude-cli/{DEFAULT_CLAUDE_CODE_VERSION}"),
+ ),
+ login_hint=CLAUDE_CODE_LOGIN_HINT,
+ backend="claude-code",
+ system_prefix=DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT,
+)
+
+OPENAI_API = AccessPolicy(
+ provider="openai",
+ supports=EndpointSupport(
+ complete=True, stream=True, live=True, files=True, batches=True,
+ images=True, speech=True, video=True, responses_api=True, models=True,
+ ),
+ auth_modes=("bearer",),
+ env_keys=("OPENAI_API_KEY",),
+ enterprise_variants=("azure-openai",),
+)
+
+DEFAULT_CODEX_BASE_URL = "https://chatgpt.com/backend-api/codex"
+DEFAULT_CODEX_ORIGINATOR = "lm15"
+DEFAULT_CODEX_INSTRUCTIONS = "You are a helpful assistant."
+# The backend's /models endpoint requires a client_version query parameter
+# (a Codex CLI release); any recent release is accepted.
+DEFAULT_CODEX_CLIENT_VERSION = "0.147.0"
+
+OPENAI_CODEX = AccessPolicy(
+ provider="openai-codex",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ credential_policy="oauth",
+ auth_modes=("chatgpt-oauth", "bearer-oauth"),
+ headers=(
+ ("OpenAI-Beta", "responses=experimental"),
+ ("originator", DEFAULT_CODEX_ORIGINATOR),
+ ),
+ login_hint=OPENAI_CODEX_LOGIN_HINT,
+ backend="chatgpt-codex",
+ backend_options={"client_version": DEFAULT_CODEX_CLIENT_VERSION},
+ system_prefix=DEFAULT_CODEX_INSTRUCTIONS,
+ base_url=DEFAULT_CODEX_BASE_URL,
+)
+
+OPENAI_CHAT_API = AccessPolicy(
+ provider="openai-chat",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("OPENAI_API_KEY",),
+)
+
+DEFAULT_XAI_BASE_URL = "https://api.x.ai/v1"
+
+XAI = AccessPolicy(
+ provider="xai",
+ supports=EndpointSupport(complete=True, stream=True, models=True, images=True, video=True),
+ credential_policy="oauth-unless-explicit",
+ auth_modes=("bearer", "xai-oauth"),
+ env_keys=("XAI_API_KEY",),
+ login_hint=XAI_LOGIN_HINT,
+ base_url=DEFAULT_XAI_BASE_URL,
+)
+
+GEMINI_API = AccessPolicy(
+ provider="gemini",
+ supports=EndpointSupport(
+ complete=True, stream=True, live=True, files=True, batches=True,
+ images=True, speech=True, video=True, models=True, caches=True,
+ ),
+ auth_modes=("query-api-key", "x-goog-api-key"),
+ env_keys=("GEMINI_API_KEY", "GOOGLE_API_KEY"),
+ auth_scheme=("x-api-key",), # the dialect renders it as x-goog-api-key
+)
+
+# ─── Responses servers reached through OpenAILM ────────────────────────
+
+# Meta Model API (dev.meta.ai, scraped 2026-09-03 — lm15-contract/scrapes/
+# meta/pages). One bearer key (`LLM|<team id>|<secret>`, authentication.md)
+# opens three chat wires and the account surfaces. `meta` names the
+# Responses wire — Meta's recommended default and the only one that carries
+# reasoning across turns (protocols.md) — plus the OpenAI-shaped Files
+# (files--upload.md: purpose user_data|batch), Images (images--create.md,
+# images--edit.md; model muse-image-1.0) and Models (models--list.md)
+# endpoints on the same root. No batch endpoint, no speech synthesis, no
+# video generation, no explicit cache resource, and the realtime WebSocket
+# is transcription-only (speech-to-text is a surface lm15 does not have).
+#
+# Env key: META_API_KEY only. Meta's own docs name the variable
+# MODEL_API_KEY (authentication.md); lm15 does not read it: a vendor-less
+# name set for some other tool would be picked up and sent to Meta without
+# the user asking for it. The registry note names the documented variable
+# so a quickstart user knows what to rename.
+META_ENV_KEYS = ("META_API_KEY",)
+
+META = AccessPolicy(
+ provider="meta",
+ supports=EndpointSupport(complete=True, stream=True, files=True, images=True, responses_api=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=META_ENV_KEYS,
+ base_url=OPENAI_RESPONSES_PRESET_BASE_URLS["meta"],
+)
+
+# ─── Chat Completions servers reached through OpenAIChatLM ───────────
+#
+# These policies are bound onto the chat dialect by the provider registry
+# (lm15.registry): the class is OpenAIChatLM, the compat preset of the
+# same name names the server's quirks, and this value names the credential
+# and the surfaces. base_url points at the compat table so each URL has
+# one copy.
+
+GROQ = AccessPolicy(
+ provider="groq",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("GROQ_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["groq"],
+)
+
+OPENROUTER = AccessPolicy(
+ provider="openrouter",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("OPENROUTER_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["openrouter"],
+)
+
+# DeepSeek (api-docs.deepseek.com, scraped 2026-09-03): bearer key from
+# platform.deepseek.com, prepaid balance (a drained balance is HTTP 402,
+# never a surprise bill). The same key also opens an Anthropic-format
+# endpoint (/anthropic) and a Responses-format endpoint; `deepseek` names
+# the Chat Completions wire only — a provider string never guesses a
+# protocol.
+DEEPSEEK = AccessPolicy(
+ provider="deepseek",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("DEEPSEEK_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["deepseek"],
+)
+
+# Z.AI (docs.z.ai, scraped 2026-09-03): bearer key from z.ai/manage-apikey,
+# general endpoint only. The GLM Coding Plan is a subscription with its own
+# endpoint and its own terms (docs.z.ai/devpack); lm15 does not name it.
+ZAI = AccessPolicy(
+ provider="zai",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("ZAI_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["zai"],
+)
+
+# Moonshot AI / Kimi API Platform (platform.kimi.ai, scraped 2026-09-03):
+# bearer key from platform.kimi.ai/console/api-keys, prepaid balance.
+# `moonshotai` names the Chat Completions wire (api--overview.md: the
+# documented primary; every model, every guide). The same key also opens a
+# Responses wire (kimi-k3 only, `tool_choice: auto` only) and an Anthropic
+# Messages wire at /anthropic; neither is registered yet — a provider
+# string never guesses a protocol.
+#
+# Env keys, in order: MOONSHOTAI_API_KEY (lm15's `<provider>_API_KEY`
+# convention, the name the maintainer set) then MOONSHOT_API_KEY (the name
+# Moonshot's own docs and SDK examples use, api--overview.md). Both are
+# vendor-named, so reading both cannot pick up another tool's secret (the
+# reason Meta's vendor-less MODEL_API_KEY is not read). Stated trade-off:
+# with both set to different keys, the lm15-named one wins silently; the
+# doctor (AUTH-7) shows the shadowed rung.
+MOONSHOTAI_ENV_KEYS = ("MOONSHOTAI_API_KEY", "MOONSHOT_API_KEY")
+
+MOONSHOTAI = AccessPolicy(
+ provider="moonshotai",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=MOONSHOTAI_ENV_KEYS,
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["moonshotai"],
+)
+
+# Moonshot's Responses wire (responses--create.md): the same key and root,
+# kimi-k3 only, stateless (no store, no previous_response_id); reasoning
+# returns as summary text and is replayed as-is. `models` is the same
+# GET /models as the chat wire.
+MOONSHOTAI_RESPONSES = AccessPolicy(
+ provider="moonshotai-responses",
+ supports=EndpointSupport(complete=True, stream=True, responses_api=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=MOONSHOTAI_ENV_KEYS,
+ base_url=OPENAI_RESPONSES_PRESET_BASE_URLS["moonshotai"],
+)
+
+# Meta's Chat Completions wire (protocols--chat-completions.md): the same
+# key, the drop-in for existing messages-array code. Reasoning is not
+# carried across turns here and search grounding is Responses-only; the
+# account surfaces (files, images) are reached through `meta`.
+META_CHAT = AccessPolicy(
+ provider="meta-chat",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=META_ENV_KEYS,
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["meta"],
+)
+
+# ─── Anthropic Messages servers reached through AnthropicLM ─────────────
+
+# DeepSeek's Anthropic-format endpoint (guide--anthropic-api.md; live
+# 2026-09-03): the same DEEPSEEK_API_KEY, sent as x-api-key. No /models on
+# this root (404) — list models through `deepseek`. A separate provider
+# string because a provider name describes wire behavior: `deepseek` is the
+# Chat Completions wire, `deepseek-anthropic` the Messages wire.
+DEEPSEEK_ANTHROPIC = AccessPolicy(
+ provider="deepseek-anthropic",
+ supports=EndpointSupport(complete=True, stream=True),
+ auth_modes=("x-api-key",),
+ env_keys=("DEEPSEEK_API_KEY",),
+ auth_scheme=("x-api-key",),
+ base_url=ANTHROPIC_PRESET_BASE_URLS["deepseek"],
+)
+
+# Meta's Anthropic-format wire (protocols--messages.md): the same key sent
+# as a bearer token (the docs' SDK examples pass it as auth_token, not
+# x-api-key). Stateless; thinking replays through redacted_thinking. The
+# /models root answers on the same base URL with the OpenAI list shape,
+# which the dialect's parser reads (live 2026-09-03, 7 entries).
+META_ANTHROPIC = AccessPolicy(
+ provider="meta-anthropic",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=META_ENV_KEYS,
+ auth_scheme=("bearer",),
+ base_url=ANTHROPIC_PRESET_BASE_URLS["meta"],
+)
+
+# Moonshot's Anthropic-format wire (messages--create.md, securitySchemes
+# bearerAuth; the Claude Code guide sets ANTHROPIC_AUTH_TOKEN): the same key
+# as a bearer token, kimi-k3 only. Whether /models answers on the
+# /anthropic root is a live finding recorded in the dossier.
+MOONSHOTAI_ANTHROPIC = AccessPolicy(
+ provider="moonshotai-anthropic",
+ supports=EndpointSupport(complete=True, stream=True),
+ auth_modes=("bearer",),
+ env_keys=MOONSHOTAI_ENV_KEYS,
+ auth_scheme=("bearer",),
+ base_url=ANTHROPIC_PRESET_BASE_URLS["moonshotai"],
+)
+
+# ─── Cloud hosts (spec/auth.md AUTH-10 host policies; changes/2026-09-03-cloud-hosts.md) ───
+#
+# Every row below is declared from provider documentation and the cloud
+# SDKs' resolver sources (lm15-contract/research/cloud-hosts/10-facts-*.md,
+# file:line cited there) and awaits its live receipt. A host is the third
+# use of the ``backend`` seam: the dialect is unchanged; the door changes
+# the URL, the signing, a closed set of rewrites, and the stream framing.
+
+_AWS_REGION = HostSetting("region", env=("AWS_REGION", "AWS_DEFAULT_REGION")) # no default: a wrong region is a residency bug
+_AWS_WORKSPACE = HostSetting("workspace", env=("ANTHROPIC_AWS_WORKSPACE_ID",))
+_GCP_PROJECT = HostSetting("project", env=("GOOGLE_CLOUD_PROJECT", "GCLOUD_PROJECT"))
+_GCP_LOCATION = HostSetting("location", env=("GOOGLE_CLOUD_LOCATION",), default="global") # stated trade-off: availability first; the doctor prints it
+_AZURE_OPENAI_RESOURCE = HostSetting("resource", env=("AZURE_OPENAI_RESOURCE",))
+_AZURE_FOUNDRY_RESOURCE = HostSetting("resource", env=("ANTHROPIC_FOUNDRY_RESOURCE",))
+_AZURE_AUTHORITY = HostSetting("authority_host", env=("AZURE_AUTHORITY_HOST",), default="https://login.microsoftonline.com")
+_AZURE_SCOPE = HostSetting("scope", env=(), default="https://ai.azure.com/.default")
+
+# Claude Platform on AWS: Anthropic-operated, the Claude API verbatim,
+# SigV4 service aws-external-anthropic or an AWS-console API key as
+# x-api-key; anthropic-workspace-id on every request; betas pass
+# (anthropic-platform-on-aws.md:19-31, :216-218, :244-262, :266-271).
+AWS_ANTHROPIC = AccessPolicy(
+ provider="aws-anthropic",
+ supports=EndpointSupport(complete=True, stream=True), # batches/models: live cells (the platform says "full Claude API")
+ credential_policy="aws-chain",
+ auth_modes=("sigv4", "x-api-key"),
+ env_keys=("ANTHROPIC_AWS_API_KEY",),
+ auth_scheme=("sigv4", "x-api-key"),
+ backend="aws-external-anthropic",
+ host=HostSpec(
+ base_url="https://aws-external-anthropic.{region}.api.aws/v1",
+ settings=(_AWS_REGION, _AWS_WORKSPACE),
+ required_headers=(("anthropic-workspace-id", "workspace"),),
+ sigv4_service="aws-external-anthropic",
+ ),
+)
+
+# Claude in Amazon Bedrock ("mantle", Opus 4.7 and later): the Messages API
+# at /anthropic/v1/messages on AWS-operated infrastructure, plain SSE, SigV4
+# service bedrock-mantle or a short-term bearer key as x-api-key; no
+# structured outputs, URL/Files sources, server tools, batches, models, or
+# anthropic-beta (anthropic-on-bedrock.md:58-70, :138-160, :322, :358-367).
+BEDROCK_ANTHROPIC = AccessPolicy(
+ provider="bedrock-anthropic",
+ supports=EndpointSupport(complete=True, stream=True),
+ credential_policy="aws-chain",
+ auth_modes=("sigv4", "x-api-key"),
+ env_keys=("AWS_BEARER_TOKEN_BEDROCK",),
+ auth_scheme=("sigv4", "x-api-key"),
+ backend="bedrock-mantle",
+ host=HostSpec(
+ base_url="https://bedrock-mantle.{region}.api.aws/anthropic/v1",
+ settings=(_AWS_REGION,),
+ sigv4_service="bedrock-mantle",
+ ),
+)
+
+# Bedrock's OpenAI Chat Completions door on bedrock-runtime: SigV4 service
+# bedrock or AWS_BEARER_TOKEN_BEDROCK (bedrock-openai-chat-completions.md:8,
+# :151, :178-228; bedrock-api-keys.md:176-185). models=False: GET
+# /openai/v1/models answers 404 UnknownOperationException under SigV4
+# (live 2026-09-03, receipts/2026-09-03-bedrock-chat/probe-models-list.json)
+# and the same 404 under a short-term key (live 2026-09-04,
+# probe-bearer-models.json), so the docs' listing claim does not hold.
+# Live-verified 2026-09-03 (SigV4) and 2026-09-04 (bearer) with
+# openai.gpt-oss-20b-1:0.
+BEDROCK_CHAT = AccessPolicy(
+ provider="bedrock-chat",
+ supports=EndpointSupport(complete=True, stream=True),
+ credential_policy="aws-chain",
+ auth_modes=("sigv4", "bearer"),
+ env_keys=("AWS_BEARER_TOKEN_BEDROCK",),
+ auth_scheme=("sigv4", "bearer"),
+ backend="bedrock-runtime",
+ host=HostSpec(
+ base_url="https://bedrock-runtime.{region}.amazonaws.com/openai/v1",
+ settings=(_AWS_REGION,),
+ sigv4_service="bedrock",
+ ),
+)
+
+# Bedrock-mantle Chat Completions: a different host from BEDROCK_CHAT, not a
+# setting. Live 2026-09-04 (receipts/2026-09-04-bedrock-chat/probe-mantle-chat-*):
+# SigV4 service bedrock-mantle; un-versioned model ids (openai.gpt-oss-20b,
+# not openai.gpt-oss-20b-1:0); GET /v1/models answers 200 with 55 entries
+# under SigV4 and under a short-term key; gpt-oss returns message.reasoning
+# (the runtime door inlines <reasoning> in content). Claude is listed but
+# 400 "does not support /v1/chat/completions"; Nova is 404. AWS's Chat
+# Completions page documents listing on this host, not on bedrock-runtime.
+BEDROCK_MANTLE_CHAT = AccessPolicy(
+ provider="bedrock-mantle-chat",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ credential_policy="aws-chain",
+ auth_modes=("sigv4", "bearer"),
+ env_keys=("AWS_BEARER_TOKEN_BEDROCK",),
+ auth_scheme=("sigv4", "bearer"),
+ backend="bedrock-mantle",
+ host=HostSpec(
+ base_url="https://bedrock-mantle.{region}.api.aws/v1",
+ settings=(_AWS_REGION,),
+ sigv4_service="bedrock-mantle",
+ ),
+)
+
+# Azure OpenAI v1: {resource}.openai.azure.com/openai/v1, no api-version,
+# api-key header or an Entra bearer token; the model is the DEPLOYMENT name
+# (azure-openai-api-lifecycle.md:59-106, :235-250;
+# azure-openai-managed-identity.md:213-246). models=True: the docs call
+# listing control-plane only, but GET /openai/v1/models answers 200 with the
+# api-key — the resource's whole catalog (dall-e, whisper, gpt-*), not just its
+# deployments (receipts/2026-09-04-azure/models.json; cases/azure/models.json).
+AZURE = AccessPolicy(
+ provider="azure",
+ # Live 2026-09-04 on an OpenAI-kind Azure resource: Files and Batches
+ # answer on /openai/v1; speech returns raw audio from /audio/speech.
+ # Images wait on deployment quota; video is deliberately out of scope.
+ supports=EndpointSupport(complete=True, stream=True, live=True, files=True, batches=True, speech=True,
+ responses_api=True, models=True),
+ credential_policy="azure-chain",
+ auth_modes=("api-key", "entra-oauth"),
+ env_keys=("AZURE_OPENAI_API_KEY",),
+ auth_scheme=("api-key", "bearer"),
+ backend="azure-openai",
+ host=HostSpec(
+ base_url="https://{resource}.openai.azure.com/openai/v1",
+ settings=(_AZURE_OPENAI_RESOURCE, _AZURE_AUTHORITY, _AZURE_SCOPE),
+ ),
+)
+
+AZURE_CHAT = AccessPolicy(
+ provider="azure-chat",
+ supports=EndpointSupport(complete=True, stream=True, models=True), # same /models as `azure`
+ credential_policy="azure-chain",
+ auth_modes=("api-key", "entra-oauth"),
+ env_keys=("AZURE_OPENAI_API_KEY",),
+ auth_scheme=("api-key", "bearer"),
+ backend="azure-openai",
+ host=HostSpec(
+ base_url="https://{resource}.openai.azure.com/openai/v1",
+ settings=(_AZURE_OPENAI_RESOURCE, _AZURE_AUTHORITY, _AZURE_SCOPE),
+ ),
+)
+
+# Claude in Microsoft Foundry: {resource}.services.ai.azure.com/anthropic/v1,
+# x-api-key or an Entra bearer token; no batches, models, fallbacks. The docs
+# also say `api-key`, but live on an AIServices resource it is 401 while the
+# same key under `x-api-key` reaches deployment lookup (404 DeploymentNotFound;
+# 2026-09-04, receipts/2026-09-04-azure-anthropic/).
+# Sources: anthropic-on-foundry.md:106, :124-143, :176, :305-318, :637-658.
+AZURE_ANTHROPIC = AccessPolicy(
+ provider="azure-anthropic",
+ supports=EndpointSupport(complete=True, stream=True),
+ credential_policy="azure-chain",
+ auth_modes=("x-api-key", "entra-oauth"),
+ env_keys=("ANTHROPIC_FOUNDRY_API_KEY",),
+ auth_scheme=("x-api-key", "bearer"),
+ backend="azure-foundry",
+ host=HostSpec(
+ base_url="https://{resource}.services.ai.azure.com/anthropic/v1",
+ settings=(_AZURE_FOUNDRY_RESOURCE, _AZURE_AUTHORITY, _AZURE_SCOPE),
+ ),
+)
+
+# Gemini on Vertex ("Agent Platform"): project + location in the path,
+# OAuth bearer with the cloud-platform scope; {location_host} is derived:
+# global → aiplatform.googleapis.com, us|eu → aiplatform.{loc}.rep.googleapis.com,
+# else {loc}-aiplatform.googleapis.com (vertex-locations.md:40-63, :91).
+_VERTEX_BASE = "https://{location_host}/v1/projects/{project}/locations/{location}"
+
+VERTEX = AccessPolicy(
+ provider="vertex",
+ supports=EndpointSupport(complete=True, stream=True), # caches/batches/models: live cells
+ credential_policy="gcp-chain",
+ auth_modes=("google-oauth",),
+ env_keys=(),
+ auth_scheme=("bearer",),
+ backend="vertex",
+ host=HostSpec(base_url=_VERTEX_BASE + "/publishers/google", settings=(_GCP_PROJECT, _GCP_LOCATION)),
+)
+
+# Express mode: an API key, no project or location (vertex-express-mode.md:84, :181).
+VERTEX_EXPRESS = AccessPolicy(
+ provider="vertex-express",
+ supports=EndpointSupport(complete=True, stream=True),
+ credential_policy="key",
+ auth_modes=("query-api-key",),
+ env_keys=("GOOGLE_API_KEY",),
+ auth_scheme=("query-key",),
+ backend="vertex-express",
+ host=HostSpec(base_url="https://aiplatform.googleapis.com/v1/publishers/google"),
+)
+
+# Claude on Vertex: model in the path (:rawPredict / :streamRawPredict),
+# anthropic_version in the body as vertex-2023-10-16; no batches, models,
+# Files sources (anthropic-on-vertex.md:9-10, :122-126, :358-365).
+VERTEX_ANTHROPIC = AccessPolicy(
+ provider="vertex-anthropic",
+ supports=EndpointSupport(complete=True, stream=True),
+ credential_policy="gcp-chain",
+ auth_modes=("google-oauth",),
+ env_keys=(),
+ auth_scheme=("bearer",),
+ backend="vertex",
+ host=HostSpec(
+ base_url=_VERTEX_BASE,
+ settings=(_GCP_PROJECT, _GCP_LOCATION),
+ paths={
+ "messages": "/publishers/anthropic/models/{model}:rawPredict",
+ "messages/stream": "/publishers/anthropic/models/{model}:streamRawPredict",
+ },
+ model_in="path",
+ anthropic_version_in="body:vertex-2023-10-16",
+ ),
+)
+
+CLOUD_HOST_POLICIES: tuple[AccessPolicy, ...] = (
+ AZURE, AZURE_CHAT, AZURE_ANTHROPIC,
+ AWS_ANTHROPIC, BEDROCK_ANTHROPIC, BEDROCK_CHAT, BEDROCK_MANTLE_CHAT,
+ VERTEX, VERTEX_EXPRESS, VERTEX_ANTHROPIC,
+)
+
+# Keyless local servers: no env key; the registry supplies the placeholder
+# the server accepts when nothing is configured.
+OLLAMA = AccessPolicy(
+ provider="ollama",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["ollama"],
+)
+
+VLLM = AccessPolicy(
+ provider="vllm",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["vllm"],
+)
+
+SGLANG = AccessPolicy(
+ provider="sglang",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["sglang"],
+)
+
+
+# ─── Credential loading, keyed by provider ───────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class LoadedCredential:
+ credential: Credential = field(repr=False)
+ account_id: str | None = None
+ source: str = "explicit" # "explicit" (caller-supplied) or "stored" (local login)
+
+
+def _load_claude_code(path: str | os.PathLike[str] | None) -> LoadedCredential:
+ # Validate now (typed, re-login-guided errors), then re-resolve per
+ # request so a long-lived client always sends a fresh token.
+ get_claude_code_access_token(path)
+ return LoadedCredential(lambda: get_claude_code_access_token(path), source="stored")
+
+
+def _load_openai_codex(path: str | os.PathLike[str] | None) -> LoadedCredential:
+ initial = get_codex_cli_access_token(path)
+ account_id = initial.account_id or extract_chatgpt_account_id(initial.access_token)
+ return LoadedCredential(lambda: get_codex_cli_access_token(path).access_token, account_id, source="stored")
+
+
+def _load_xai(path: str | os.PathLike[str] | None) -> LoadedCredential:
+ get_xai_access_token(path)
+ return LoadedCredential(lambda: get_xai_access_token(path), source="stored")
+
+
+_CREDENTIAL_LOADERS: dict[str, Callable[[str | os.PathLike[str] | None], LoadedCredential]] = {
+ "claude-code": _load_claude_code,
+ "openai-codex": _load_openai_codex,
+ "xai": _load_xai,
+}
+
+_STORED_PROBES: dict[str, Callable[[], bool]] = {
+ "xai": usable_xai_credential,
+}
+
+
+def load_credential(
+ policy: AccessPolicy,
+ api_key: Credential | None,
+ *,
+ credentials_path: str | os.PathLike[str] | None = None,
+) -> LoadedCredential:
+ """Resolve the credential an adapter will send under ``policy``.
+
+ An explicit ``api_key`` always wins (AUTH-1). Otherwise a stored-login
+ policy loads through its provider's loader; a ``key`` policy with no
+ key is a typed not-configured error naming the env keys.
+ """
+ if api_key is not None and api_key != "":
+ return LoadedCredential(api_key)
+ loader = _CREDENTIAL_LOADERS.get(policy.provider) if policy.credential_policy != "key" else None
+ if loader is not None:
+ return loader(credentials_path)
+ raise NotConfiguredError(
+ f"{policy.provider}: no credential given"
+ + (f"; set {' or '.join(policy.env_keys)} or pass api_key=" if policy.env_keys else "; pass api_key="),
+ provider=policy.provider,
+ env_keys=policy.env_keys,
+ credential_hint=policy.login_hint,
+ )
+
+
+def has_stored_credential(policy: AccessPolicy) -> bool:
+ """Offline probe (reads files, never the network) for the router's
+ ``oauth-unless-explicit`` chain: is a usable login stored locally?"""
+ probe = _STORED_PROBES.get(policy.provider)
+ return bool(probe()) if probe is not None else False
+
+
+# AUTH-2 (ratified 2026-09-06, lm15-contract/changes/2026-09-06-decisions.md D1): the
+# schemes each credential kind may travel under. An ApiKey takes the
+# policy's first header-carrying scheme in POLICY order; a BearerToken takes
+# `bearer` if listed, else `x-api-key` if listed — the TOKEN's order, not the
+# policy's, so an Entra token on azure-anthropic (x-api-key, bearer) still
+# goes as bearer while a Bedrock short-term key on bedrock-anthropic
+# (sigv4, x-api-key) goes in the key header; AwsCredentials sign (sigv4) only.
+_ACCEPTED_SCHEMES: dict[str, tuple[AuthScheme, ...]] = {
+ "api_key": ("bearer", "x-api-key", "api-key", "query-key"),
+ "bearer_token": ("bearer", "x-api-key"),
+ "aws": ("sigv4",),
+}
+
+
+def select_scheme(policy: AccessPolicy, credential: CredentialValue) -> AuthScheme:
+ """The scheme this credential kind travels under (AUTH-2, AUTH-10).
+
+ ``ApiKey``: the first scheme in the policy's order that carries a key.
+ ``BearerToken``: ``bearer`` if the policy lists it, else ``x-api-key`` if
+ the policy lists it. ``AwsCredentials``: ``sigv4`` only. Anything else
+ raises ``NotConfiguredError`` naming the schemes the kind accepts and the
+ schemes the door offers.
+ """
+ accepted = _ACCEPTED_SCHEMES[credential.kind]
+ if isinstance(credential, BearerToken):
+ for scheme in accepted:
+ if scheme in policy.auth_scheme:
+ return scheme
+ else:
+ for scheme in policy.auth_scheme:
+ if scheme in accepted:
+ return scheme
+ raise NotConfiguredError(
+ f"{policy.provider}: a {credential.kind} credential cannot travel under "
+ f"{'/'.join(policy.auth_scheme)}; it accepts {'/'.join(accepted)}",
+ provider=policy.provider,
+ env_keys=policy.env_keys,
+ )
+
+
+def _looks_like_jwt(text: str) -> bool:
+ """Three base64url segments whose first decodes to a JSON object with
+ ``alg`` — the JWS compact form every Entra/OAuth access token uses."""
+ import base64
+ import json
+
+ parts = text.split(".")
+ if len(parts) != 3 or not all(parts):
+ return False
+ head = parts[0]
+ try:
+ decoded = base64.urlsafe_b64decode(head + "=" * (-len(head) % 4))
+ header = json.loads(decoded)
+ except (ValueError, UnicodeDecodeError):
+ return False
+ return isinstance(header, dict) and "alg" in header
+
+
+def auth_header(
+ policy: AccessPolicy,
+ credential: str | CredentialValue,
+ *,
+ api_key_header: str = "x-api-key",
+) -> tuple[str, str] | None:
+ """The (name, value) header that carries ``credential`` under this
+ policy, or ``None`` when the scheme is not a header (``sigv4`` signs the
+ finished request; ``query-key`` is a query parameter) — the dialect's
+ ``_emit`` handles those."""
+ value = coerce_credential(credential)
+ scheme = select_scheme(policy, value)
+ if scheme in ("api-key", "x-api-key") and "bearer" in policy.auth_scheme and _looks_like_jwt(value.value):
+ # A plain string reads as an API key, and on this door the key header
+ # comes before bearer. A JWT is never an API key on these doors: it
+ # is an Entra/OAuth access token that a token-provider callable
+ # (azure-identity's get_bearer_token_provider returns a str) handed
+ # over as a string. Sent as a key it is a bare 401 ("invalid
+ # subscription key", live 2026-09-04); name the fix instead.
+ raise NotConfiguredError(
+ f"{policy.provider}: the credential is a JWT (a bearer token), but a plain string travels as an"
+ f" API key here (`{'x-api-key' if scheme == 'x-api-key' else 'api-key'}` header); wrap it:"
+ " lm15.credentials.BearerToken(token)",
+ provider=policy.provider,
+ env_keys=policy.env_keys,
+ credential_hint="api_key=lambda: BearerToken(provider())",
+ )
+ if scheme == "bearer":
+ return ("Authorization", f"Bearer {value.value}")
+ if scheme == "x-api-key":
+ return (api_key_header, value.value)
+ if scheme == "api-key":
+ return ("api-key", value.value)
+ return None
diff --git a/dspy/_vendor/lm15/auth.py b/dspy/_vendor/lm15/auth.py
new file mode 100644
index 000000000..981e6305f
--- /dev/null
+++ b/dspy/_vendor/lm15/auth.py
@@ -0,0 +1,917 @@
+"""
+lm15.auth — Local subscription credential helpers.
+
+These helpers intentionally do not read ordinary provider API keys from the
+environment. They only support explicit local developer credentials created
+by provider CLIs: Claude Code (``~/.claude/.credentials.json``), the OpenAI
+Codex CLI (``~/.codex/auth.json``) — plus xAI subscription OAuth, which lm15
+logs in itself (device-code flow) because xAI ships no CLI credential file
+convention; see the xAI section at the bottom.
+
+Failure behavior is typed and helpful, never a raw JSON traceback:
+
+- missing / unreadable / malformed credential files raise
+ :class:`lm15.errors.NotConfiguredError` telling the user which CLI login to
+ run;
+- an expired token that cannot be refreshed (no refresh token, or the refresh
+ call fails) raises :class:`lm15.errors.AuthError` with the same re-login
+ guidance;
+- lock contention on a credential file raises
+ :class:`lm15.auth.CredentialLockTimeout` — an
+ :class:`lm15.errors.LockTimeoutError` (ErrorCode ``lock_timeout``,
+ retryable; spec/auth.md AUTH-6) and the builtin ``TimeoutError`` at
+ once: a local, transient condition, not a provider error, so it
+ deliberately does not wear the AuthError type.
+
+Token material never appears in error messages or reprs.
+
+Concurrency contract (lm15-contract spec/auth.md AUTH-3/AUTH-4, ratified
+2026-08-31):
+
+- refresh runs under a cross-process advisory lock, with a re-read of the
+ file inside the lock (double-checked refresh) so a refresh that another
+ process completed while we waited is used, not repeated — repeating it
+ loses a rotated refresh token;
+- all credential writes are atomic (temp file + rename) and private (0600);
+- the lock is advisory and cooperative between lm15 processes. The Claude
+ Code and Codex CLIs do not take it; the double-checked re-read is the
+ mitigation for foreign writers, not a cure. The network refresh happens
+ while holding the lock — one slow refresh can therefore stall other lm15
+ processes for up to the lock timeout; the alternative (refresh outside the
+ lock) double-spends rotated refresh tokens, which is worse.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from ._authlock import CredentialLockTimeout, hold_file_lock, write_private_json_atomic
+from .errors import AuthError, NotConfiguredError, UnsupportedFeatureError
+
+__all__ = [
+ "CredentialLockTimeout",
+ "LocalOAuthCredential",
+ "XaiDeviceAuthorization",
+ "get_claude_code_access_token",
+ "get_codex_cli_access_token",
+ "get_xai_access_token",
+ "load_claude_code_credential",
+ "load_codex_cli_credential",
+ "load_xai_credential",
+ "login",
+ "login_xai",
+ "poll_xai_device_login",
+ "read_claude_code_credential",
+ "read_codex_cli_credential",
+ "read_xai_credential",
+ "refresh_claude_code_credential",
+ "refresh_codex_cli_credential",
+ "refresh_xai_credential",
+ "start_xai_device_login",
+ "usable_xai_credential",
+ "write_claude_code_credential",
+ "write_codex_cli_credential",
+ "write_xai_credential",
+]
+
+CLAUDE_CODE_CREDENTIALS_PATH = Path("~/.claude/.credentials.json").expanduser()
+CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d5-88ed-5944d1962f5e"
+CLAUDE_CODE_TOKEN_URL = "https://platform.claude.com/v1/oauth/token"
+CLAUDE_CODE_LOGIN_HINT = "Log in again: run `claude` and use /login (Claude subscription auth)"
+
+CODEX_CLI_AUTH_PATH = Path("~/.codex/auth.json").expanduser()
+OPENAI_CODEX_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+OPENAI_CODEX_TOKEN_URL = "https://auth.openai.com/oauth/token"
+OPENAI_CODEX_JWT_CLAIM_PATH = "https://api.openai.com/auth"
+OPENAI_CODEX_LOGIN_HINT = "Log in again: run `codex login` (ChatGPT subscription auth)"
+
+_REFRESH_SKEW_MS = 5 * 60 * 1000
+
+
+@dataclass(frozen=True, slots=True)
+class LocalOAuthCredential:
+ """A locally stored OAuth credential. Token fields are repr-suppressed."""
+
+ access_token: str = field(repr=False)
+ refresh_token: str | None = field(default=None, repr=False)
+ expires_at: int | None = None
+ account_id: str | None = None
+
+ @property
+ def expired(self) -> bool:
+ return isinstance(self.expires_at, int) and int(time.time() * 1000) >= self.expires_at
+
+
+def _not_configured(provider: str, message: str, hint: str) -> NotConfiguredError:
+ return NotConfiguredError(message, provider=provider, credential_hint=hint)
+
+
+def _read_json_file(path: Path, *, provider: str, hint: str) -> dict[str, Any]:
+ """Read a credential file, raising typed errors instead of crashing."""
+ try:
+ text = path.read_text(encoding="utf-8")
+ except FileNotFoundError as exc:
+ raise _not_configured(provider, f"No credentials file at {path}.", hint) from exc
+ except OSError as exc:
+ raise _not_configured(provider, f"Could not read credentials file at {path}: {exc}", hint) from exc
+ try:
+ data = json.loads(text)
+ except ValueError as exc:
+ raise _not_configured(provider, f"Credentials file at {path} is not valid JSON.", hint) from exc
+ if not isinstance(data, dict):
+ raise _not_configured(provider, f"Credentials file at {path} has an unexpected shape.", hint)
+ return data
+
+
+def _read_json_file_or_none(path: Path) -> dict[str, Any] | None:
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ except Exception:
+ return None
+ return data if isinstance(data, dict) else None
+
+
+def _write_private_json(path: Path, data: dict[str, Any]) -> None:
+ write_private_json_atomic(path, data)
+
+
+def _base64url_json(segment: str) -> dict[str, Any]:
+ padding = "=" * (-len(segment) % 4)
+ decoded = base64.urlsafe_b64decode(segment + padding)
+ data = json.loads(decoded.decode("utf-8"))
+ return data if isinstance(data, dict) else {}
+
+
+def decode_jwt_payload(token: str) -> dict[str, Any]:
+ parts = token.split(".")
+ if len(parts) != 3:
+ raise ValueError("Invalid JWT")
+ return _base64url_json(parts[1])
+
+
+def jwt_expires_at_ms(token: str) -> int | None:
+ try:
+ exp = decode_jwt_payload(token).get("exp")
+ except Exception:
+ return None
+ if isinstance(exp, (int, float)):
+ return int(exp * 1000) - _REFRESH_SKEW_MS
+ return None
+
+
+def extract_chatgpt_account_id(token: str) -> str | None:
+ try:
+ payload = decode_jwt_payload(token)
+ except Exception:
+ return None
+ auth_claim = payload.get(OPENAI_CODEX_JWT_CLAIM_PATH)
+ if isinstance(auth_claim, dict):
+ account_id = auth_claim.get("chatgpt_account_id")
+ if isinstance(account_id, str) and account_id:
+ return account_id
+ return None
+
+
+def _post_json(url: str, payload: dict[str, Any]) -> dict[str, Any]:
+ body = json.dumps(payload).encode("utf-8")
+ request = urllib.request.Request(
+ url,
+ data=body,
+ headers={"Content-Type": "application/json", "Accept": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(request, timeout=30) as response: # noqa: S310 - provider token endpoint
+ data = json.loads(response.read().decode("utf-8"))
+ return data if isinstance(data, dict) else {}
+
+
+def _post_form(url: str, payload: dict[str, Any]) -> dict[str, Any]:
+ body = urllib.parse.urlencode(payload).encode("utf-8")
+ request = urllib.request.Request(
+ url,
+ data=body,
+ headers={"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json"},
+ method="POST",
+ )
+ with urllib.request.urlopen(request, timeout=30) as response: # noqa: S310 - provider token endpoint
+ data = json.loads(response.read().decode("utf-8"))
+ return data if isinstance(data, dict) else {}
+
+
+def _coerce_path(path: str | os.PathLike[str] | None, default: Path) -> Path:
+ return Path(path).expanduser() if path is not None else default
+
+
+# ─── Claude Code (~/.claude/.credentials.json) ───────────────────────
+
+
+def load_claude_code_credential(
+ credentials_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential:
+ """Load the Claude Code OAuth credential, raising typed errors."""
+ path = _coerce_path(credentials_path, CLAUDE_CODE_CREDENTIALS_PATH)
+ data = _read_json_file(path, provider="claude-code", hint=CLAUDE_CODE_LOGIN_HINT)
+ raw = data.get("claudeAiOauth")
+ if not isinstance(raw, dict):
+ raise _not_configured(
+ "claude-code",
+ f"Credentials file at {path} has no claudeAiOauth section.",
+ CLAUDE_CODE_LOGIN_HINT,
+ )
+ access = raw.get("accessToken")
+ if not isinstance(access, str) or not access:
+ raise _not_configured(
+ "claude-code",
+ f"Credentials file at {path} has no access token.",
+ CLAUDE_CODE_LOGIN_HINT,
+ )
+ refresh = raw.get("refreshToken")
+ expires = raw.get("expiresAt")
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh if isinstance(refresh, str) and refresh else None,
+ expires_at=int(expires) if isinstance(expires, (int, float)) else None,
+ )
+
+
+def read_claude_code_credential(
+ credentials_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential | None:
+ """Optional-style loader: None when no usable credential exists."""
+ try:
+ return load_claude_code_credential(credentials_path)
+ except NotConfiguredError:
+ return None
+
+
+def refresh_claude_code_credential(refresh_token: str) -> LocalOAuthCredential:
+ payload = _post_json(
+ CLAUDE_CODE_TOKEN_URL,
+ {
+ "grant_type": "refresh_token",
+ "client_id": CLAUDE_CODE_CLIENT_ID,
+ "refresh_token": refresh_token,
+ },
+ )
+ access = payload.get("access_token")
+ refresh = payload.get("refresh_token")
+ expires_in = payload.get("expires_in")
+ if not isinstance(access, str) or not isinstance(refresh, str) or not isinstance(expires_in, (int, float)):
+ raise RuntimeError("Claude Code token refresh response is missing required fields")
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh,
+ expires_at=int(time.time() * 1000 + expires_in * 1000 - _REFRESH_SKEW_MS),
+ )
+
+
+def _write_claude_code_credential_unlocked(credential: LocalOAuthCredential, path: Path) -> None:
+ data = _read_json_file_or_none(path) or {}
+ raw = data.get("claudeAiOauth")
+ current = raw if isinstance(raw, dict) else {}
+ current["accessToken"] = credential.access_token
+ if credential.refresh_token:
+ current["refreshToken"] = credential.refresh_token
+ if credential.expires_at is not None:
+ current["expiresAt"] = credential.expires_at
+ data["claudeAiOauth"] = current
+ _write_private_json(path, data)
+
+
+def write_claude_code_credential(
+ credential: LocalOAuthCredential,
+ credentials_path: str | os.PathLike[str] | None = None,
+) -> None:
+ path = _coerce_path(credentials_path, CLAUDE_CODE_CREDENTIALS_PATH)
+ with hold_file_lock(path):
+ _write_claude_code_credential_unlocked(credential, path)
+
+
+def get_claude_code_access_token(
+ credentials_path: str | os.PathLike[str] | None = None,
+ *,
+ refresh: bool = True,
+) -> str:
+ """Return a usable Claude Code access token, refreshing it if expired.
+
+ Raises NotConfiguredError when no credential exists, AuthError when the
+ credential is expired and cannot be refreshed.
+ """
+ credential = load_claude_code_credential(credentials_path)
+ if not credential.expired:
+ return credential.access_token
+ if not refresh or not credential.refresh_token:
+ raise AuthError(
+ "Claude Code OAuth token is expired and no refresh token is available.",
+ provider="claude-code",
+ credential_hint=CLAUDE_CODE_LOGIN_HINT,
+ )
+ path = _coerce_path(credentials_path, CLAUDE_CODE_CREDENTIALS_PATH)
+ with hold_file_lock(path):
+ # Double-checked refresh: another process may have refreshed (and
+ # rotated the refresh token) while we waited for the lock.
+ credential = load_claude_code_credential(path)
+ if not credential.expired:
+ return credential.access_token
+ if not credential.refresh_token:
+ raise AuthError(
+ "Claude Code OAuth token is expired and no refresh token is available.",
+ provider="claude-code",
+ credential_hint=CLAUDE_CODE_LOGIN_HINT,
+ )
+ try:
+ refreshed = refresh_claude_code_credential(credential.refresh_token)
+ except Exception as exc:
+ raise AuthError(
+ "Claude Code OAuth token is expired and the refresh attempt failed.",
+ provider="claude-code",
+ credential_hint=CLAUDE_CODE_LOGIN_HINT,
+ ) from exc
+ _write_claude_code_credential_unlocked(refreshed, path)
+ return refreshed.access_token
+
+
+# ─── OpenAI Codex CLI (~/.codex/auth.json) ───────────────────────────
+
+
+def load_codex_cli_credential(
+ auth_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential:
+ """Load the Codex CLI OAuth credential, raising typed errors."""
+ path = _coerce_path(auth_path, CODEX_CLI_AUTH_PATH)
+ data = _read_json_file(path, provider="openai-codex", hint=OPENAI_CODEX_LOGIN_HINT)
+ tokens = data.get("tokens")
+ if not isinstance(tokens, dict):
+ raise _not_configured(
+ "openai-codex",
+ f"Credentials file at {path} has no tokens section.",
+ OPENAI_CODEX_LOGIN_HINT,
+ )
+ access = tokens.get("access_token")
+ if not isinstance(access, str) or not access:
+ raise _not_configured(
+ "openai-codex",
+ f"Credentials file at {path} has no access token.",
+ OPENAI_CODEX_LOGIN_HINT,
+ )
+ refresh = tokens.get("refresh_token")
+ account_id = tokens.get("account_id") or extract_chatgpt_account_id(access)
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh if isinstance(refresh, str) and refresh else None,
+ expires_at=jwt_expires_at_ms(access),
+ account_id=account_id if isinstance(account_id, str) and account_id else None,
+ )
+
+
+def read_codex_cli_credential(
+ auth_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential | None:
+ """Optional-style loader: None when no usable credential exists."""
+ try:
+ return load_codex_cli_credential(auth_path)
+ except NotConfiguredError:
+ return None
+
+
+def refresh_codex_cli_credential(refresh_token: str) -> LocalOAuthCredential:
+ payload = _post_form(
+ OPENAI_CODEX_TOKEN_URL,
+ {
+ "grant_type": "refresh_token",
+ "refresh_token": refresh_token,
+ "client_id": OPENAI_CODEX_CLIENT_ID,
+ },
+ )
+ access = payload.get("access_token")
+ refresh = payload.get("refresh_token") or refresh_token
+ if not isinstance(access, str) or not isinstance(refresh, str):
+ raise RuntimeError("Codex token refresh response is missing required fields")
+ account_id = extract_chatgpt_account_id(access)
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh,
+ expires_at=jwt_expires_at_ms(access),
+ account_id=account_id,
+ )
+
+
+def write_codex_cli_credential(
+ credential: LocalOAuthCredential,
+ auth_path: str | os.PathLike[str] | None = None,
+ *,
+ id_token: str | None = None,
+) -> None:
+ path = _coerce_path(auth_path, CODEX_CLI_AUTH_PATH)
+ with hold_file_lock(path):
+ _write_codex_cli_credential_unlocked(credential, path, id_token=id_token)
+
+
+def _write_codex_cli_credential_unlocked(
+ credential: LocalOAuthCredential,
+ path: Path,
+ *,
+ id_token: str | None = None,
+) -> None:
+ data = _read_json_file_or_none(path) or {}
+ tokens = data.get("tokens")
+ current = tokens if isinstance(tokens, dict) else {}
+ current["access_token"] = credential.access_token
+ if credential.refresh_token:
+ current["refresh_token"] = credential.refresh_token
+ if credential.account_id:
+ current["account_id"] = credential.account_id
+ if id_token is not None:
+ current["id_token"] = id_token
+ data["tokens"] = current
+ data.setdefault("auth_mode", "chatgpt")
+ data["last_refresh"] = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+ _write_private_json(path, data)
+
+
+def get_codex_cli_access_token(
+ auth_path: str | os.PathLike[str] | None = None,
+ *,
+ refresh: bool = True,
+) -> LocalOAuthCredential:
+ """Return a usable Codex CLI credential, refreshing it if expired.
+
+ Raises NotConfiguredError when no credential exists, AuthError when the
+ credential is expired and cannot be refreshed.
+ """
+ credential = load_codex_cli_credential(auth_path)
+ if not credential.expired:
+ return credential
+ if not refresh or not credential.refresh_token:
+ raise AuthError(
+ "Codex CLI OAuth token is expired and no refresh token is available.",
+ provider="openai-codex",
+ credential_hint=OPENAI_CODEX_LOGIN_HINT,
+ )
+ path = _coerce_path(auth_path, CODEX_CLI_AUTH_PATH)
+ with hold_file_lock(path):
+ # Double-checked refresh: see the Claude Code sibling above.
+ credential = load_codex_cli_credential(path)
+ if not credential.expired:
+ return credential
+ if not credential.refresh_token:
+ raise AuthError(
+ "Codex CLI OAuth token is expired and no refresh token is available.",
+ provider="openai-codex",
+ credential_hint=OPENAI_CODEX_LOGIN_HINT,
+ )
+ try:
+ refreshed = refresh_codex_cli_credential(credential.refresh_token)
+ except Exception as exc:
+ raise AuthError(
+ "Codex CLI OAuth token is expired and the refresh attempt failed.",
+ provider="openai-codex",
+ credential_hint=OPENAI_CODEX_LOGIN_HINT,
+ ) from exc
+ original = _read_json_file_or_none(path) or {}
+ tokens = original.get("tokens") if isinstance(original.get("tokens"), dict) else {}
+ id_token = (
+ tokens.get("id_token")
+ if isinstance(tokens, dict) and isinstance(tokens.get("id_token"), str)
+ else None
+ )
+ _write_codex_cli_credential_unlocked(refreshed, path, id_token=id_token)
+ return refreshed
+
+
+# ─── xAI Grok (device-code OAuth; lm15 store or Pi agent store) ──────
+#
+# Unlike Claude Code and Codex, xAI has no first-party CLI credential file
+# convention lm15 can piggyback on. lm15 therefore owns a login
+# (:func:`login_xai`, RFC 8628 device-code flow) writing to lm15's own
+# credential store, and additionally reads the Pi coding agent's store
+# (``~/.pi/agent/auth.json``) when present — both files share the same
+# ``{"xai": {"type": "oauth", "access", "refresh", "expires"}}`` schema.
+# Refreshes write back to whichever file the credential came from: xAI
+# rotates refresh tokens, so a refresh that is not persisted to its source
+# bricks that source's login.
+
+XAI_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828"
+XAI_DEVICE_CODE_URL = "https://auth.x.ai/oauth2/device/code"
+XAI_TOKEN_URL = "https://auth.x.ai/oauth2/token"
+XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access"
+XAI_LOGIN_HINT = "Log in again: run lm15.auth.login_xai() (SuperGrok / X Premium subscription auth)"
+PI_AGENT_AUTH_PATH = Path("~/.pi/agent/auth.json").expanduser()
+
+_XAI_PROVIDER_KEY = "xai"
+_XAI_DEFAULT_TOKEN_LIFETIME_S = 3600
+
+
+def _xai_store_paths() -> tuple[Path, ...]:
+ from .authkit import default_credentials_path
+
+ return (default_credentials_path(), PI_AGENT_AUTH_PATH)
+
+
+def _xai_entry_to_credential(entry: Any) -> LocalOAuthCredential | None:
+ if not isinstance(entry, dict):
+ return None
+ access = entry.get("access")
+ if not isinstance(access, str) or not access:
+ return None
+ refresh = entry.get("refresh")
+ expires = entry.get("expires")
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh if isinstance(refresh, str) and refresh else None,
+ expires_at=expires if isinstance(expires, int) and not isinstance(expires, bool) else None,
+ )
+
+
+def _xai_credential_to_entry(credential: LocalOAuthCredential, current: dict[str, Any] | None) -> dict[str, Any]:
+ entry = dict(current or {})
+ entry["type"] = "oauth"
+ entry["access"] = credential.access_token
+ if credential.refresh_token:
+ entry["refresh"] = credential.refresh_token
+ if credential.expires_at is not None:
+ entry["expires"] = credential.expires_at
+ return entry
+
+
+def _load_xai_with_source(
+ auth_path: str | os.PathLike[str] | None = None,
+) -> tuple[LocalOAuthCredential, Path]:
+ paths = (Path(auth_path).expanduser(),) if auth_path is not None else _xai_store_paths()
+ for path in paths:
+ data = _read_json_file_or_none(path)
+ credential = _xai_entry_to_credential(data.get(_XAI_PROVIDER_KEY)) if data else None
+ if credential is not None:
+ return credential, path
+ checked = ", ".join(str(p) for p in paths)
+ raise _not_configured(
+ "xai",
+ f"No xAI OAuth credential found (checked: {checked}).",
+ XAI_LOGIN_HINT,
+ )
+
+
+def load_xai_credential(
+ auth_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential:
+ """Load the stored xAI OAuth credential, raising typed errors."""
+ credential, _ = _load_xai_with_source(auth_path)
+ return credential
+
+
+def read_xai_credential(
+ auth_path: str | os.PathLike[str] | None = None,
+) -> LocalOAuthCredential | None:
+ """Optional-style loader: None when no usable credential exists."""
+ try:
+ return load_xai_credential(auth_path)
+ except NotConfiguredError:
+ return None
+
+
+def usable_xai_credential(auth_path: str | os.PathLike[str] | None = None) -> bool:
+ """True when a stored xAI subscription credential exists and is usable
+ (fresh, or expired with a refresh token to refresh it at request time).
+
+ Reads files only — never the network — so the router can consult it
+ while staying offline. This is the probe behind the
+ ``oauth-unless-explicit`` credential policy (spec/auth.md AUTH-1): the
+ stored subscription wins over ambient environment keys exactly when
+ this returns True.
+ """
+ credential = read_xai_credential(auth_path)
+ if credential is None:
+ return False
+ return not credential.expired or bool(credential.refresh_token)
+
+
+def _xai_credential_from_token_response(
+ payload: dict[str, Any],
+ previous_refresh_token: str | None = None,
+) -> LocalOAuthCredential:
+ access = payload.get("access_token")
+ if not isinstance(access, str) or not access:
+ raise RuntimeError("xAI token response is missing access_token")
+ refresh = payload.get("refresh_token")
+ if not isinstance(refresh, str) or not refresh:
+ # xAI may omit refresh_token when it does not rotate it.
+ refresh = previous_refresh_token
+ expires_in = payload.get("expires_in")
+ lifetime_s = (
+ expires_in
+ if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool) and expires_in > 0
+ else _XAI_DEFAULT_TOKEN_LIFETIME_S
+ )
+ return LocalOAuthCredential(
+ access_token=access,
+ refresh_token=refresh,
+ expires_at=int(time.time() * 1000 + lifetime_s * 1000 - _REFRESH_SKEW_MS),
+ )
+
+
+def refresh_xai_credential(refresh_token: str) -> LocalOAuthCredential:
+ payload = _post_form(
+ XAI_TOKEN_URL,
+ {
+ "grant_type": "refresh_token",
+ "client_id": XAI_CLIENT_ID,
+ "refresh_token": refresh_token,
+ },
+ )
+ return _xai_credential_from_token_response(payload, refresh_token)
+
+
+def write_xai_credential(
+ credential: LocalOAuthCredential,
+ auth_path: str | os.PathLike[str] | None = None,
+) -> None:
+ """Write the credential into a store file (default: lm15's own store)."""
+ from .authkit import CredentialFileStore, default_credentials_path
+
+ store = CredentialFileStore(auth_path if auth_path is not None else default_credentials_path())
+ store.mutate(_XAI_PROVIDER_KEY, lambda current: _xai_credential_to_entry(credential, current))
+
+
+def get_xai_access_token(
+ auth_path: str | os.PathLike[str] | None = None,
+ *,
+ refresh: bool = True,
+) -> str:
+ """Return a usable xAI access token, refreshing (and persisting) if expired.
+
+ Raises NotConfiguredError when no credential exists, AuthError when the
+ credential is expired and cannot be refreshed. A refresh is written back
+ to the file the credential came from (lm15 store or Pi agent store) under
+ that file's lock, with a double-checked re-read: xAI rotates refresh
+ tokens, so losing the write would break every consumer of that file.
+ """
+ from .authkit import CredentialFileStore
+
+ credential, source = _load_xai_with_source(auth_path)
+ if not credential.expired:
+ return credential.access_token
+ if not refresh or not credential.refresh_token:
+ raise AuthError(
+ "xAI OAuth token is expired and no refresh token is available.",
+ provider="xai",
+ credential_hint=XAI_LOGIN_HINT,
+ )
+
+ result: dict[str, str] = {}
+
+ def _refresh_entry(current: dict[str, Any] | None) -> dict[str, Any] | None:
+ # Double-checked refresh: another process may have refreshed (and
+ # rotated the refresh token) while we waited for the lock.
+ fresh = _xai_entry_to_credential(current)
+ if fresh is not None and not fresh.expired:
+ result["access"] = fresh.access_token
+ return None
+ refresh_token = (fresh.refresh_token if fresh else None) or credential.refresh_token
+ if not refresh_token:
+ raise AuthError(
+ "xAI OAuth token is expired and no refresh token is available.",
+ provider="xai",
+ credential_hint=XAI_LOGIN_HINT,
+ )
+ try:
+ refreshed = refresh_xai_credential(refresh_token)
+ except AuthError:
+ raise
+ except Exception as exc:
+ raise AuthError(
+ "xAI OAuth token is expired and the refresh attempt failed.",
+ provider="xai",
+ credential_hint=XAI_LOGIN_HINT,
+ ) from exc
+ result["access"] = refreshed.access_token
+ return _xai_credential_to_entry(refreshed, current)
+
+ CredentialFileStore(source).mutate(_XAI_PROVIDER_KEY, _refresh_entry)
+ return result["access"]
+
+
+# ─── xAI device-code login (RFC 8628) ────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class XaiDeviceAuthorization:
+ """One pending device authorization. The device code is repr-suppressed."""
+
+ user_code: str
+ verification_uri: str
+ verification_uri_complete: str | None
+ interval_s: float
+ expires_in_s: float
+ device_code: str = field(repr=False, default="")
+
+
+def _https_or_raise(raw: Any) -> str:
+ # The verification URI is shown to (and often opened by) the user; refuse
+ # anything a malicious response could turn into a local scheme launch.
+ if isinstance(raw, str):
+ try:
+ parsed = urllib.parse.urlparse(raw)
+ except ValueError:
+ parsed = None
+ if parsed is not None and parsed.scheme == "https" and parsed.netloc:
+ return raw
+ raise AuthError("xAI device authorization returned an untrusted verification URI.", provider="xai")
+
+
+def _parse_xai_device_authorization(payload: dict[str, Any]) -> XaiDeviceAuthorization:
+ device_code = payload.get("device_code")
+ user_code = payload.get("user_code")
+ expires_in = payload.get("expires_in")
+ if not isinstance(device_code, str) or not device_code or not isinstance(user_code, str) or not user_code:
+ raise AuthError("xAI device authorization response is missing required fields.", provider="xai")
+ if not isinstance(expires_in, (int, float)) or isinstance(expires_in, bool) or expires_in <= 0:
+ raise AuthError("xAI device authorization response is missing expires_in.", provider="xai")
+ interval = payload.get("interval")
+ interval_s = (
+ float(interval)
+ if isinstance(interval, (int, float)) and not isinstance(interval, bool) and interval > 0
+ else 5.0
+ )
+ complete = payload.get("verification_uri_complete")
+ return XaiDeviceAuthorization(
+ user_code=user_code,
+ verification_uri=_https_or_raise(payload.get("verification_uri")),
+ verification_uri_complete=_https_or_raise(complete) if isinstance(complete, str) and complete else None,
+ interval_s=interval_s,
+ expires_in_s=float(expires_in),
+ device_code=device_code,
+ )
+
+
+def _post_form_tolerant(url: str, payload: dict[str, Any]) -> tuple[bool, dict[str, Any]]:
+ """POST a form; return (ok, parsed body) even for 4xx responses.
+
+ Device-code polling encodes protocol state (authorization_pending,
+ slow_down, ...) in 4xx bodies, so HTTP errors are data here.
+ """
+ try:
+ return True, _post_form(url, payload)
+ except urllib.error.HTTPError as exc:
+ try:
+ data = json.loads(exc.read().decode("utf-8"))
+ except Exception:
+ data = {}
+ return False, data if isinstance(data, dict) else {}
+
+
+def start_xai_device_login() -> XaiDeviceAuthorization:
+ """Request a device authorization; show the user code, then poll."""
+ ok, payload = _post_form_tolerant(
+ XAI_DEVICE_CODE_URL,
+ {"client_id": XAI_CLIENT_ID, "scope": XAI_OAUTH_SCOPE, "referrer": "lm15"},
+ )
+ if not ok:
+ detail = payload.get("error_description") or payload.get("error") or "request failed"
+ raise AuthError(f"xAI device authorization failed: {detail}", provider="xai")
+ return _parse_xai_device_authorization(payload)
+
+
+def poll_xai_device_login(
+ device: XaiDeviceAuthorization,
+ *,
+ sleep: Any = time.sleep,
+) -> LocalOAuthCredential:
+ """Poll the token endpoint until the user approves; return the credential."""
+ from .authkit import DeviceComplete, DeviceFailed, DevicePending, DeviceSlowDown, poll_device_code
+
+ def _poll() -> Any:
+ ok, payload = _post_form_tolerant(
+ XAI_TOKEN_URL,
+ {
+ "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+ "client_id": XAI_CLIENT_ID,
+ "device_code": device.device_code,
+ },
+ )
+ if ok:
+ return DeviceComplete(_xai_credential_from_token_response(payload))
+ error = payload.get("error")
+ if error == "authorization_pending":
+ return DevicePending()
+ if error == "slow_down":
+ interval = payload.get("interval")
+ return DeviceSlowDown(
+ float(interval)
+ if isinstance(interval, (int, float)) and not isinstance(interval, bool) and interval > 0
+ else None
+ )
+ if error in {"access_denied", "authorization_denied"}:
+ return DeviceFailed("xAI device authorization was denied.")
+ if error == "expired_token":
+ return DeviceFailed("xAI device code expired before it was approved.")
+ detail = payload.get("error_description") or error or "request failed"
+ return DeviceFailed(f"xAI device token polling failed: {detail}")
+
+ return poll_device_code(
+ _poll,
+ interval_s=device.interval_s,
+ expires_in_s=device.expires_in_s,
+ provider="xai",
+ wait_before_first_poll=True,
+ sleep=sleep,
+ )
+
+
+def login_xai(
+ auth_path: str | os.PathLike[str] | None = None,
+ *,
+ echo: Any = print,
+) -> LocalOAuthCredential:
+ """Interactive device-code login; persists the credential and returns it.
+
+ Prints the verification URL and user code via ``echo`` and blocks until
+ the user approves in a browser (or the code expires). The credential is
+ written to lm15's own store unless ``auth_path`` overrides it.
+ """
+ device = start_xai_device_login()
+ target = device.verification_uri_complete or device.verification_uri
+ echo(f"Open {target} and enter code: {device.user_code}")
+ credential = poll_xai_device_login(device)
+ write_xai_credential(credential, auth_path)
+ return credential
+
+
+# ─── Uniform login entry point ───────────────────────────────────
+#
+# One door, provider-dispatched. Only providers with an lm15-owned flow
+# actually log in here (today: xai). Every other provider fails typed,
+# naming the real path: the foreign CLI command that owns the flow, or the
+# console URL where keys are created. These URLs are guidance strings, not
+# wire facts — they can drift, and drifting costs a stale hint, not broken
+# inference.
+
+_KEY_CONSOLE_URLS: dict[str, str] = {
+ "openai": "https://platform.openai.com/api-keys",
+ "openai-chat": "https://platform.openai.com/api-keys",
+ "anthropic": "https://console.anthropic.com",
+ "gemini": "https://aistudio.google.com/apikey",
+ "groq": "https://console.groq.com/keys",
+ "openrouter": "https://openrouter.ai/keys",
+ "xai": "https://console.x.ai",
+}
+
+_CLI_LOGIN_HINTS: dict[str, str] = {
+ "claude-code": CLAUDE_CODE_LOGIN_HINT,
+ "openai-codex": OPENAI_CODEX_LOGIN_HINT,
+}
+
+_KEYLESS_LOCAL_SERVERS = frozenset({"ollama", "vllm", "sglang"})
+
+
+def login(
+ provider: str,
+ *,
+ credentials_path: str | os.PathLike[str] | None = None,
+ echo: Any = print,
+) -> LocalOAuthCredential:
+ """Run the login flow lm15 owns for ``provider``; fail typed otherwise.
+
+ This is the uniform door: ``login("xai")`` runs the device-code flow and
+ returns the stored credential. Providers whose login lives elsewhere
+ raise :class:`lm15.errors.UnsupportedFeatureError` naming the exact fix
+ — the foreign CLI command (Claude Code, Codex) or the console URL where
+ an API key is created. Nothing here prompts, opens a browser, or
+ spends money except the one flow you explicitly asked for.
+ """
+ canonical = provider.replace("_", "-")
+ if canonical == "xai":
+ return login_xai(credentials_path, echo=echo)
+ if canonical in _CLI_LOGIN_HINTS:
+ raise UnsupportedFeatureError(
+ f"lm15 does not own the {canonical!r} login flow — the provider CLI does. "
+ f"{_CLI_LOGIN_HINTS[canonical]}",
+ provider=canonical,
+ )
+ if canonical in _KEYLESS_LOCAL_SERVERS:
+ raise UnsupportedFeatureError(
+ f"{canonical!r} is a keyless local server — there is nothing to log into. "
+ "The router sends the placeholder key the server expects.",
+ provider=canonical,
+ )
+ if canonical in _KEY_CONSOLE_URLS:
+ raise UnsupportedFeatureError(
+ f"{canonical!r} offers no OAuth login flow — only manually created API keys. "
+ f"Create one at {_KEY_CONSOLE_URLS[canonical]} and set it in the environment "
+ f"or RouterConfig(api_keys={{{canonical!r}: \"...\"}}).",
+ provider=canonical,
+ )
+ raise UnsupportedFeatureError(
+ f"lm15 has no login flow for {provider!r}. Supply an API key via the "
+ "environment or RouterConfig(api_keys=...).",
+ provider=canonical,
+ )
diff --git a/dspy/_vendor/lm15/authkit.py b/dspy/_vendor/lm15/authkit.py
new file mode 100644
index 000000000..d604044d8
--- /dev/null
+++ b/dspy/_vendor/lm15/authkit.py
@@ -0,0 +1,360 @@
+"""
+lm15.authkit — building blocks for login flows. No UI, no opinions.
+
+lm15 deliberately does not own a ``/login`` experience: apps and CLIs do.
+This module gives those apps the pieces that are hard to get right and
+painful to reimplement per language, all stdlib-only:
+
+- :func:`generate_pkce` / :func:`pkce_challenge` — RFC 7636 (S256 only;
+ ``plain`` is intentionally not offered because every current provider
+ supports S256 and ``plain`` exists only as a downgrade).
+- :func:`poll_device_code` — the RFC 8628 device-authorization polling state
+ machine (pending / slow_down / complete / failure / expiry), with
+ injectable clock and sleep so it is testable without real time.
+- :class:`OAuthCallbackListener` — a one-shot loopback HTTP listener for
+ authorization-code redirects, bound to ``127.0.0.1``, with state checking.
+- :class:`CredentialFileStore` — an lm15-owned, locked, atomic, 0600
+ credential file keyed by provider id (the ADC/pi ``auth.json`` pattern),
+ with a serialized read-modify-write ``mutate`` as the only compound write
+ path.
+
+Secrets never appear in reprs or exception messages raised by this module.
+"""
+
+from __future__ import annotations
+
+import base64
+import copy
+import hashlib
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Any, Callable, Union
+from urllib.parse import parse_qs, urlsplit
+
+from ._authlock import hold_file_lock, write_private_json_atomic
+from .errors import AuthError
+
+__all__ = [
+ "CredentialFileStore",
+ "DeviceCodeExpiredError",
+ "DeviceComplete",
+ "DeviceFailed",
+ "DevicePending",
+ "DeviceSlowDown",
+ "OAuthCallbackListener",
+ "OAuthCallbackResult",
+ "PKCEPair",
+ "default_credentials_path",
+ "generate_pkce",
+ "pkce_challenge",
+ "poll_device_code",
+]
+
+
+# ─── PKCE (RFC 7636, S256) ───────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class PKCEPair:
+ verifier: str = field(repr=False) # secret until the code exchange
+ challenge: str
+ method: str = "S256"
+
+
+def pkce_challenge(verifier: str) -> str:
+ """S256 code challenge for ``verifier`` (RFC 7636 §4.2)."""
+ digest = hashlib.sha256(verifier.encode("ascii")).digest()
+ return base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii")
+
+
+def generate_pkce() -> PKCEPair:
+ """Fresh PKCE pair: 64 random bytes → 86-char base64url verifier."""
+ verifier = base64.urlsafe_b64encode(secrets.token_bytes(64)).rstrip(b"=").decode("ascii")
+ return PKCEPair(verifier=verifier, challenge=pkce_challenge(verifier))
+
+
+# ─── Device-code polling (RFC 8628 §3.5) ─────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class DevicePending:
+ """Authorization still pending; poll again after the interval."""
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceSlowDown:
+ """Server asked to slow down; interval grows by 5s unless it names one."""
+
+ interval_s: float | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceComplete:
+ """Authorization finished; ``value`` is whatever the poll fn produced."""
+
+ value: Any = field(repr=False) # usually carries tokens
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceFailed:
+ """Terminal denial/failure. ``message`` must not contain secrets."""
+
+ message: str
+
+
+DevicePollResult = Union[DevicePending, DeviceSlowDown, DeviceComplete, DeviceFailed]
+
+_SLOW_DOWN_STEP_S = 5.0 # RFC 8628 §3.5: "increase ... by 5 seconds"
+
+
+class DeviceCodeExpiredError(AuthError):
+ """The device code expired before the user approved it."""
+
+
+def poll_device_code(
+ poll: Callable[[], DevicePollResult],
+ *,
+ interval_s: float = 5.0,
+ expires_in_s: float = 900.0,
+ provider: str | None = None,
+ wait_before_first_poll: bool = False,
+ sleep: Callable[[float], None] = time.sleep,
+ clock: Callable[[], float] = time.monotonic,
+) -> Any:
+ """Run the device-authorization polling loop; return the completed value.
+
+ ``poll`` performs one token-endpoint request and classifies the outcome.
+ Raises :class:`DeviceCodeExpiredError` on expiry and :class:`AuthError`
+ on terminal failure. ``sleep``/``clock`` are injectable for tests.
+ """
+ interval = max(interval_s, 0.0)
+ deadline = clock() + expires_in_s
+ first = True
+ while True:
+ if not first or wait_before_first_poll:
+ if clock() + interval > deadline:
+ raise DeviceCodeExpiredError(
+ "Device authorization expired before it was approved. Start the login again.",
+ provider=provider,
+ )
+ sleep(interval)
+ first = False
+ if clock() > deadline:
+ raise DeviceCodeExpiredError(
+ "Device authorization expired before it was approved. Start the login again.",
+ provider=provider,
+ )
+ result = poll()
+ if isinstance(result, DeviceComplete):
+ return result.value
+ if isinstance(result, DeviceFailed):
+ raise AuthError(result.message, provider=provider)
+ if isinstance(result, DeviceSlowDown):
+ interval = result.interval_s if result.interval_s else interval + _SLOW_DOWN_STEP_S
+ elif not isinstance(result, DevicePending):
+ raise TypeError(f"poll() must return a DevicePollResult, got {type(result).__name__}")
+
+
+# ─── Loopback callback listener ──────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class OAuthCallbackResult:
+ code: str = field(repr=False) # authorization codes are secrets
+ state: str | None = None
+
+
+_SUCCESS_HTML = (
+ "<!doctype html><meta charset='utf-8'><title>Signed in</title>"
+ "<p>Authentication completed. You can close this window.</p>"
+)
+_ERROR_HTML = "<!doctype html><meta charset='utf-8'><title>Error</title><p>{message}</p>"
+
+
+class OAuthCallbackListener:
+ """One-shot loopback listener for an authorization-code redirect.
+
+ Usage::
+
+ with OAuthCallbackListener(expected_state=state) as listener:
+ url = build_authorize_url(redirect_uri=listener.redirect_uri, ...)
+ print(url) # or open a browser
+ result = listener.wait(timeout_s=300)
+
+ Binds ``127.0.0.1`` (never a public interface) on an ephemeral port by
+ default. Wrong-path and wrong-state requests get an error page and the
+ listener keeps waiting; a provider ``error`` parameter or the deadline
+ ends the wait. Single-threaded by design: build and display the
+ authorization URL before calling :meth:`wait`.
+ """
+
+ def __init__(
+ self,
+ *,
+ expected_state: str | None = None,
+ host: str = "127.0.0.1",
+ port: int = 0,
+ path: str = "/callback",
+ ) -> None:
+ self._expected_state = expected_state
+ self._path = path
+ self._result: OAuthCallbackResult | None = None
+ self._error: str | None = None
+ listener = self
+
+ class _Handler(BaseHTTPRequestHandler):
+ def log_message(self, *_args: Any) -> None: # no request logging: URLs carry codes
+ pass
+
+ def do_GET(self) -> None:
+ split = urlsplit(self.path)
+ if split.path != listener._path:
+ self._reply(404, _ERROR_HTML.format(message="Callback route not found."))
+ return
+ params = parse_qs(split.query)
+ error = params.get("error", [None])[0]
+ if error:
+ description = params.get("error_description", [error])[0]
+ listener._error = description or error
+ self._reply(400, _ERROR_HTML.format(message="Authorization was not completed."))
+ return
+ state = params.get("state", [None])[0]
+ if listener._expected_state is not None and state != listener._expected_state:
+ self._reply(400, _ERROR_HTML.format(message="State mismatch."))
+ return
+ code = params.get("code", [None])[0]
+ if not code:
+ self._reply(400, _ERROR_HTML.format(message="Missing authorization code."))
+ return
+ listener._result = OAuthCallbackResult(code=code, state=state)
+ self._reply(200, _SUCCESS_HTML)
+
+ def _reply(self, status: int, html: str) -> None:
+ body = html.encode("utf-8")
+ self.send_response(status)
+ self.send_header("Content-Type", "text/html; charset=utf-8")
+ self.send_header("Content-Length", str(len(body)))
+ self.send_header("Cache-Control", "no-store")
+ self.end_headers()
+ self.wfile.write(body)
+
+ self._server = HTTPServer((host, port), _Handler)
+
+ @property
+ def redirect_uri(self) -> str:
+ host, port = self._server.server_address[:2]
+ return f"http://{host}:{port}{self._path}"
+
+ def wait(self, *, timeout_s: float = 300.0) -> OAuthCallbackResult:
+ """Block until the redirect arrives; raise on error or timeout."""
+ deadline = time.monotonic() + timeout_s
+ while self._result is None and self._error is None:
+ remaining = deadline - time.monotonic()
+ if remaining <= 0:
+ raise TimeoutError("Timed out waiting for the OAuth redirect.")
+ self._server.timeout = min(remaining, 1.0)
+ self._server.handle_request()
+ if self._error is not None:
+ raise AuthError(f"Authorization failed: {self._error}")
+ assert self._result is not None
+ return self._result
+
+ def close(self) -> None:
+ self._server.server_close()
+
+ def __enter__(self) -> "OAuthCallbackListener":
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ self.close()
+
+
+# ─── lm15-owned credential store ─────────────────────────────────────
+
+
+def default_credentials_path() -> Path:
+ """``$LM15_CREDENTIALS_PATH``, else ``$XDG_CONFIG_HOME/lm15/credentials.json``."""
+ override = os.environ.get("LM15_CREDENTIALS_PATH")
+ if override:
+ return Path(override).expanduser()
+ config_home = os.environ.get("XDG_CONFIG_HOME")
+ base = Path(config_home).expanduser() if config_home else Path("~/.config").expanduser()
+ return base / "lm15" / "credentials.json"
+
+
+class CredentialFileStore:
+ """A locked, atomic, private (0600) credential file keyed by provider id.
+
+ The file is one JSON object: ``{"<provider>": {...credential...}}``.
+ ``mutate`` is the only compound write path — a serialized
+ read-modify-write under the cross-process lock, so refresh flows can
+ re-check state before writing (the double-checked pattern).
+
+ The store deliberately does not interpret credential shapes; that is the
+ caller's schema. It only guarantees storage semantics.
+ """
+
+ def __init__(self, path: str | os.PathLike[str] | None = None) -> None:
+ self.path = Path(path).expanduser() if path is not None else default_credentials_path()
+
+ def __repr__(self) -> str: # never show file contents
+ return f"CredentialFileStore(path={str(self.path)!r})"
+
+ def _read_all(self) -> dict[str, Any]:
+ try:
+ data = json.loads(self.path.read_text(encoding="utf-8"))
+ except FileNotFoundError:
+ return {}
+ except ValueError as exc:
+ raise ValueError(f"Credential store at {self.path} is not valid JSON.") from exc
+ if not isinstance(data, dict):
+ raise ValueError(f"Credential store at {self.path} must be a JSON object.")
+ return data
+
+ def read(self, provider: str) -> dict[str, Any] | None:
+ """The stored credential for ``provider``, or None. Returns a copy."""
+ credential = self._read_all().get(provider)
+ return copy.deepcopy(credential) if isinstance(credential, dict) else None
+
+ def list(self) -> tuple[str, ...]:
+ """Provider ids with stored credentials. Never returns values."""
+ return tuple(sorted(self._read_all()))
+
+ def write(self, provider: str, credential: dict[str, Any]) -> None:
+ self.mutate(provider, lambda _current: credential)
+
+ def delete(self, provider: str) -> None:
+ with hold_file_lock(self.path):
+ data = self._read_all()
+ if provider in data:
+ del data[provider]
+ write_private_json_atomic(self.path, data)
+
+ def mutate(
+ self,
+ provider: str,
+ fn: Callable[[dict[str, Any] | None], dict[str, Any] | None],
+ ) -> dict[str, Any] | None:
+ """Serialized read-modify-write for one provider's credential.
+
+ ``fn`` receives the current credential (or None) as read inside the
+ lock and returns the new credential, or None to leave the entry
+ unchanged. Returns the post-write credential.
+ """
+ with hold_file_lock(self.path):
+ data = self._read_all()
+ current = data.get(provider)
+ current = copy.deepcopy(current) if isinstance(current, dict) else None
+ replacement = fn(current)
+ if replacement is None:
+ return current
+ if not isinstance(replacement, dict):
+ raise TypeError("mutate() callback must return a dict or None")
+ data[provider] = replacement
+ write_private_json_atomic(self.path, data)
+ return copy.deepcopy(replacement)
diff --git a/dspy/_vendor/lm15/batch.py b/dspy/_vendor/lm15/batch.py
new file mode 100644
index 000000000..c412ca8dc
--- /dev/null
+++ b/dspy/_vendor/lm15/batch.py
@@ -0,0 +1,165 @@
+"""
+lm15.batch — the BatchJob handle (ticket ergonomics over the pure ops).
+
+A batch job is a ticket: the provider holds the requests, ``job.id`` is
+the ticket number, and the id is a plain string you can store anywhere.
+The handle is per-language sugar over five pure operations
+(``batch_submit`` / ``batch_status`` / ``batch_results`` /
+``batch_cancel`` / ``batch_list``); ports implement the ops, the handle
+idiom is theirs to choose.
+
+``refresh()`` / ``wait()`` / ``cancel()`` update the handle's snapshot in
+place and return the handle — a mutating refresh avoids the
+forgot-to-reassign-stale-status bug. The frozen-types culture applies to
+canonical types (``BatchJobInfo``, ``BatchEntry``), not client handles.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING, Any
+
+from .types import BatchEntry, BatchJobInfo, BatchStatus
+
+if TYPE_CHECKING: # pragma: no cover - annotations only
+ from .providers.async_base import AsyncBaseLM
+ from .providers.base import BaseProviderLM
+
+__all__ = ["AsyncBatchJob", "BatchJob"]
+
+_DEFAULT_POLL_SECONDS = 30.0
+
+
+class BatchJob:
+ """A live handle on one provider-side batch job."""
+
+ def __init__(self, lm: "BaseProviderLM", info: BatchJobInfo) -> None:
+ self._lm = lm
+ self._info = info
+
+ # ─── Snapshot access ─────────────────────────────────────────────
+
+ @property
+ def info(self) -> BatchJobInfo:
+ """The frozen snapshot from the last provider contact."""
+ return self._info
+
+ @property
+ def id(self) -> str:
+ return self._info.id
+
+ @property
+ def status(self) -> BatchStatus:
+ return self._info.status
+
+ @property
+ def label(self) -> str | None:
+ return self._info.label
+
+ @property
+ def created_at(self) -> str | None:
+ return self._info.created_at
+
+ @property
+ def provider_data(self) -> dict[str, Any] | None:
+ return self._info.provider_data
+
+ @property
+ def done(self) -> bool:
+ return self._info.done
+
+ def __repr__(self) -> str:
+ label = f" label={self._info.label!r}" if self._info.label else ""
+ return f"BatchJob(id={self._info.id!r}, status={self._info.status!r}{label})"
+
+ # ─── Verbs (update the snapshot in place, return self) ───────────
+
+ def refresh(self) -> "BatchJob":
+ self._info = self._lm.batch_status(self._info.id)
+ return self
+
+ def wait(self, poll_every: float = _DEFAULT_POLL_SECONDS, timeout: float | None = None) -> "BatchJob":
+ """Poll until the job is terminal. Convenience for small jobs and
+ notebooks; the primary pattern for real workloads is store-the-id
+ and re-attach."""
+ deadline = None if timeout is None else time.monotonic() + timeout
+ while True:
+ if self._info.done:
+ return self
+ if deadline is not None and time.monotonic() >= deadline:
+ raise TimeoutError(
+ f"batch {self._info.id} still {self._info.status!r} after {timeout}s"
+ )
+ time.sleep(poll_every)
+ self.refresh()
+
+ def results(self) -> tuple[BatchEntry, ...]:
+ return self._lm.batch_results(self._info.id)
+
+ def cancel(self) -> "BatchJob":
+ self._info = self._lm.batch_cancel(self._info.id)
+ return self
+
+
+class AsyncBatchJob:
+ """Async twin of :class:`BatchJob`; identical types, awaitable verbs."""
+
+ def __init__(self, lm: "AsyncBaseLM", info: BatchJobInfo) -> None:
+ self._lm = lm
+ self._info = info
+
+ @property
+ def info(self) -> BatchJobInfo:
+ return self._info
+
+ @property
+ def id(self) -> str:
+ return self._info.id
+
+ @property
+ def status(self) -> BatchStatus:
+ return self._info.status
+
+ @property
+ def label(self) -> str | None:
+ return self._info.label
+
+ @property
+ def created_at(self) -> str | None:
+ return self._info.created_at
+
+ @property
+ def provider_data(self) -> dict[str, Any] | None:
+ return self._info.provider_data
+
+ @property
+ def done(self) -> bool:
+ return self._info.done
+
+ def __repr__(self) -> str:
+ label = f" label={self._info.label!r}" if self._info.label else ""
+ return f"AsyncBatchJob(id={self._info.id!r}, status={self._info.status!r}{label})"
+
+ async def refresh(self) -> "AsyncBatchJob":
+ self._info = await self._lm.batch_status(self._info.id)
+ return self
+
+ async def wait(self, poll_every: float = _DEFAULT_POLL_SECONDS, timeout: float | None = None) -> "AsyncBatchJob":
+ deadline = None if timeout is None else time.monotonic() + timeout
+ while True:
+ if self._info.done:
+ return self
+ if deadline is not None and time.monotonic() >= deadline:
+ raise TimeoutError(
+ f"batch {self._info.id} still {self._info.status!r} after {timeout}s"
+ )
+ await asyncio.sleep(poll_every)
+ await self.refresh()
+
+ async def results(self) -> tuple[BatchEntry, ...]:
+ return await self._lm.batch_results(self._info.id)
+
+ async def cancel(self) -> "AsyncBatchJob":
+ self._info = await self._lm.batch_cancel(self._info.id)
+ return self
diff --git a/dspy/_vendor/lm15/cloud/__init__.py b/dspy/_vendor/lm15/cloud/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/dspy/_vendor/lm15/cloud/chains.py b/dspy/_vendor/lm15/cloud/chains.py
new file mode 100644
index 000000000..e86ed7caa
--- /dev/null
+++ b/dspy/_vendor/lm15/cloud/chains.py
@@ -0,0 +1,1280 @@
+"""
+lm15.cloud.chains — the three cloud credential chains as data over ten rung kinds.
+
+spec/auth.md AUTH-1 (``aws-chain``, ``azure-chain``, ``gcp-chain``) and
+AUTH-11 (rung kinds). Every order, variable, path and endpoint here is
+cited in lm15-contract/research/cloud-hosts/10-facts-*.md from the cloud
+SDKs' own resolver sources.
+
+Two entry points:
+
+- ``explain(policy, ctx)`` — the offline doctor walk (AUTH-7): every rung
+ reports ``selected`` / ``shadowed`` / ``absent`` / ``unprobed``. No
+ network, no subprocess: a rung that needs either is ``unprobed`` when
+ its configuration is present. The first offline-usable rung is
+ ``selected``; an ``unprobed`` rung that precedes it may still win at
+ request time, and the report says so.
+- ``credential_provider(policy, ctx)`` — the AUTH-2 provider callable:
+ resolves once, caches until the AUTH-3 skew window, re-resolves after.
+ Cache key = provider id + the identity-selecting settings.
+
+Rungs that are declared but not implemented raise ``NotConfiguredError``
+naming the gap and the fix; they never fall through silently
+(``aws login`` refresh with a DPoP key; Azure Service Fabric managed
+identity; GCP ``external_account`` with an AWS source).
+"""
+
+from __future__ import annotations
+
+import base64
+import configparser
+import hashlib
+import http.client
+import json
+import os
+import subprocess
+import threading
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Callable, Mapping
+from xml.etree import ElementTree
+
+from ..credentials import ApiKey, AwsCredentials, BearerToken, CredentialValue, parse_rfc3339
+from ..errors import AuthError, NotConfiguredError
+from ..features import RUNG_KINDS, AccessPolicy
+from . import rs256, sigv4
+
+__all__ = ["ChainContext", "Rung", "Step", "chain_for", "explain", "credential_provider",
+ "token_exchange_build", "token_exchange_parse", "RUNG_KINDS"]
+
+
+_SKEW = timedelta(seconds=300) # AUTH-3
+_GCP_SCOPE = "https://www.googleapis.com/auth/cloud-platform"
+_GCP_TOKEN_URL = "https://oauth2.googleapis.com/token"
+_GCP_STS_URL = "https://sts.googleapis.com/v1/token"
+_JWT_BEARER = "urn:ietf:params:oauth:grant-type:jwt-bearer"
+_CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+
+# ─── Context: everything a chain touches, injectable ─────────────────
+
+HttpFn = Callable[[str, str, Mapping[str, str], bytes | None, float], tuple[int, dict[str, str], bytes]]
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+ def redirect_request(self, req, fp, code, msg, headers, newurl):
+ # Never forward credential headers or token bodies to another URL.
+ return None
+
+
+def _default_http(method: str, url: str, headers: Mapping[str, str], body: bytes | None, timeout: float):
+ try:
+ req = urllib.request.Request(url, data=body, method=method, headers=dict(headers))
+ with urllib.request.build_opener(_NoRedirect()).open(req, timeout=timeout) as r:
+ return r.status, {k.lower(): v for k, v in r.headers.items()}, r.read()
+ except urllib.error.HTTPError as e:
+ with e:
+ return e.code, {k.lower(): v for k, v in e.headers.items()}, e.read()
+ except (OSError, ValueError, http.client.HTTPException):
+ raise AuthError("credential HTTP request failed") from None
+
+
+def _default_run(argv: list[str], timeout: float, *, env: Mapping[str, str] | None = None) -> str:
+ try:
+ out = subprocess.run(argv, capture_output=True, text=True, timeout=timeout, check=False, env=env)
+ except (OSError, subprocess.SubprocessError):
+ raise AuthError("credential command failed") from None
+ if out.returncode != 0:
+ raise AuthError(f"credential command exited {out.returncode}")
+ return out.stdout
+
+
+@dataclass(repr=False)
+class ChainContext:
+ """What a chain reads. ``http`` / ``run`` = None means offline (the
+ doctor). ``files`` overrides the filesystem for the harness."""
+
+ env: Mapping[str, str]
+ home: Path = field(default_factory=Path.home)
+ files: Mapping[str, str] | None = None
+ http: HttpFn | None = None
+ run: Callable[[list[str], float], str] | None = None
+ now: Callable[[], datetime] = lambda: datetime.now(timezone.utc)
+ settings: Mapping[str, str] = field(default_factory=dict)
+
+ @classmethod
+ def online(cls, env: Mapping[str, str] | None = None, **kw: Any) -> "ChainContext":
+ values = dict(env if env is not None else os.environ)
+ if "home" not in kw:
+ kw["home"] = Path(values["HOME"]) if values.get("HOME") else Path.home()
+ return cls(env=values, http=_default_http,
+ run=lambda argv, timeout: _default_run(argv, timeout, env=values), **kw)
+
+ def path(self, text: str) -> Path:
+ if text.startswith("~"):
+ return self.home / text[1:].lstrip("/\\")
+ return Path(text)
+
+ def read(self, text: str) -> str | None:
+ if self.files is not None:
+ for key, content in self.files.items():
+ if str(self.path(key)) == str(self.path(text)):
+ return content
+ return None
+ try:
+ return self.path(text).read_text(encoding="utf-8")
+ except OSError:
+ return None
+
+ def exists(self, text: str) -> bool:
+ return self.read(text) is not None
+
+ def on_path(self, command: str) -> str | None:
+ """Where ``command`` would run from, from the context's PATH only —
+ an offline file check, so the doctor can say "not installed"."""
+ if "/" in command or "\\" in command:
+ return command if self.exists(command) else None
+ path = self.env.get("PATH") or ""
+ if self.files is not None:
+ for directory in path.split(os.pathsep):
+ if directory and self.exists(f"{directory.rstrip('/')}/{command}"):
+ return f"{directory.rstrip('/')}/{command}"
+ return None
+ import shutil
+
+ return shutil.which(command, path=path) if path else None
+
+ @property
+ def offline(self) -> bool:
+ return self.http is None
+
+
+# ─── Rungs and steps ─────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Rung:
+ name: str # the fixture kind: "env:AWS_REGION", "assume-role", "imds", …
+ kind: str # RUNG_KINDS
+ source: str # human label
+ needs: str # "" (offline-usable) | "network" | "subprocess"
+ probe: Callable[["ChainContext"], tuple[str, str]] # → ("usable"|"configured"|"absent", detail)
+ acquire: Callable[["ChainContext"], CredentialValue | None] # online resolution
+
+ def __post_init__(self) -> None:
+ if self.kind not in RUNG_KINDS:
+ raise ValueError(f"unknown rung kind {self.kind!r}")
+
+
+@dataclass(frozen=True, slots=True)
+class Step:
+ kind: str
+ source: str
+ detail: str
+ state: str # selected | shadowed | absent | unprobed
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────
+
+
+def _expires_from(now: datetime, seconds: Any) -> datetime | None:
+ try:
+ return now + timedelta(seconds=int(float(seconds)))
+ except (TypeError, ValueError, OverflowError):
+ return None
+
+
+def _json_body(body: bytes) -> dict:
+ try:
+ data = json.loads(body.decode("utf-8", "replace"))
+ except ValueError:
+ return {}
+ return data if isinstance(data, dict) else {}
+
+
+def _form(pairs: list[tuple[str, str]]) -> bytes:
+ return urllib.parse.urlencode(pairs).encode("ascii")
+
+
+def _exchange(ctx: ChainContext, method: str, url: str, headers: Mapping[str, str], body: bytes | None, what: str) -> dict:
+ assert ctx.http is not None
+ status, _, raw = ctx.http(method, url, headers, body, 30.0)
+ data = _json_body(raw)
+ if not 200 <= status < 300:
+ raise AuthError(f"{what}: HTTP {status}")
+ return data
+
+
+def _bearer_from_oauth(data: dict, now: datetime, what: str) -> BearerToken:
+ token = data.get("access_token")
+ if not isinstance(token, str) or not token:
+ raise AuthError(f"{what}: no valid access_token in response")
+ expires = None
+ if data.get("expires_on") not in (None, ""):
+ try:
+ expires = datetime.fromtimestamp(int(float(data["expires_on"])), tz=timezone.utc)
+ except (TypeError, ValueError, OverflowError, OSError):
+ expires = None
+ if expires is None and data.get("expires_in") not in (None, ""):
+ expires = _expires_from(now, data["expires_in"])
+ return BearerToken(token, expires_at=expires)
+
+
+# ─── AWS ─────────────────────────────────────────────────────────────
+
+
+def _aws_config(ctx: ChainContext) -> tuple[configparser.ConfigParser, configparser.ConfigParser, str]:
+ profile = ctx.env.get("AWS_PROFILE") or "default"
+ creds = configparser.ConfigParser(interpolation=None)
+ conf = configparser.ConfigParser(interpolation=None)
+ text = ctx.read(ctx.env.get("AWS_SHARED_CREDENTIALS_FILE") or "~/.aws/credentials")
+ try:
+ if text:
+ creds.read_string(text)
+ text = ctx.read(ctx.env.get("AWS_CONFIG_FILE") or "~/.aws/config")
+ if text:
+ conf.read_string(text)
+ except configparser.Error:
+ raise NotConfiguredError("malformed AWS profile configuration; check the AWS config and credentials files") from None
+ return creds, conf, profile
+
+
+def _aws_profile_section(conf: configparser.ConfigParser, profile: str) -> Mapping[str, str]:
+ name = profile if profile == "default" else f"profile {profile}"
+ if conf.has_section(name):
+ return conf[name]
+ if conf.has_section(profile):
+ return conf[profile]
+ return {}
+
+
+def _aws_static(section: Mapping[str, str], expiry: str | None = None) -> AwsCredentials | None:
+ key, secret = section.get("aws_access_key_id"), section.get("aws_secret_access_key")
+ if not key or not secret:
+ return None
+ return AwsCredentials(key, secret, session_token=section.get("aws_session_token") or None)
+
+
+def _aws_from_response(d: Mapping[str, Any]) -> AwsCredentials:
+ expires = None
+ raw = d.get("Expiration") or d.get("expiration")
+ if isinstance(raw, str):
+ expires = parse_rfc3339(raw)
+ elif isinstance(raw, (int, float)):
+ expires = datetime.fromtimestamp(raw / (1000 if raw > 10**11 else 1), tz=timezone.utc)
+ key = d.get("AccessKeyId") or d.get("accessKeyId")
+ secret = d.get("SecretAccessKey") or d.get("secretAccessKey")
+ if not isinstance(key, str) or not key or not isinstance(secret, str) or not secret:
+ raise AuthError("AWS credential response lacks access key id or secret access key")
+ return AwsCredentials(
+ key,
+ secret,
+ session_token=(d.get("SessionToken") or d.get("Token") or d.get("sessionToken")) or None,
+ expires_at=expires,
+ )
+
+
+def _sts_xml_credentials(raw: bytes) -> AwsCredentials:
+ root = ElementTree.fromstring(raw)
+ ns = {"sts": "https://sts.amazonaws.com/doc/2011-06-15/"}
+ node = root.find(".//sts:Credentials", ns)
+ if node is None:
+ raise AuthError("STS: no Credentials in response")
+ get = lambda tag: (node.findtext(f"sts:{tag}", namespaces=ns) or "") # noqa: E731
+ return AwsCredentials(get("AccessKeyId"), get("SecretAccessKey"), session_token=get("SessionToken") or None,
+ expires_at=parse_rfc3339(get("Expiration")) if get("Expiration") else None)
+
+
+def _aws_source_credentials(ctx: ChainContext, section: Mapping[str, str], depth: int = 0) -> AwsCredentials:
+ """Source credentials for assume-role: source_profile (recursive) or credential_source."""
+ if depth > 5:
+ raise AuthError("assume-role: source_profile chain too deep")
+ source_profile = section.get("source_profile")
+ if source_profile:
+ creds, conf, _ = _aws_config(ctx)
+ sub = dict(_aws_profile_section(conf, source_profile))
+ if creds.has_section(source_profile):
+ sub.update(creds[source_profile])
+ if sub.get("role_arn"):
+ return _assume_role(ctx, sub, depth + 1)
+ static = _aws_static(sub)
+ if static is None:
+ raise NotConfiguredError(f"assume-role: source_profile {source_profile!r} has no keys")
+ return static
+ source = section.get("credential_source")
+ if source == "Environment":
+ static = _env_aws(ctx)
+ if static is None:
+ raise NotConfiguredError("assume-role: credential_source=Environment but AWS_ACCESS_KEY_ID is not set")
+ return static
+ if source == "EcsContainer":
+ got = _container_acquire(ctx)
+ if got is None:
+ raise NotConfiguredError("assume-role: credential_source=EcsContainer but no container endpoint is configured")
+ return got
+ if source == "Ec2InstanceMetadata":
+ got = _imds_acquire(ctx)
+ if got is None:
+ raise NotConfiguredError("assume-role: credential_source=Ec2InstanceMetadata but IMDS answered nothing")
+ return got
+ raise NotConfiguredError("assume-role: profile needs source_profile or credential_source")
+
+
+def _assume_role(ctx: ChainContext, section: Mapping[str, str], depth: int = 0) -> AwsCredentials:
+ source = _aws_source_credentials(ctx, section, depth)
+ region = ctx.settings.get("region") or ctx.env.get("AWS_REGION") or ctx.env.get("AWS_DEFAULT_REGION") or section.get("region") or "us-east-1"
+ url = f"https://sts.{region}.amazonaws.com/"
+ pairs = [("Action", "AssumeRole"), ("Version", "2011-06-15"), ("RoleArn", section["role_arn"]),
+ ("RoleSessionName", section.get("role_session_name") or f"lm15-{uuid.uuid4().hex[:12]}")]
+ if section.get("external_id"):
+ pairs.append(("ExternalId", section["external_id"]))
+ if section.get("duration_seconds"):
+ pairs.append(("DurationSeconds", section["duration_seconds"]))
+ body = _form(pairs)
+ headers = {"content-type": "application/x-www-form-urlencoded"}
+ signed = sigv4.sign(method="POST", url=url, headers=headers, payload=body, credentials=source, region=region, service="sts", now=ctx.now())
+ assert ctx.http is not None
+ status, _, raw = ctx.http("POST", url, signed.headers, body, 30.0)
+ if status >= 400:
+ raise AuthError(f"STS AssumeRole: HTTP {status}")
+ return _sts_xml_credentials(raw)
+
+
+def _env_aws(ctx: ChainContext) -> AwsCredentials | None:
+ key, secret = ctx.env.get("AWS_ACCESS_KEY_ID"), ctx.env.get("AWS_SECRET_ACCESS_KEY")
+ if key and secret:
+ return AwsCredentials(key, secret, session_token=ctx.env.get("AWS_SESSION_TOKEN") or None)
+ return None
+
+
+def _web_identity_config(ctx: ChainContext) -> tuple[str, str, str] | None:
+ token_file, role = ctx.env.get("AWS_WEB_IDENTITY_TOKEN_FILE"), ctx.env.get("AWS_ROLE_ARN")
+ session = ctx.env.get("AWS_ROLE_SESSION_NAME") or ""
+ if not (token_file and role):
+ _, conf, profile = _aws_config(ctx)
+ section = _aws_profile_section(conf, profile)
+ token_file, role = section.get("web_identity_token_file"), section.get("role_arn")
+ session = section.get("role_session_name") or ""
+ if not (token_file and role and not section.get("source_profile") and not section.get("credential_source")):
+ return None
+ return token_file, role, session
+
+
+def _web_identity_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ cfg = _web_identity_config(ctx)
+ if cfg is None:
+ return None
+ token_file, role, session = cfg
+ token = ctx.read(token_file)
+ if token is None:
+ raise NotConfiguredError(f"web identity token file {token_file} is unreadable")
+ region = ctx.settings.get("region") or ctx.env.get("AWS_REGION") or ctx.env.get("AWS_DEFAULT_REGION") or "us-east-1"
+ body = _form([("Action", "AssumeRoleWithWebIdentity"), ("Version", "2011-06-15"), ("RoleArn", role),
+ ("RoleSessionName", session or f"lm15-{uuid.uuid4().hex[:12]}"), ("WebIdentityToken", token.strip())])
+ assert ctx.http is not None
+ status, _, raw = ctx.http("POST", f"https://sts.{region}.amazonaws.com/", {"content-type": "application/x-www-form-urlencoded"}, body, 30.0)
+ if status >= 400:
+ raise AuthError(f"STS AssumeRoleWithWebIdentity: HTTP {status}")
+ return _sts_xml_credentials(raw)
+
+
+def _sso_config(ctx: ChainContext) -> dict[str, str] | None:
+ _, conf, profile = _aws_config(ctx)
+ section = dict(_aws_profile_section(conf, profile))
+ if section.get("sso_session"):
+ name = section["sso_session"]
+ sess = dict(conf[f"sso-session {name}"]) if conf.has_section(f"sso-session {name}") else {}
+ if not sess.get("sso_start_url"):
+ return None
+ cache_key = hashlib.sha1(name.encode("utf-8")).hexdigest()
+ return {**sess, **section, "cache_key": cache_key, "session_name": name}
+ if section.get("sso_start_url"):
+ cache_key = hashlib.sha1(section["sso_start_url"].encode("utf-8")).hexdigest()
+ return {**section, "cache_key": cache_key}
+ return None
+
+
+def _sso_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ cfg = _sso_config(ctx)
+ if cfg is None:
+ return None
+ raw = ctx.read(f"~/.aws/sso/cache/{cfg['cache_key']}.json")
+ if raw is None:
+ raise NotConfiguredError("IAM Identity Center: no cached token; run `aws sso login`", credential_hint="aws sso login")
+ token = json.loads(raw)
+ now = ctx.now()
+ expires = parse_rfc3339(token["expiresAt"]) if token.get("expiresAt") else None
+ access = token.get("accessToken")
+ sso_region = cfg.get("sso_region") or "us-east-1"
+ assert ctx.http is not None
+ if not access or (expires is not None and expires - now <= _SKEW):
+ if not (token.get("refreshToken") and token.get("clientId") and token.get("clientSecret")):
+ raise NotConfiguredError("IAM Identity Center: token expired and not refreshable; run `aws sso login`", credential_hint="aws sso login")
+ data = _exchange(ctx, "POST", f"https://oidc.{sso_region}.amazonaws.com/token", {"content-type": "application/json"},
+ json.dumps({"clientId": token["clientId"], "clientSecret": token["clientSecret"],
+ "grantType": "refresh_token", "refreshToken": token["refreshToken"]}).encode(), "sso-oidc CreateToken")
+ access = data.get("accessToken")
+ if not access:
+ raise AuthError("sso-oidc CreateToken: no accessToken")
+ account, role = cfg.get("sso_account_id"), cfg.get("sso_role_name")
+ if not (account and role):
+ raise NotConfiguredError("IAM Identity Center: profile needs sso_account_id and sso_role_name")
+ query = urllib.parse.urlencode({"role_name": role, "account_id": account})
+ status, _, raw_creds = ctx.http("GET", f"https://portal.sso.{sso_region}.amazonaws.com/federation/credentials?{query}",
+ {"x-amz-sso_bearer_token": str(access)}, None, 30.0)
+ if status >= 400:
+ raise AuthError(f"sso GetRoleCredentials: HTTP {status}")
+ creds = _json_body(raw_creds).get("roleCredentials") or {}
+ return _aws_from_response(creds)
+
+
+def _login_config(ctx: ChainContext) -> str | None:
+ _, conf, profile = _aws_config(ctx)
+ return _aws_profile_section(conf, profile).get("login_session") or None
+
+
+def _login_cached(ctx: ChainContext) -> AwsCredentials | None:
+ session = _login_config(ctx)
+ if not session:
+ return None
+ directory = ctx.env.get("AWS_LOGIN_CACHE_DIRECTORY") or "~/.aws/login/cache"
+ raw = ctx.read(f"{directory}/{hashlib.sha256(session.encode('utf-8')).hexdigest()}.json")
+ if raw is None:
+ return None
+ token = json.loads(raw).get("accessToken") or {}
+ if not token.get("accessKeyId"):
+ return None
+ return _aws_from_response({"AccessKeyId": token["accessKeyId"], "SecretAccessKey": token.get("secretAccessKey"),
+ "SessionToken": token.get("sessionToken"), "Expiration": token.get("expiresAt")})
+
+
+def _login_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ if _login_config(ctx) is None:
+ return None
+ cached = _login_cached(ctx)
+ if cached is not None and not cached.is_expired(ctx.now()):
+ return cached
+ # Refresh needs the signin CreateOAuth2Token call with a DPoP proof over
+ # the cached EC key (botocore credentials.py LoginCredentialFetcher):
+ # a stated gap; the hint names the command.
+ raise NotConfiguredError("AWS login session expired; run `aws login`", credential_hint="aws login")
+
+
+def _process_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ _, conf, profile = _aws_config(ctx)
+ command = _aws_profile_section(conf, profile).get("credential_process")
+ if not command:
+ return None
+ if ctx.run is None:
+ return None
+ import shlex
+
+ out = ctx.run(shlex.split(command), 60.0)
+ data = _json_body(out.encode())
+ if data.get("Version") != 1:
+ raise AuthError("credential_process: output Version must be 1")
+ return _aws_from_response(data)
+
+
+_CONTAINER_ALLOWED = {"169.254.170.2", "169.254.170.23", "fd00:ec2::23", "localhost"}
+
+
+def _container_config(ctx: ChainContext) -> str | None:
+ rel, full = ctx.env.get("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI"), ctx.env.get("AWS_CONTAINER_CREDENTIALS_FULL_URI")
+ if rel:
+ if not rel.startswith("/") or rel.startswith("//") or any(c in rel for c in "\\\r\n\t#"):
+ raise NotConfiguredError("container credentials relative URI must be an absolute path")
+ return f"http://169.254.170.2{rel}"
+ if full:
+ import ipaddress
+
+ parsed = urllib.parse.urlsplit(full)
+ host = parsed.hostname or ""
+ if parsed.scheme not in ("http", "https") or not host or parsed.username is not None or parsed.fragment:
+ raise NotConfiguredError("container credentials URI must be HTTP(S), without userinfo or fragment")
+ loopback = False
+ try:
+ loopback = ipaddress.ip_address(host).is_loopback
+ except ValueError:
+ pass
+ if parsed.scheme != "https" and not loopback and host not in _CONTAINER_ALLOWED:
+ raise NotConfiguredError(
+ f"Unsupported host {host!r}. Can only retrieve metadata from a loopback address or one of these hosts: "
+ + ", ".join(sorted(_CONTAINER_ALLOWED))
+ )
+ return full
+ return None
+
+
+def _container_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ url = _container_config(ctx)
+ if url is None or ctx.http is None:
+ return None
+ headers: dict[str, str] = {}
+ token = ctx.env.get("AWS_CONTAINER_AUTHORIZATION_TOKEN")
+ token_file = ctx.env.get("AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE")
+ if token_file and not token:
+ token = (ctx.read(token_file) or "").strip()
+ if token:
+ headers["Authorization"] = token
+ status, _, raw = ctx.http("GET", url, headers, None, 5.0)
+ if status >= 400:
+ raise AuthError(f"container credentials: HTTP {status}")
+ return _aws_from_response(_json_body(raw))
+
+
+def _imds_disabled(ctx: ChainContext) -> bool:
+ return (ctx.env.get("AWS_EC2_METADATA_DISABLED") or "").strip().lower() == "true"
+
+
+def _imds_acquire(ctx: ChainContext) -> AwsCredentials | None:
+ if _imds_disabled(ctx) or ctx.http is None:
+ return None
+ base = ctx.env.get("AWS_EC2_METADATA_SERVICE_ENDPOINT") or (
+ "http://[fd00:ec2::254]" if (ctx.env.get("AWS_EC2_METADATA_SERVICE_ENDPOINT_MODE") or "").lower() == "ipv6" else "http://169.254.169.254"
+ )
+ base = base.rstrip("/")
+ try:
+ status, _, tok = ctx.http("PUT", f"{base}/latest/api/token", {"X-aws-ec2-metadata-token-ttl-seconds": "21600"}, None, 1.0)
+ except Exception: # noqa: BLE001 - not on EC2: the rung is absent, not an error
+ return None
+ if status != 200:
+ return None
+ headers = {"X-aws-ec2-metadata-token": tok.decode("utf-8", "replace")}
+ status, _, role = ctx.http("GET", f"{base}/latest/meta-data/iam/security-credentials/", headers, None, 1.0)
+ if status != 200 or not role.strip():
+ return None
+ status, _, raw = ctx.http("GET", f"{base}/latest/meta-data/iam/security-credentials/{role.decode().strip().splitlines()[0]}", headers, None, 1.0)
+ if status != 200:
+ return None
+ data = _json_body(raw)
+ if data.get("Code") not in (None, "Success"):
+ raise AuthError("IMDS rejected the credential request")
+ return _aws_from_response(data)
+
+
+def _aws_chain(policy: AccessPolicy) -> list[Rung]:
+ door_key = policy.env_keys[0] if policy.env_keys else None
+
+ def env_probe(var: str):
+ return lambda ctx: ("usable", "set (value never shown)") if ctx.env.get(var) else ("absent", "not set")
+
+ def static_keys_probe(ctx: ChainContext):
+ return ("usable", "set (values never shown)") if _env_aws(ctx) else ("absent", "AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY not set")
+
+ def assume_role_probe(ctx: ChainContext):
+ _, conf, profile = _aws_config(ctx)
+ section = _aws_profile_section(conf, profile)
+ if section.get("role_arn") and (section.get("source_profile") or section.get("credential_source")):
+ return ("configured", f"profile {profile!r} assumes {section['role_arn']} (STS call at request time)")
+ return ("absent", f"profile {profile!r} has no role_arn with a source")
+
+ def assume_role_acquire(ctx: ChainContext):
+ _, conf, profile = _aws_config(ctx)
+ section = _aws_profile_section(conf, profile)
+ if section.get("role_arn") and (section.get("source_profile") or section.get("credential_source")):
+ return _assume_role(ctx, section)
+ return None
+
+ def web_identity_probe(ctx: ChainContext):
+ cfg = _web_identity_config(ctx)
+ return ("configured", f"token file {cfg[0]} → {cfg[1]} (STS call at request time)") if cfg else ("absent", "AWS_WEB_IDENTITY_TOKEN_FILE / AWS_ROLE_ARN not set")
+
+ def sso_probe(ctx: ChainContext):
+ cfg = _sso_config(ctx)
+ if cfg is None:
+ return ("absent", "no sso_session / sso_start_url in the profile")
+ cached = ctx.exists(f"~/.aws/sso/cache/{cfg['cache_key']}.json")
+ return ("configured", "cached token present (GetRoleCredentials at request time)" if cached else "no cached token; run `aws sso login`")
+
+ def shared_file_probe(ctx: ChainContext):
+ creds, _, profile = _aws_config(ctx)
+ section = creds[profile] if creds.has_section(profile) else {}
+ return ("usable", f"profile {profile!r} (values never shown)") if _aws_static(section) else ("absent", f"no keys for profile {profile!r}")
+
+ def shared_file_acquire(ctx: ChainContext):
+ creds, _, profile = _aws_config(ctx)
+ return _aws_static(creds[profile]) if creds.has_section(profile) else None
+
+ def login_probe(ctx: ChainContext):
+ if _login_config(ctx) is None:
+ return ("absent", "no login_session in the profile")
+ cached = _login_cached(ctx)
+ if cached is not None and not cached.is_expired(ctx.now()):
+ return ("usable", "cached short-term credentials are fresh")
+ return ("configured", "cached credentials missing or expired; refresh needs `aws login`")
+
+ def process_probe(ctx: ChainContext):
+ _, conf, profile = _aws_config(ctx)
+ cmd = _aws_profile_section(conf, profile).get("credential_process")
+ if not cmd:
+ return ("absent", "no credential_process in the profile")
+ import shlex
+
+ executable = shlex.split(cmd)[0]
+ if ctx.on_path(executable) is None:
+ return ("absent", f"credential_process {executable!r} is not on PATH")
+ return ("configured", "credential_process configured (run at request time)")
+
+ def config_file_probe(ctx: ChainContext):
+ _, conf, profile = _aws_config(ctx)
+ return ("usable", f"static keys in config for profile {profile!r}") if _aws_static(_aws_profile_section(conf, profile)) else ("absent", "no static keys in config")
+
+ def config_file_acquire(ctx: ChainContext):
+ _, conf, profile = _aws_config(ctx)
+ return _aws_static(_aws_profile_section(conf, profile))
+
+ def container_probe(ctx: ChainContext):
+ try:
+ url = _container_config(ctx)
+ except NotConfiguredError as exc:
+ return ("absent", str(exc).splitlines()[0])
+ return ("configured", "container endpoint configured (HTTP at request time)") if url else ("absent", "no AWS_CONTAINER_CREDENTIALS_* URI")
+
+ def imds_probe(ctx: ChainContext):
+ return ("absent", "AWS_EC2_METADATA_DISABLED=true") if _imds_disabled(ctx) else ("configured", "instance metadata probed at request time")
+
+ rungs: list[Rung] = []
+ if door_key:
+ kind_cred = BearerToken if door_key == "AWS_BEARER_TOKEN_BEDROCK" else ApiKey
+ rungs.append(Rung(f"env:{door_key}", "env", f"env ${door_key}", "", env_probe(door_key),
+ lambda ctx, k=door_key, c=kind_cred: c(ctx.env[k]) if ctx.env.get(k) else None))
+ rungs += [
+ Rung("env:AWS_ACCESS_KEY_ID", "env", "env $AWS_ACCESS_KEY_ID (+SECRET, +SESSION_TOKEN)", "", static_keys_probe, _env_aws),
+ Rung("assume-role", "sigv4-sts", "profile assume-role via STS", "network", assume_role_probe, assume_role_acquire),
+ Rung("web-identity", "unsigned-sts", "web identity via STS", "network", web_identity_probe, _web_identity_acquire),
+ Rung("sso", "file-cache", "IAM Identity Center (~/.aws/sso/cache)", "network", sso_probe, _sso_acquire),
+ Rung("shared-credentials-file", "ini-profile", "~/.aws/credentials", "", shared_file_probe, shared_file_acquire),
+ Rung("login", "file-cache", "aws login session (~/.aws/login/cache)", "", login_probe, _login_acquire),
+ Rung("credential_process", "subprocess", "profile credential_process", "subprocess", process_probe, _process_acquire),
+ Rung("config-file", "ini-profile", "~/.aws/config static keys", "", config_file_probe, config_file_acquire),
+ Rung("container", "http-metadata", "container credentials endpoint", "network", container_probe, _container_acquire),
+ Rung("imds", "http-metadata", "EC2 instance metadata (IMDSv2)", "network", imds_probe, _imds_acquire),
+ ]
+ return rungs
+
+
+# ─── Azure ───────────────────────────────────────────────────────────
+
+
+def _azure_authority(ctx: ChainContext) -> str:
+ return (ctx.settings.get("authority_host") or ctx.env.get("AZURE_AUTHORITY_HOST") or "https://login.microsoftonline.com").rstrip("/")
+
+
+def _azure_scope(ctx: ChainContext) -> str:
+ return ctx.settings.get("scope") or "https://ai.azure.com/.default"
+
+
+def _azure_token_url(ctx: ChainContext, tenant: str) -> str:
+ return f"{_azure_authority(ctx)}/{tenant}/oauth2/v2.0/token"
+
+
+def azure_certificate_assertion(ctx: ChainContext, tenant: str, client_id: str, pem: str, *, jti: str | None = None,
+ send_chain: bool = False) -> str:
+ """The Entra client assertion: RS256 (as azure-identity signs it), ``x5t``
+ = base64url SHA-1 of the DER certificate, claims in MSAL's order
+ (assertion.py:99-118), 600 s lifetime."""
+ key = rs256.load_private_key(pem)
+ der = rs256.certificate_der(pem)
+ now = int(ctx.now().timestamp())
+ header: dict[str, Any] = {"alg": "RS256", "typ": "JWT", "x5t": rs256.b64url(hashlib.sha1(der).digest())}
+ if send_chain:
+ header["x5c"] = [base64.b64encode(der).decode("ascii")]
+ payload = {"aud": _azure_token_url(ctx, tenant), "iss": client_id, "sub": client_id,
+ "exp": now + 600, "iat": now, "jti": jti or str(uuid.uuid4())}
+ return rs256.jwt_encode(header, payload, key)
+
+
+def _azure_environment_kind(ctx: ChainContext) -> str | None:
+ e = ctx.env
+ if not (e.get("AZURE_TENANT_ID") and e.get("AZURE_CLIENT_ID")):
+ return None
+ if e.get("AZURE_CLIENT_SECRET"):
+ return "secret"
+ if e.get("AZURE_CLIENT_CERTIFICATE_PATH"):
+ return "certificate"
+ return None
+
+
+def azure_environment_request(ctx: ChainContext, *, jti: str | None = None) -> tuple[str, list[tuple[str, str]]]:
+ """(token URL, form pairs) for the environment service principal."""
+ e = ctx.env
+ kind = _azure_environment_kind(ctx)
+ tenant, client = e["AZURE_TENANT_ID"], e["AZURE_CLIENT_ID"]
+ url = _azure_token_url(ctx, tenant)
+ scope = _azure_scope(ctx)
+ if kind == "secret":
+ return url, [("client_id", client), ("scope", scope), ("client_secret", e["AZURE_CLIENT_SECRET"]), ("grant_type", "client_credentials")]
+ if kind == "certificate":
+ pem = ctx.read(e["AZURE_CLIENT_CERTIFICATE_PATH"])
+ if pem is None:
+ raise NotConfiguredError(f"AZURE_CLIENT_CERTIFICATE_PATH {e['AZURE_CLIENT_CERTIFICATE_PATH']} is unreadable")
+ if e.get("AZURE_CLIENT_CERTIFICATE_PASSWORD"):
+ raise NotConfiguredError("password-protected certificates are not supported; decrypt with `openssl pkey`",
+ credential_hint="openssl pkey -in cert.pem -out cert-plain.pem")
+ send_chain = (e.get("AZURE_CLIENT_SEND_CERTIFICATE_CHAIN") or "").lower() in ("1", "true")
+ assertion = azure_certificate_assertion(ctx, tenant, client, pem, jti=jti, send_chain=send_chain)
+ return url, [("client_id", client), ("scope", scope), ("client_assertion_type", _CLIENT_ASSERTION_TYPE),
+ ("client_assertion", assertion), ("grant_type", "client_credentials")]
+ raise NotConfiguredError("Azure environment credential needs AZURE_CLIENT_SECRET or AZURE_CLIENT_CERTIFICATE_PATH")
+
+
+def _azure_environment_acquire(ctx: ChainContext) -> BearerToken | None:
+ if _azure_environment_kind(ctx) is None:
+ return None
+ url, pairs = azure_environment_request(ctx)
+ data = _exchange(ctx, "POST", url, {"content-type": "application/x-www-form-urlencoded"}, _form(pairs), "Entra client credentials")
+ return _bearer_from_oauth(data, ctx.now(), "Entra")
+
+
+def _azure_workload_config(ctx: ChainContext) -> bool:
+ e = ctx.env
+ return bool(e.get("AZURE_FEDERATED_TOKEN_FILE") and e.get("AZURE_CLIENT_ID") and e.get("AZURE_TENANT_ID"))
+
+
+def _azure_workload_acquire(ctx: ChainContext) -> BearerToken | None:
+ if not _azure_workload_config(ctx):
+ return None
+ e = ctx.env
+ token = ctx.read(e["AZURE_FEDERATED_TOKEN_FILE"])
+ if token is None:
+ raise NotConfiguredError(f"AZURE_FEDERATED_TOKEN_FILE {e['AZURE_FEDERATED_TOKEN_FILE']} is unreadable")
+ pairs = [("client_id", e["AZURE_CLIENT_ID"]), ("scope", _azure_scope(ctx)), ("client_assertion_type", _CLIENT_ASSERTION_TYPE),
+ ("client_assertion", token.strip()), ("grant_type", "client_credentials")]
+ data = _exchange(ctx, "POST", _azure_token_url(ctx, e["AZURE_TENANT_ID"]), {"content-type": "application/x-www-form-urlencoded"}, _form(pairs), "Entra workload identity")
+ return _bearer_from_oauth(data, ctx.now(), "Entra")
+
+
+def _azure_msi_flavor(ctx: ChainContext) -> str:
+ e = ctx.env
+ if e.get("IDENTITY_ENDPOINT"):
+ if e.get("IDENTITY_HEADER"):
+ return "service-fabric" if e.get("IDENTITY_SERVER_THUMBPRINT") else "app-service"
+ if e.get("IMDS_ENDPOINT"):
+ return "azure-arc"
+ if e.get("MSI_ENDPOINT"):
+ return "azure-ml" if e.get("MSI_SECRET") else "cloud-shell"
+ return "imds"
+
+
+def _azure_msi_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.http is None:
+ return None
+ e = ctx.env
+ flavor = _azure_msi_flavor(ctx)
+ resource = _azure_scope(ctx).removesuffix("/.default")
+ client_id = e.get("AZURE_CLIENT_ID")
+ now = ctx.now()
+ if flavor == "imds":
+ query = {"api-version": "2018-02-01", "resource": resource}
+ if client_id:
+ query["client_id"] = client_id
+ try:
+ status, _, raw = ctx.http("GET", "http://169.254.169.254/metadata/identity/oauth2/token?" + urllib.parse.urlencode(query), {"Metadata": "true"}, None, 1.0)
+ except Exception: # noqa: BLE001 - not on Azure: absent
+ return None
+ if status != 200:
+ return None
+ return _bearer_from_oauth(_json_body(raw), now, "managed identity")
+ if flavor == "app-service":
+ query = {"api-version": "2019-08-01", "resource": resource}
+ if client_id:
+ query["client_id"] = client_id
+ data = _exchange(ctx, "GET", e["IDENTITY_ENDPOINT"] + "?" + urllib.parse.urlencode(query), {"X-IDENTITY-HEADER": e["IDENTITY_HEADER"]}, None, "App Service managed identity")
+ return _bearer_from_oauth(data, now, "managed identity")
+ if flavor == "cloud-shell":
+ data = _exchange(ctx, "POST", e["MSI_ENDPOINT"], {"Metadata": "true", "content-type": "application/x-www-form-urlencoded"}, _form([("resource", resource)]), "Cloud Shell managed identity")
+ return _bearer_from_oauth(data, now, "managed identity")
+ if flavor == "azure-ml":
+ query = {"api-version": "2017-09-01", "resource": resource}
+ if client_id:
+ query["clientid"] = client_id
+ data = _exchange(ctx, "GET", e["MSI_ENDPOINT"] + "?" + urllib.parse.urlencode(query), {"secret": e["MSI_SECRET"]}, None, "Azure ML managed identity")
+ return _bearer_from_oauth(data, now, "managed identity")
+ if flavor == "azure-arc":
+ url = e["IDENTITY_ENDPOINT"] + "?" + urllib.parse.urlencode({"api-version": "2019-11-01", "resource": resource})
+ status, headers, _ = ctx.http("GET", url, {"Metadata": "true"}, None, 5.0)
+ challenge = headers.get("www-authenticate", "")
+ if status != 401 or "realm=" not in challenge:
+ raise AuthError(f"Azure Arc managed identity: expected a 401 challenge, got {status}")
+ key_path = challenge.split("realm=", 1)[1].strip().strip('"')
+ directory = (Path(ctx.env.get("PROGRAMDATA", "C:/ProgramData")) / "AzureConnectedMachineAgent" / "Tokens"
+ if os.name == "nt" else Path("/var/opt/azcmagent/tokens"))
+ path = Path(key_path)
+ if path.parent != directory or path.suffix != ".key":
+ raise AuthError("Azure Arc managed identity: invalid challenge file location")
+ if ctx.files is None and path.resolve().parent != directory.resolve():
+ raise AuthError("Azure Arc managed identity: invalid challenge file location")
+ secret = ctx.read(key_path)
+ if secret is None or len(secret) > 4096:
+ raise AuthError("Azure Arc managed identity: challenge file missing or too large")
+ data = _exchange(ctx, "GET", url, {"Metadata": "true", "Authorization": f"Basic {secret.strip()}"}, None, "Azure Arc managed identity")
+ return _bearer_from_oauth(data, now, "managed identity")
+ raise NotConfiguredError("Service Fabric managed identity (TLS thumbprint pinning) is not supported; use a certificate or secret")
+
+
+def _az_cli_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.run is None or ctx.on_path("az") is None:
+ return None
+ argv = ["az", "account", "get-access-token", "--output", "json", "--scope", _azure_scope(ctx)]
+ tenant = ctx.env.get("AZURE_TENANT_ID")
+ if tenant:
+ argv += ["--tenant", tenant]
+ data = _json_body(ctx.run(argv, 30.0).encode())
+ token = data.get("accessToken")
+ if token is None:
+ return None
+ parsed = _bearer_from_oauth({"access_token": token, "expires_on": data.get("expires_on")}, ctx.now(), "Azure CLI")
+ expires = parsed.expires_at
+ if expires is None and data.get("expiresOn"):
+ try:
+ expires = datetime.fromisoformat(str(data["expiresOn"])).astimezone(timezone.utc)
+ except (ValueError, OverflowError, OSError):
+ expires = None
+ return BearerToken(parsed.value, expires_at=expires)
+
+
+def _pwsh_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.run is None or ctx.on_path("pwsh") is None:
+ return None
+ resource = _azure_scope(ctx).removesuffix("/.default").replace("'", "''")
+ script = f"Get-AzAccessToken -ResourceUrl '{resource}' -AsSecureString:$false | ConvertTo-Json -Compress"
+ data = _json_body(ctx.run(["pwsh", "-NoProfile", "-NonInteractive", "-Command", script], 30.0).encode())
+ token = data.get("Token")
+ return _bearer_from_oauth({"access_token": token}, ctx.now(), "Azure PowerShell") if token is not None else None
+
+
+def _azd_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.run is None or ctx.on_path("azd") is None:
+ return None
+ data = _json_body(ctx.run(["azd", "auth", "token", "--output", "json", "--scope", _azure_scope(ctx)], 30.0).encode())
+ token = data.get("token")
+ if token is None:
+ return None
+ parsed = _bearer_from_oauth({"access_token": token}, ctx.now(), "Azure Developer CLI")
+ expires = None
+ if data.get("expiresOn"):
+ try:
+ expires = parse_rfc3339(str(data["expiresOn"]))
+ except ValueError:
+ expires = None
+ return BearerToken(parsed.value, expires_at=expires)
+
+
+def _azure_chain(policy: AccessPolicy) -> list[Rung]:
+ door_key = policy.env_keys[0] if policy.env_keys else None
+
+ def narrowed(ctx: ChainContext, name: str, developer: bool) -> bool:
+ """AZURE_TOKEN_CREDENTIALS=prod|dev|<CredentialName> narrowing."""
+ value = (ctx.env.get("AZURE_TOKEN_CREDENTIALS") or "").strip().lower()
+ if not value:
+ return False
+ if value == "prod":
+ return developer
+ if value == "dev":
+ return not developer
+ return value != name.lower()
+
+ def env_probe(ctx: ChainContext):
+ if narrowed(ctx, "EnvironmentCredential", False):
+ return ("absent", "excluded by AZURE_TOKEN_CREDENTIALS")
+ kind = _azure_environment_kind(ctx)
+ return ("configured", f"service principal by {kind} (token exchange at request time)") if kind else ("absent", "AZURE_TENANT_ID/AZURE_CLIENT_ID + secret or certificate not set")
+
+ def workload_probe(ctx: ChainContext):
+ if narrowed(ctx, "WorkloadIdentityCredential", False):
+ return ("absent", "excluded by AZURE_TOKEN_CREDENTIALS")
+ return ("configured", "federated token file present (exchange at request time)") if _azure_workload_config(ctx) else ("absent", "AZURE_FEDERATED_TOKEN_FILE not set")
+
+ def msi_probe(ctx: ChainContext):
+ if narrowed(ctx, "ManagedIdentityCredential", False):
+ return ("absent", "excluded by AZURE_TOKEN_CREDENTIALS")
+ return ("configured", f"managed identity ({_azure_msi_flavor(ctx)}) probed at request time")
+
+ def cli_probe(name: str, label: str, command: str):
+ def probe(ctx: ChainContext):
+ if narrowed(ctx, name, True):
+ return ("absent", "excluded by AZURE_TOKEN_CREDENTIALS")
+ if ctx.on_path(command) is None:
+ return ("absent", f"{command} is not on PATH")
+ return ("configured", f"{label} run at request time")
+ return probe
+
+ def guard(fn, name: str, developer: bool):
+ return lambda ctx: None if narrowed(ctx, name, developer) else fn(ctx)
+
+ rungs: list[Rung] = []
+ if door_key:
+ rungs.append(Rung(f"env:{door_key}", "env", f"env ${door_key}", "",
+ lambda ctx, k=door_key: ("usable", "set (value never shown)") if ctx.env.get(k) else ("absent", "not set"),
+ lambda ctx, k=door_key: ApiKey(ctx.env[k]) if ctx.env.get(k) else None))
+ rungs += [
+ Rung("environment", "http-token-exchange", "Entra service principal from AZURE_* env", "network", env_probe, guard(_azure_environment_acquire, "EnvironmentCredential", False)),
+ Rung("workload-identity", "http-token-exchange", "Entra workload identity", "network", workload_probe, guard(_azure_workload_acquire, "WorkloadIdentityCredential", False)),
+ Rung("managed-identity", "http-metadata", "Azure managed identity", "network", msi_probe, guard(_azure_msi_acquire, "ManagedIdentityCredential", False)),
+ Rung("az", "subprocess", "az account get-access-token", "subprocess", cli_probe("AzureCliCredential", "`az`", "az"), guard(_az_cli_acquire, "AzureCliCredential", True)),
+ Rung("pwsh", "subprocess", "Azure PowerShell Get-AzAccessToken", "subprocess", cli_probe("AzurePowerShellCredential", "`pwsh`", "pwsh"), guard(_pwsh_acquire, "AzurePowerShellCredential", True)),
+ Rung("azd", "subprocess", "azd auth token", "subprocess", cli_probe("AzureDeveloperCliCredential", "`azd`", "azd"), guard(_azd_acquire, "AzureDeveloperCliCredential", True)),
+ ]
+ return rungs
+
+
+# ─── Google Cloud ────────────────────────────────────────────────────
+
+
+def gcp_service_account_assertion(ctx: ChainContext, info: Mapping[str, Any], scope: str = _GCP_SCOPE) -> tuple[str, str]:
+ """(token_uri, JWT) for a ``service_account`` file: header typ/alg/kid,
+ claims iat, exp=iat+3600, iss, aud, scope (google-auth
+ service_account.py:393-420, jwt.py:75-107)."""
+ key = rs256.load_private_key(str(info["private_key"]))
+ now = int(ctx.now().timestamp())
+ token_uri = str(info.get("token_uri") or _GCP_TOKEN_URL)
+ header: dict[str, Any] = {"alg": "RS256", "typ": "JWT"}
+ if info.get("private_key_id"):
+ header["kid"] = str(info["private_key_id"])
+ payload = {"iat": now, "exp": now + 3600, "iss": str(info["client_email"]), "aud": token_uri, "scope": scope}
+ return token_uri, rs256.jwt_encode(header, payload, key)
+
+
+def _gcp_credential_file(ctx: ChainContext, path: str) -> dict | None:
+ raw = ctx.read(path)
+ if raw is None:
+ return None
+ try:
+ data = json.loads(raw)
+ except ValueError:
+ raise NotConfiguredError(f"{path}: not valid JSON") from None
+ return data if isinstance(data, dict) else None
+
+
+def _gcp_from_info(ctx: ChainContext, info: Mapping[str, Any], where: str) -> BearerToken:
+ kind = info.get("type")
+ now = ctx.now()
+ if kind == "authorized_user":
+ for k in ("refresh_token", "client_id", "client_secret"):
+ if not info.get(k):
+ raise NotConfiguredError(f"{where}: authorized_user file lacks {k}")
+ pairs = [("grant_type", "refresh_token"), ("client_id", str(info["client_id"])), ("client_secret", str(info["client_secret"])),
+ ("refresh_token", str(info["refresh_token"]))]
+ data = _exchange(ctx, "POST", str(info.get("token_uri") or _GCP_TOKEN_URL), {"content-type": "application/x-www-form-urlencoded"}, _form(pairs), "Google OAuth refresh")
+ return _bearer_from_oauth(data, now, "Google OAuth")
+ if kind == "service_account":
+ token_uri, assertion = gcp_service_account_assertion(ctx, info)
+ data = _exchange(ctx, "POST", token_uri, {"content-type": "application/x-www-form-urlencoded"},
+ _form([("grant_type", _JWT_BEARER), ("assertion", assertion)]), "Google service account")
+ return _bearer_from_oauth(data, now, "Google service account")
+ if kind == "external_account":
+ return _gcp_external_account(ctx, info, where)
+ if kind == "impersonated_service_account":
+ source = info.get("source_credentials")
+ if not isinstance(source, dict):
+ raise NotConfiguredError(f"{where}: impersonated_service_account lacks source_credentials")
+ base = _gcp_from_info(ctx, source, f"{where}.source_credentials")
+ return _gcp_impersonate(ctx, base, str(info["service_account_impersonation_url"]), info.get("delegates") or [])
+ raise NotConfiguredError(f"{where}: credential type {kind!r} is not supported by lm15 "
+ "(external_account_authorized_user and gdch_service_account are stated gaps)")
+
+
+def _gcp_impersonate(ctx: ChainContext, source: BearerToken, url: str, delegates: list) -> BearerToken:
+ body = json.dumps({"delegates": list(delegates), "scope": [_GCP_SCOPE], "lifetime": "3600s"}).encode()
+ data = _exchange(ctx, "POST", url, {"content-type": "application/json", "authorization": f"Bearer {source.value}"}, body, "generateAccessToken")
+ token = data.get("accessToken")
+ if not token:
+ raise AuthError("generateAccessToken: no accessToken")
+ expires = parse_rfc3339(str(data["expireTime"])) if data.get("expireTime") else None
+ return BearerToken(str(token), expires_at=expires)
+
+
+def _gcp_external_account(ctx: ChainContext, info: Mapping[str, Any], where: str) -> BearerToken:
+ source = info.get("credential_source") or {}
+ if "environment_id" in source:
+ raise NotConfiguredError(f"{where}: external_account with an AWS credential_source is a stated gap in lm15; "
+ "use a file/url/executable source or a service account")
+ subject: str | None = None
+ fmt = source.get("format") or {}
+ if source.get("file"):
+ raw = ctx.read(str(source["file"]))
+ if raw is None:
+ raise NotConfiguredError(f"{where}: subject token file {source['file']} is unreadable")
+ subject = raw.strip()
+ elif source.get("url"):
+ status, _, raw = ctx.http("GET", str(source["url"]), {str(k): str(v) for k, v in (source.get("headers") or {}).items()}, None, 30.0) # type: ignore[misc]
+ if status >= 400:
+ raise AuthError(f"{where}: subject token url HTTP {status}")
+ subject = raw.decode("utf-8", "replace").strip()
+ elif source.get("executable"):
+ if ctx.run is None:
+ raise NotConfiguredError(f"{where}: executable credential source needs subprocess access")
+ if (ctx.env.get("GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES") or "") != "1":
+ raise NotConfiguredError(f"{where}: set GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES=1 to allow the executable source")
+ import shlex
+
+ out = ctx.run(shlex.split(str(source["executable"]["command"])), float(source["executable"].get("timeout_millis", 30000)) / 1000)
+ data = _json_body(out.encode())
+ if not data.get("success", True):
+ raise AuthError("external account executable reported failure")
+ subject = data.get("id_token") or data.get("saml_response")
+ fmt = {"type": "text"}
+ if subject is None:
+ raise NotConfiguredError(f"{where}: external_account credential_source is not file/url/executable")
+ if fmt.get("type") == "json":
+ field_name = str(fmt.get("subject_token_field_name") or "")
+ subject = str(_json_body(subject.encode()).get(field_name) or "")
+ body = json.dumps({
+ "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
+ "audience": str(info["audience"]),
+ "scope": _GCP_SCOPE,
+ "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
+ "subjectToken": subject,
+ "subjectTokenType": str(info["subject_token_type"]),
+ }).encode()
+ data = _exchange(ctx, "POST", str(info.get("token_url") or _GCP_STS_URL), {"content-type": "application/json"}, body, "Google STS exchange")
+ token = _bearer_from_oauth(data, ctx.now(), "Google STS")
+ if info.get("service_account_impersonation_url"):
+ return _gcp_impersonate(ctx, token, str(info["service_account_impersonation_url"]), [])
+ return token
+
+
+def _gcp_metadata_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.http is None or (ctx.env.get("NO_GCE_CHECK") or "").lower() in ("1", "true"):
+ return None
+ host = ctx.env.get("GCE_METADATA_HOST") or ctx.env.get("GCE_METADATA_ROOT") or "metadata.google.internal"
+ try:
+ status, _, raw = ctx.http("GET", f"http://{host}/computeMetadata/v1/instance/service-accounts/default/token", {"Metadata-Flavor": "Google"}, None, 1.0)
+ except Exception: # noqa: BLE001 - not on GCE: absent
+ return None
+ if status != 200:
+ return None
+ return _bearer_from_oauth(_json_body(raw), ctx.now(), "GCE metadata")
+
+
+def _gcloud_acquire(ctx: ChainContext) -> BearerToken | None:
+ if ctx.run is None or ctx.on_path("gcloud") is None:
+ return None
+ token = ctx.run(["gcloud", "auth", "print-access-token"], 30.0).strip()
+ return BearerToken(token) if token else None
+
+
+def _adc_file_path(ctx: ChainContext) -> str:
+ base = ctx.env.get("CLOUDSDK_CONFIG") or "~/.config/gcloud"
+ return f"{base.rstrip('/')}/application_default_credentials.json"
+
+
+def _gcp_chain(policy: AccessPolicy) -> list[Rung]:
+ door_key = policy.env_keys[0] if policy.env_keys else None
+
+ def file_probe(label: str, path_fn):
+ def probe(ctx: ChainContext):
+ path = path_fn(ctx)
+ if not path:
+ return ("absent", f"{label} not set")
+ info = _gcp_credential_file(ctx, path)
+ if info is None:
+ return ("absent", f"{path} missing or unreadable")
+ return ("configured", f"{info.get('type', '?')} credentials in {path} (token exchange at request time)")
+ return probe
+
+ def file_acquire(path_fn):
+ def acquire(ctx: ChainContext):
+ path = path_fn(ctx)
+ if not path:
+ return None
+ info = _gcp_credential_file(ctx, path)
+ return _gcp_from_info(ctx, info, path) if info else None
+ return acquire
+
+ env_path = lambda ctx: ctx.env.get("GOOGLE_APPLICATION_CREDENTIALS") # noqa: E731
+ adc_path = lambda ctx: _adc_file_path(ctx) # noqa: E731
+
+ def metadata_probe(ctx: ChainContext):
+ if (ctx.env.get("NO_GCE_CHECK") or "").lower() in ("1", "true"):
+ return ("absent", "NO_GCE_CHECK set")
+ return ("configured", "GCE metadata server probed at request time")
+
+ rungs: list[Rung] = []
+ if door_key:
+ rungs.append(Rung(f"env:{door_key}", "env", f"env ${door_key}", "",
+ lambda ctx, k=door_key: ("usable", "set (value never shown)") if ctx.env.get(k) else ("absent", "not set"),
+ lambda ctx, k=door_key: ApiKey(ctx.env[k]) if ctx.env.get(k) else None))
+ rungs += [
+ Rung("adc-env", "json-file", "GOOGLE_APPLICATION_CREDENTIALS file", "network", file_probe("GOOGLE_APPLICATION_CREDENTIALS", env_path), file_acquire(env_path)),
+ Rung("adc-file", "json-file", "gcloud application default credentials file", "network", file_probe("ADC file", adc_path), file_acquire(adc_path)),
+ Rung("metadata", "http-metadata", "GCE metadata server", "network", metadata_probe, _gcp_metadata_acquire),
+ Rung("gcloud", "subprocess", "gcloud auth print-access-token", "subprocess",
+ lambda ctx: ("configured", "`gcloud` run at request time") if ctx.on_path("gcloud") else ("absent", "gcloud is not on PATH"),
+ _gcloud_acquire),
+ ]
+ return rungs
+
+
+# ─── Settings from the cloud profile (AUTH-10 fallbacks after env) ────
+
+
+def profile_settings(policy: AccessPolicy, ctx: ChainContext) -> Callable[[str], str | None]:
+ """The setting values the cloud's own config files carry: AWS
+ ``region`` from the active profile (`~/.aws/config`, then
+ `~/.aws/credentials`); GCP ``project`` from the ADC file's
+ ``quota_project_id`` / ``project_id``. Nothing for Azure."""
+
+ def lookup(name: str) -> str | None:
+ if policy.credential_policy == "aws-chain" and name == "region":
+ creds, conf, profile = _aws_config(ctx)
+ value = _aws_profile_section(conf, profile).get("region")
+ if not value and creds.has_section(profile):
+ value = creds[profile].get("region")
+ return value or None
+ if policy.credential_policy == "gcp-chain" and name == "project":
+ for path in (ctx.env.get("GOOGLE_APPLICATION_CREDENTIALS"), _adc_file_path(ctx)):
+ if path:
+ info = _gcp_credential_file(ctx, path) or {}
+ value = info.get("quota_project_id") or info.get("project_id")
+ if value:
+ return str(value)
+ return None
+
+ return lookup
+
+
+# ─── Chains ──────────────────────────────────────────────────────────
+
+_CHAINS = {"aws-chain": _aws_chain, "azure-chain": _azure_chain, "gcp-chain": _gcp_chain}
+
+
+def chain_for(policy: AccessPolicy) -> list[Rung]:
+ builder = _CHAINS.get(policy.credential_policy)
+ if builder is None:
+ raise ValueError(f"{policy.provider}: not a cloud chain policy")
+ return builder(policy)
+
+
+def explain(policy: AccessPolicy, ctx: ChainContext, *, explicit: bool) -> tuple[list[Step], bool]:
+ """The AUTH-7 walk. ``explicit`` = an api_keys entry exists (rung 0)."""
+ steps: list[Step] = []
+ selected = False
+ if explicit:
+ steps.append(Step("api_keys", "explicit api_keys entry", "provided (value never shown)", "selected"))
+ selected = True
+ else:
+ steps.append(Step("api_keys", "explicit api_keys entry", "not provided", "absent"))
+ for rung in chain_for(policy):
+ try:
+ verdict, detail = rung.probe(ctx)
+ except NotConfiguredError as exc:
+ verdict, detail = "absent", str(exc).splitlines()[0]
+ if verdict == "absent":
+ state = "absent"
+ elif verdict == "configured":
+ state = "shadowed" if selected else "unprobed"
+ else:
+ state = "shadowed" if selected else "selected"
+ selected = True
+ steps.append(Step(rung.name, rung.source, detail, state))
+ # ``configured`` is true when something may supply the credential: a
+ # rung selected offline, or a configured network/subprocess rung the
+ # offline doctor could not probe. The report names which.
+ return steps, selected or any(s.state == "unprobed" for s in steps)
+
+
+def resolve(policy: AccessPolicy, ctx: ChainContext) -> CredentialValue:
+ """Walk the chain online; the first rung that yields wins. A rung that
+ is configured and fails raises. Azure developer commands are the
+ AUTH-1 exception: try all three before reporting their failure.
+ Deployed Azure credentials and AWS/GCP failures never fall through."""
+ developer_failed = False
+ for rung in chain_for(policy):
+ try:
+ got = rung.acquire(ctx)
+ except AuthError:
+ if policy.credential_policy == "azure-chain" and rung.name in {"az", "pwsh", "azd"}:
+ developer_failed = True
+ continue
+ raise
+ if got is not None:
+ return got
+ if developer_failed:
+ raise AuthError("Azure developer credentials failed; sign in with az, Azure PowerShell, or azd",
+ provider=policy.provider)
+ raise NotConfiguredError(
+ f"{policy.provider}: no credential found in the {policy.credential_policy} chain"
+ + (f"; set {policy.env_keys[0]} or configure the cloud SDK" if policy.env_keys else "; configure the cloud SDK"),
+ provider=policy.provider,
+ env_keys=policy.env_keys,
+ )
+
+
+class _CachingProvider:
+ """AUTH-2/AUTH-3: resolve once, hand out until the skew window, then
+ re-resolve. In memory only; never written to a foreign file."""
+
+ def __init__(self, policy: AccessPolicy, ctx: ChainContext) -> None:
+ self._policy = policy
+ self._ctx = ctx
+ self._lock = threading.Lock()
+ self._value: CredentialValue | None = None
+
+ def __call__(self) -> CredentialValue:
+ with self._lock:
+ if self._value is None or self._value.is_expired(self._ctx.now()):
+ value = resolve(self._policy, self._ctx)
+ if value.is_expired(self._ctx.now()):
+ raise AuthError("cloud credential is expired; renew the configured credential source",
+ provider=self._policy.provider)
+ # CLI output without an expiry cannot safely be cached forever.
+ self._value = value if isinstance(value, (ApiKey, AwsCredentials)) or value.expires_at is not None else None
+ return value
+ return self._value
+
+ def __repr__(self) -> str:
+ return f"<cloud credential provider for {self._policy.provider}>"
+
+
+def cache_key(policy: AccessPolicy, ctx: ChainContext) -> str:
+ """Provider id + the identity-selecting settings (AUTH-3)."""
+ e = ctx.env
+ parts = [policy.provider, ctx.env.get("AWS_PROFILE") or "", e.get("AZURE_TENANT_ID") or "", e.get("AZURE_CLIENT_ID") or "",
+ e.get("GOOGLE_APPLICATION_CREDENTIALS") or "", e.get("CLOUDSDK_CONFIG") or "", str(ctx.home)]
+ parts += [f"{k}={v}" for k, v in sorted(ctx.settings.items())]
+ return hashlib.sha256("\x1f".join(parts).encode()).hexdigest()
+
+
+def credential_provider(policy: AccessPolicy, ctx: ChainContext) -> Callable[[], CredentialValue]:
+ return _CachingProvider(policy, ctx)
+
+
+# ─── Harness ops (PROTOCOL.md token_exchange_build / token_exchange_parse) ──
+
+
+def token_exchange_build(policy: AccessPolicy, rung: str, inputs: Mapping[str, Any], ctx: ChainContext) -> dict[str, Any]:
+ """The exact token-exchange request a rung would send under ``ctx.now``."""
+ if rung in ("adc-env", "adc-file", "service-account"):
+ info = inputs["credential_file"]
+ scope = str(inputs.get("scope") or _GCP_SCOPE)
+ token_uri, assertion = gcp_service_account_assertion(ctx, info, scope)
+ return {"method": "POST", "url": token_uri, "headers": {"content-type": "application/x-www-form-urlencoded"},
+ "body_encoding": "form", "body": {"grant_type": _JWT_BEARER, "assertion": assertion}}
+ if rung == "environment":
+ url, pairs = azure_environment_request(ctx, jti=inputs.get("jti"))
+ return {"method": "POST", "url": url, "headers": {"content-type": "application/x-www-form-urlencoded"},
+ "body_encoding": "form", "body": dict(pairs)}
+ raise ValueError(f"token_exchange_build: rung {rung!r} has no deterministic request")
+
+
+def token_exchange_parse(policy: AccessPolicy, rung: str, status: int, body: Mapping[str, Any], ctx: ChainContext) -> CredentialValue:
+ now = ctx.now()
+ if rung in ("adc-env", "adc-file", "service-account", "environment", "workload-identity", "managed-identity", "metadata"):
+ if not 200 <= status < 300:
+ raise AuthError(f"{rung}: HTTP {status}")
+ return _bearer_from_oauth(dict(body), now, rung)
+ if rung == "credential_process":
+ if status != 0 or body.get("Version") != 1:
+ raise AuthError("credential_process failed or returned an unsupported Version")
+ return _aws_from_response(body)
+ if rung in ("imds", "container"):
+ if not 200 <= status < 300:
+ raise AuthError(f"{rung}: HTTP {status}")
+ return _aws_from_response(body)
+ raise ValueError(f"token_exchange_parse: rung {rung!r} is not a parse vector")
diff --git a/dspy/_vendor/lm15/cloud/hosts.py b/dspy/_vendor/lm15/cloud/hosts.py
new file mode 100644
index 000000000..e59cb5be5
--- /dev/null
+++ b/dspy/_vendor/lm15/cloud/hosts.py
@@ -0,0 +1,207 @@
+"""
+lm15.cloud.hosts — a dialect reaches a cloud door through a host (AUTH-10).
+
+Three pure functions, in the order an adapter calls them:
+
+1. ``resolve_settings(host, given, env)`` — the host's settings from the
+ caller's values, then the environment (router/doctor only; a bare
+ adapter is given its settings explicitly, like its credential), then
+ defaults. A required setting with no value raises ``NotConfiguredError``
+ naming the variable: ``region`` and ``resource`` have no default on
+ purpose (a wrong-region default is a residency bug).
+2. ``render_base_url(host, settings)`` — the base URL for the settings;
+ ``{location_host}`` is derived from ``location``.
+3. ``finish_request(...)`` — the dialect built its request against that
+ base URL; this applies the host's closed set of rewrites (endpoint path
+ override, model into the path, ``anthropic_version`` into the body,
+ required headers, ``query-key``) and then signs (``sigv4``). Ports
+ implement exactly this function; the harness pins its output.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import re
+from urllib.parse import quote
+from typing import Any, Callable, Mapping
+
+from ..credentials import ApiKey, AwsCredentials, CredentialValue
+from ..errors import NotConfiguredError, UnsupportedFeatureError
+from ..features import AccessPolicy, HostSpec
+from . import sigv4
+
+__all__ = ["resolve_settings", "render_base_url", "location_host", "finish_request", "Clock", "utc_now"]
+
+Clock = Callable[[], datetime]
+
+
+def utc_now() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+def resolve_settings(
+ host: HostSpec | None,
+ given: Mapping[str, str] | None,
+ env: Mapping[str, str] | None = None,
+ *,
+ provider: str = "",
+ profile: Callable[[str], str | None] | None = None,
+) -> dict[str, str]:
+ """Explicit values, then ``env`` (when given), then the cloud profile
+ (``profile(name)``: the AWS shared config's ``region`` for the active
+ profile, the ADC file's ``quota_project_id`` — AUTH-10), then defaults."""
+ out: dict[str, str] = {}
+ if host is None:
+ return dict(given or {})
+ given = dict(given or {})
+ for setting in host.settings:
+ value = given.pop(setting.name, None)
+ if not value and env is not None:
+ for var in setting.env:
+ candidate = env.get(var)
+ if candidate:
+ value = candidate
+ break
+ if not value and profile is not None:
+ value = profile(setting.name)
+ if not value:
+ value = setting.default
+ if not value:
+ hint = f"set {' or '.join(setting.env)}" if setting.env else f"pass settings={{'{setting.name}': ...}}"
+ raise NotConfiguredError(
+ f"{provider or 'host'}: setting {setting.name!r} is required and has no default; {hint}",
+ provider=provider or None,
+ credential_hint=hint,
+ )
+ out[setting.name] = value
+ unknown = sorted(given)
+ if unknown:
+ raise ValueError(f"{provider or 'host'}: unknown host setting(s) {unknown}; known: {list(host.setting_names)}")
+ return out
+
+
+def location_host(location: str) -> str:
+ """Vertex host for a location (vertex-locations.md:40-63, :91)."""
+ if location == "global":
+ return "aiplatform.googleapis.com"
+ if location in ("us", "eu"):
+ return f"aiplatform.{location}.rep.googleapis.com"
+ return f"{location}-aiplatform.googleapis.com"
+
+
+def render_base_url(host: HostSpec, settings: Mapping[str, str]) -> str:
+ values = dict(settings)
+ for name in ("region", "resource", "location"):
+ if name in values and not re.fullmatch(r"[A-Za-z0-9-]+", values[name]):
+ raise NotConfiguredError(f"host setting {name!r} must be a DNS label")
+ if "project" in values:
+ values["project"] = quote(values["project"], safe="")
+ if "location" in values and "location_host" not in values:
+ values["location_host"] = location_host(values["location"])
+ try:
+ return host.base_url.format(**values)
+ except KeyError as exc:
+ raise NotConfiguredError(f"host base URL needs setting {exc.args[0]!r}") from None
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class FinishedRequest:
+ url: str
+ headers: dict[str, str]
+ payload: Any
+ params: dict[str, str]
+
+
+def finish_request(
+ policy: AccessPolicy,
+ settings: Mapping[str, str],
+ *,
+ base_url: str,
+ url: str,
+ headers: Mapping[str, str],
+ payload: Any,
+ params: Mapping[str, Any] | None,
+ endpoint: str | None,
+ stream: bool,
+ model: str | None,
+ credential: CredentialValue | None,
+) -> FinishedRequest:
+ """Apply the host's rewrites before serialization. Signing happens
+ after serialization in ``sign_request``."""
+ host = policy.host
+ out_headers = dict(headers)
+ out_params = {str(k): str(v) for k, v in (params or {}).items()}
+ if host is None:
+ return FinishedRequest(url=url, headers=out_headers, payload=payload, params=out_params)
+
+ if host.stream_framing != "sse" and stream:
+ raise UnsupportedFeatureError(
+ f"{policy.provider}: {host.stream_framing} stream framing is not implemented yet (phase 2)",
+ provider=policy.provider,
+ )
+
+ key = f"{endpoint}/stream" if (endpoint and stream and f"{endpoint}/stream" in host.paths) else endpoint
+ if key is not None and key in host.paths:
+ if "{model}" in host.paths[key] and not model:
+ raise ValueError(f"{policy.provider}: endpoint {endpoint!r} needs the model in the path")
+ path_model = model or ""
+ if endpoint == "generateContent":
+ path_model = path_model.removeprefix("models/")
+ url = base_url.rstrip("/") + host.paths[key].format(model=quote(path_model, safe=":@"))
+
+ if isinstance(payload, dict):
+ payload = dict(payload)
+ if host.model_in == "path":
+ payload.pop("model", None)
+ if host.anthropic_version_in.startswith("body:"):
+ payload["anthropic_version"] = host.anthropic_version_in[len("body:"):]
+ out_headers = {k: v for k, v in out_headers.items() if k.lower() != "anthropic-version"}
+
+ for name, setting in host.required_headers:
+ value = settings.get(setting)
+ if not value:
+ raise NotConfiguredError(f"{policy.provider}: header {name} needs setting {setting!r}", provider=policy.provider)
+ out_headers[name] = value
+
+ if credential is not None and isinstance(credential, ApiKey) and "query-key" in policy.auth_scheme:
+ from ..access import select_scheme
+
+ if select_scheme(policy, credential) == "query-key":
+ out_params["key"] = credential.value
+
+ return FinishedRequest(url=url, headers=out_headers, payload=payload, params=out_params)
+
+
+def sign_request(
+ policy: AccessPolicy,
+ settings: Mapping[str, str],
+ *,
+ method: str,
+ url: str,
+ headers: list[tuple[str, str]],
+ body: bytes,
+ credential: CredentialValue | None,
+ now: datetime,
+) -> list[tuple[str, str]]:
+ """The headers to send. ``sigv4`` replaces them with the signed set;
+ every other scheme was already applied by the dialect's auth header."""
+ host = policy.host
+ if not isinstance(credential, AwsCredentials):
+ return headers
+ if host is None or host.sigv4_service is None:
+ raise NotConfiguredError(f"{policy.provider}: AWS credentials need a sigv4 host", provider=policy.provider)
+ region = settings.get("region")
+ if not region:
+ raise NotConfiguredError(f"{policy.provider}: sigv4 needs the region setting", provider=policy.provider)
+ signature = sigv4.sign(
+ method=method,
+ url=url,
+ headers={k: v for k, v in headers if k.lower() not in ("authorization", "x-api-key")},
+ payload=body,
+ credentials=credential,
+ region=region,
+ service=host.sigv4_service,
+ now=now,
+ )
+ return list(signature.headers.items())
diff --git a/dspy/_vendor/lm15/cloud/rs256.py b/dspy/_vendor/lm15/cloud/rs256.py
new file mode 100644
index 000000000..d06e38a59
--- /dev/null
+++ b/dspy/_vendor/lm15/cloud/rs256.py
@@ -0,0 +1,204 @@
+"""
+lm15.cloud.rs256 — RSASSA-PKCS1-v1_5 / SHA-256 signing, standard library only.
+
+Used for the two JWT assertions in spec/auth.md AUTH-11 (``jwt-rs256``):
+Google service accounts (RS256 is "the only signing algorithm supported",
+gcp-service-account-oauth.md:318-333) and Microsoft Entra certificate
+credentials (azure-identity signs RS256, certificate.py:20).
+
+What is implemented, and only that:
+
+- PEM → DER for ``PRIVATE KEY`` (PKCS#8), ``RSA PRIVATE KEY`` (PKCS#1),
+ and ``CERTIFICATE`` blocks;
+- a minimal DER reader (SEQUENCE, INTEGER, OCTET STRING, NULL, OID);
+- EMSA-PKCS1-v1_5 encoding with the SHA-256 DigestInfo prefix (RFC 8017
+ §9.2) and the RSASP1 primitive ``pow(m, d, n)``;
+- the compact JWS serialization lm15 pins (compact JSON, keys in the
+ caller's order, base64url without padding).
+
+Stated trade-offs (changes/2026-09-03-cloud-hosts.md):
+
+- ``pow`` on Python integers is not constant-time and has no RSA blinding.
+ This implementation is not hardened against timing attacks. Use an
+ external credential provider when that threat matters. Ports with a
+ platform RSA (Go ``crypto/rsa``, Node ``crypto``) use it.
+- Encrypted PEM and PKCS#12 are not parsed: the error names
+ ``openssl pkcs12 -nodes`` / ``openssl pkey``.
+- The Chinese-remainder speed-up is not used: one 2048-bit signature is
+ about 75 ms in pure Python (measured 2026-09-03), once per token
+ lifetime of an hour.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from ..errors import NotConfiguredError
+
+__all__ = ["RsaPrivateKey", "load_private_key", "certificate_der", "sign_pkcs1v15_sha256", "jwt_encode", "b64url"]
+
+# DigestInfo prefix for SHA-256 (RFC 8017 §9.2, note 1).
+_SHA256_DIGEST_INFO = bytes.fromhex("3031300d060960864801650304020105000420")
+_RSA_OID = bytes.fromhex("2a864886f70d010101") # 1.2.840.113549.1.1.1
+
+
+def b64url(data: bytes) -> str:
+ return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+# ─── PEM / DER ───────────────────────────────────────────────────────
+
+
+def _pem_block(text: str, label: str) -> bytes | None:
+ head, tail = f"-----BEGIN {label}-----", f"-----END {label}-----"
+ start = text.find(head)
+ if start < 0:
+ return None
+ end = text.find(tail, start)
+ if end < 0:
+ raise ValueError(f"PEM block {label!r} has no END line")
+ body = "".join(text[start + len(head):end].split())
+ return base64.b64decode(body)
+
+
+def _der_read(data: bytes, pos: int) -> tuple[int, bytes, int]:
+ """(tag, value, next_pos) for the TLV at ``pos``."""
+ if pos >= len(data):
+ raise ValueError("DER: unexpected end")
+ tag = data[pos]
+ pos += 1
+ if pos >= len(data):
+ raise ValueError("DER: truncated length")
+ length = data[pos]
+ pos += 1
+ if length & 0x80:
+ count = length & 0x7F
+ if count == 0 or count > 4:
+ raise ValueError("DER: unsupported length form")
+ if pos + count > len(data):
+ raise ValueError("DER: truncated length")
+ length = int.from_bytes(data[pos:pos + count], "big")
+ pos += count
+ value = data[pos:pos + length]
+ if len(value) != length:
+ raise ValueError("DER: truncated value")
+ return tag, value, pos + length
+
+
+def _der_sequence(data: bytes) -> list[tuple[int, bytes]]:
+ tag, value, end = _der_read(data, 0)
+ if tag != 0x30:
+ raise ValueError(f"DER: expected SEQUENCE, got tag {tag:#x}")
+ if end != len(data):
+ raise ValueError("DER: trailing bytes after SEQUENCE")
+ return _der_items(value)
+
+
+def _der_items(value: bytes) -> list[tuple[int, bytes]]:
+ """The TLVs inside a constructed value (a SEQUENCE's contents)."""
+ items: list[tuple[int, bytes]] = []
+ pos = 0
+ while pos < len(value):
+ item_tag, item_value, pos = _der_read(value, pos)
+ items.append((item_tag, item_value))
+ return items
+
+
+def _der_int(item: tuple[int, bytes]) -> int:
+ tag, value = item
+ if tag != 0x02:
+ raise ValueError(f"DER: expected INTEGER, got tag {tag:#x}")
+ return int.from_bytes(value, "big", signed=False)
+
+
+@dataclass(frozen=True, slots=True)
+class RsaPrivateKey:
+ n: int
+ e: int
+ d: int
+
+ def __repr__(self) -> str: # AUTH-5
+ return f"RsaPrivateKey(bits={self.n.bit_length()}, <redacted>)"
+
+ @property
+ def size_bytes(self) -> int:
+ return (self.n.bit_length() + 7) // 8
+
+
+def _rsa_from_pkcs1(der: bytes) -> RsaPrivateKey:
+ items = _der_sequence(der)
+ # RSAPrivateKey ::= SEQUENCE { version, n, e, d, p, q, dP, dQ, qInv }
+ if len(items) < 4:
+ raise ValueError("PKCS#1 RSAPrivateKey: too few fields")
+ return RsaPrivateKey(n=_der_int(items[1]), e=_der_int(items[2]), d=_der_int(items[3]))
+
+
+def _rsa_from_pkcs8(der: bytes) -> RsaPrivateKey:
+ items = _der_sequence(der)
+ # PrivateKeyInfo ::= SEQUENCE { version, AlgorithmIdentifier, OCTET STRING privateKey }
+ if len(items) < 3 or items[1][0] != 0x30 or items[2][0] != 0x04:
+ raise ValueError("PKCS#8 PrivateKeyInfo: unexpected shape")
+ alg = _der_items(items[1][1])
+ if not alg or alg[0][0] != 0x06 or alg[0][1] != _RSA_OID:
+ raise ValueError("PKCS#8: not an RSA key (only rsaEncryption is supported)")
+ return _rsa_from_pkcs1(items[2][1])
+
+
+def load_private_key(pem: str) -> RsaPrivateKey:
+ """Parse an unencrypted RSA private key from PEM (PKCS#8 or PKCS#1)."""
+ if "ENCRYPTED PRIVATE KEY" in pem or "Proc-Type: 4,ENCRYPTED" in pem:
+ raise NotConfiguredError(
+ "encrypted private keys are not supported; decrypt it first: "
+ "openssl pkey -in key.pem -out key-plain.pem",
+ credential_hint="openssl pkey -in key.pem -out key-plain.pem",
+ )
+ der = _pem_block(pem, "PRIVATE KEY")
+ if der is not None:
+ return _rsa_from_pkcs8(der)
+ der = _pem_block(pem, "RSA PRIVATE KEY")
+ if der is not None:
+ return _rsa_from_pkcs1(der)
+ if "BEGIN EC PRIVATE KEY" in pem:
+ raise NotConfiguredError("EC private keys are not supported (RS256 needs an RSA key)")
+ raise NotConfiguredError(
+ "no PEM private key found; PKCS#12 (.pfx/.p12) is not parsed — convert with: "
+ "openssl pkcs12 -in cert.pfx -nodes -out cert.pem",
+ credential_hint="openssl pkcs12 -in cert.pfx -nodes -out cert.pem",
+ )
+
+
+def certificate_der(pem: str) -> bytes:
+ """The DER bytes of the first CERTIFICATE block (for ``x5t`` thumbprints)."""
+ der = _pem_block(pem, "CERTIFICATE")
+ if der is None:
+ raise NotConfiguredError("no PEM CERTIFICATE block found")
+ return der
+
+
+# ─── Signing ─────────────────────────────────────────────────────────
+
+
+def sign_pkcs1v15_sha256(key: RsaPrivateKey, message: bytes) -> bytes:
+ """RSASSA-PKCS1-v1_5-SIGN with SHA-256 (RFC 8017 §8.2.1)."""
+ k = key.size_bytes
+ digest = _SHA256_DIGEST_INFO + hashlib.sha256(message).digest()
+ if k < len(digest) + 11:
+ raise ValueError("RSA key too small for SHA-256 PKCS#1 v1.5")
+ padded = b"\x00\x01" + b"\xff" * (k - len(digest) - 3) + b"\x00" + digest
+ m = int.from_bytes(padded, "big")
+ s = pow(m, key.d, key.n)
+ return s.to_bytes(k, "big")
+
+
+def jwt_encode(header: Mapping[str, Any], payload: Mapping[str, Any], key: RsaPrivateKey) -> str:
+ """Compact JWS: lm15 pins compact JSON with keys in the given order and
+ unpadded base64url (a canonical fact so four ports emit identical bytes;
+ RFC 7519 servers accept any valid JSON)."""
+ head = b64url(json.dumps(dict(header), separators=(",", ":")).encode("utf-8"))
+ body = b64url(json.dumps(dict(payload), separators=(",", ":")).encode("utf-8"))
+ signing_input = f"{head}.{body}".encode("ascii")
+ return f"{head}.{body}.{b64url(sign_pkcs1v15_sha256(key, signing_input))}"
diff --git a/dspy/_vendor/lm15/cloud/sigv4.py b/dspy/_vendor/lm15/cloud/sigv4.py
new file mode 100644
index 000000000..8fc52772c
--- /dev/null
+++ b/dspy/_vendor/lm15/cloud/sigv4.py
@@ -0,0 +1,153 @@
+"""
+lm15.cloud.sigv4 — AWS Signature Version 4, standard library only.
+
+Rules from the AWS reference (lm15-contract/research/cloud-hosts/sources/
+aws-sigv4-create-signed-request.md, lines 46–190), pinned by the AWS test
+suite in lm15-contract/auth/sigv4-vectors.json:
+
+- canonical request = method, URI-encoded path, sorted+encoded query,
+ lowercase sorted headers (``host`` and every ``x-amz-*`` mandatory;
+ ``content-type`` when present), the signed-header list, hex SHA-256 of
+ the payload;
+- string to sign = ``AWS4-HMAC-SHA256``, ``x-amz-date``, credential scope
+ ``YYYYMMDD/region/service/aws4_request``, hex SHA-256 of the canonical
+ request;
+- signing key = HMAC chain ``AWS4``+secret → date → region → service →
+ ``aws4_request``;
+- header values are trimmed and inner runs of whitespace collapsed to one
+ space (test-suite case ``get-header-value-trim``);
+- ``x-amz-content-sha256`` is an S3 requirement and is NOT added here.
+
+Deterministic under a fixed clock and fixed keys: the harness compares the
+``authorization`` header byte for byte.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import urllib.parse
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+from ..credentials import AwsCredentials
+
+__all__ = ["SigV4Signature", "sign", "canonicalize"]
+
+_ALGORITHM = "AWS4-HMAC-SHA256"
+_SAFE = "-_.~"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class SigV4Signature:
+ canonical_request: str
+ string_to_sign: str
+ authorization: str
+ headers: dict[str, str] # every header to send, lowercase names, including the new ones
+
+
+def _encode(text: str) -> str:
+ return urllib.parse.quote(text, safe=_SAFE)
+
+
+def _remove_dot_segments(path: str) -> str:
+ """RFC 3986 §5.2.4 as the AWS SDKs apply it to non-S3 paths: drop `.`
+ and empty segments, pop on `..`, keep a leading and a trailing slash.
+ Pinned by the AWS test-suite vectors get-relative*, get-slash*,
+ get-slashes and get-slash-pointless-dot (auth/sigv4-vectors.json)."""
+ kept: list[str] = []
+ for segment in path.split("/"):
+ if segment == "..":
+ if kept:
+ kept.pop()
+ elif segment and segment != ".":
+ kept.append(segment)
+ first = "/" if path.startswith("/") else ""
+ last = "/" if path.endswith("/") and kept else ""
+ return first + "/".join(kept) + last
+
+
+def _canonical_path(path: str) -> str:
+ if not path:
+ return "/"
+ normalized = _remove_dot_segments(path) or "/"
+ return "/".join(_encode(urllib.parse.unquote(seg)) for seg in normalized.split("/"))
+
+
+def _canonical_query(query: str) -> str:
+ pairs = urllib.parse.parse_qsl(query, keep_blank_values=True)
+ encoded = sorted((_encode(k), _encode(v)) for k, v in pairs)
+ return "&".join(f"{k}={v}" for k, v in encoded)
+
+
+def _trim(value: str) -> str:
+ return " ".join(value.split())
+
+
+def canonicalize(
+ method: str,
+ url: str,
+ headers: dict[str, str],
+ payload: bytes,
+) -> tuple[str, str]:
+ """(canonical_request, signed_headers) for already-complete headers."""
+ parts = urllib.parse.urlsplit(url)
+ lowered = {k.lower(): _trim(v) for k, v in headers.items()}
+ signed = ";".join(sorted(lowered))
+ canonical_headers = "".join(f"{k}:{lowered[k]}\n" for k in sorted(lowered))
+ canonical = "\n".join([
+ method.upper(),
+ _canonical_path(parts.path),
+ _canonical_query(parts.query),
+ canonical_headers,
+ signed,
+ hashlib.sha256(payload).hexdigest(),
+ ])
+ return canonical, signed
+
+
+def sign(
+ *,
+ method: str,
+ url: str,
+ headers: dict[str, str],
+ payload: bytes,
+ credentials: AwsCredentials,
+ region: str,
+ service: str,
+ now: datetime,
+) -> SigV4Signature:
+ """Sign a request. ``headers`` are the caller's headers (any case); the
+ result carries every header to send, lowercase, with ``host``,
+ ``x-amz-date``, ``x-amz-security-token`` (when a session token exists)
+ and ``authorization`` added."""
+ if now.tzinfo is None:
+ now = now.replace(tzinfo=timezone.utc)
+ now = now.astimezone(timezone.utc)
+ amz_date = now.strftime("%Y%m%dT%H%M%SZ")
+ date = now.strftime("%Y%m%d")
+ parts = urllib.parse.urlsplit(url)
+
+ to_sign = {k.lower(): v for k, v in headers.items() if k.lower() != "authorization"}
+ to_sign["host"] = parts.netloc
+ to_sign["x-amz-date"] = amz_date
+ to_sign.pop("x-amz-security-token", None)
+ if credentials.session_token:
+ to_sign["x-amz-security-token"] = credentials.session_token
+
+ canonical, signed = canonicalize(method, url, to_sign, payload)
+ scope = f"{date}/{region}/{service}/aws4_request"
+ string_to_sign = "\n".join([_ALGORITHM, amz_date, scope, hashlib.sha256(canonical.encode()).hexdigest()])
+
+ key = ("AWS4" + credentials.secret_access_key).encode()
+ for piece in (date, region, service, "aws4_request"):
+ key = hmac.new(key, piece.encode(), hashlib.sha256).digest()
+ signature = hmac.new(key, string_to_sign.encode(), hashlib.sha256).hexdigest()
+
+ authorization = (
+ f"{_ALGORITHM} Credential={credentials.access_key_id}/{scope}, "
+ f"SignedHeaders={signed}, Signature={signature}"
+ )
+ out = {k: _trim(v) for k, v in to_sign.items()}
+ out["authorization"] = authorization
+ return SigV4Signature(canonical_request=canonical, string_to_sign=string_to_sign, authorization=authorization, headers=out)
diff --git a/dspy/_vendor/lm15/compat.py b/dspy/_vendor/lm15/compat.py
new file mode 100644
index 000000000..eb72102c7
--- /dev/null
+++ b/dspy/_vendor/lm15/compat.py
@@ -0,0 +1,1171 @@
+"""
+lm15.compat — Typed provider/API compatibility policies.
+
+Compatibility policies describe how a provider adapter should serialize a
+canonical lm15 request for a specific API dialect. They are intentionally
+separate from lm15.types: Request/Response describe *what* the caller wants;
+compat profiles describe provider wire-format quirks.
+
+Fields default to None, which means "inherit from the parent profile". The
+string value "auto" is an explicit policy: ask the adapter to use its automatic
+heuristic for that field. Keeping None distinct from "auto" matters because
+profiles are layered.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+from dataclasses import dataclass, field, fields
+from typing import Literal, TypeAlias, get_args
+
+from .types import JsonObject
+
+
+# ─── Shared helpers ──────────────────────────────────────────────────
+
+
+def _check_literal_or_none(value: object, literal_alias: object, field_name: str) -> None:
+ if value is not None and value not in get_args(literal_alias): # type: ignore[arg-type]
+ raise ValueError(f"unsupported {field_name}: {value!r}")
+
+
+def _check_json_object_or_none(value: object, field_name: str) -> None:
+ if value is None:
+ return
+ if not isinstance(value, dict):
+ raise TypeError(f"{field_name} must be a JSON object or None")
+
+
+def _merge_json_object(a: JsonObject | None, b: JsonObject | None) -> JsonObject | None:
+ if a is None:
+ return b
+ if b is None:
+ return a
+ return {**a, **b}
+
+
+# ─── OpenAI Responses API compatibility ──────────────────────────────
+
+OpenAIResponsesDeveloperRole = Literal["auto", "developer", "system"]
+OpenAIResponsesMaxOutputTokensField = Literal[
+ "auto",
+ "max_output_tokens",
+ "max_completion_tokens",
+ "max_tokens",
+]
+OpenAIResponsesReasoningFormat = Literal[
+ "auto",
+ "none",
+ "responses_reasoning",
+ "reasoning_effort",
+ "openrouter",
+ "deepseek",
+ "qwen",
+ "qwen_chat_template",
+ "zai",
+]
+OpenAIToolResultName = Literal["auto", "include", "omit"]
+OpenAIStrictTools = Literal["auto", "include", "omit"]
+# "openai": prompt_cache_key, prompt_cache_retention, and the explicit
+# breakpoint mark (prompt_cache_breakpoint / prompt_cache_options, gpt-5.6+).
+# "openai_implicit": the two documented fields only, on a server that caches
+# every prefix automatically and would take a breakpoint mark without
+# acting on it (Meta, guide--prompt-caching.md: "you do not … mark
+# breakpoints"; live 2026-09-03 the mark answered 200 with no signal either
+# way). As with "none", an explicit CacheConfig is not an error there —
+# the prefix is cached regardless — but no undocumented field is sent.
+OpenAICacheControl = Literal["auto", "none", "openai", "openai_implicit", "anthropic"]
+# Whether a replayed assistant message that precedes a function_call in the
+# same turn carries `phase: "commentary"`. Meta Model API stamps the field
+# on the messages it emits before a tool call and documents replaying them
+# untagged as HTTP 400 (protocols--responses.md § Message phase); live
+# 2026-09-03 the untagged replay answered 200, so the tag is sent for the
+# documented quality reason ("dropping it can degrade quality"), not to
+# avoid an error. OpenAI has no such field: "omit".
+OpenAIResponsesCommentaryPhase = Literal["auto", "omit", "tag"]
+# The multipart key for input images on POST /images/edits. OpenAI takes
+# `image[]` (pinned: cases/openai/image_edit.json); Meta rejects that key
+# and asks for `image[0]`, `image[1]`, … (live 2026-09-03, HTTP 400
+# "`image[]` is not a valid image key; use `image[N]`").
+OpenAIResponsesEditImageField = Literal["auto", "array", "indexed"]
+# Which server-executed tool types the canonical BuiltinTool names map to.
+# "openai": OpenAI's Responses vocabulary (web_search_preview,
+# code_interpreter, file_search, computer_use_preview). "verbatim": the
+# canonical name IS the wire type — servers whose schema spells the tool
+# `web_search` (Meta responses--schemas.md; Moonshot responses--create.md)
+# — and a name the server lacks goes out unchanged and is refused loudly
+# (both: HTTP 400, live 2026-09-03). Named for the shape, not the first
+# server that needed it (renamed from "meta" on 2026-09-03, same day, before
+# any port or release carried the old value).
+OpenAIResponsesBuiltinTools = Literal["auto", "openai", "verbatim"]
+# MAP-10 (2026-09-07): what a ToolResultPart's media parts may become on the
+# wire. "native" = images and documents as native blocks inside the result
+# item; "images" = images only (documents raise); "reject" = every media part
+# raises before the wire. Measured per preset:
+# lm15-contract/research/tool-result-content/30-model.md.
+ToolResultMedia = Literal["auto", "native", "images", "reject"]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIResponsesCompat:
+ """Partial compatibility policy for OpenAI Responses-family APIs.
+
+ None means "inherit". Non-None values override parent profiles. The value
+ "auto" means "explicitly use adapter auto-detection".
+ """
+
+ developer_role: OpenAIResponsesDeveloperRole | None = None
+ max_output_tokens_field: OpenAIResponsesMaxOutputTokensField | None = None
+ reasoning_format: OpenAIResponsesReasoningFormat | None = None
+ tool_result_name: OpenAIToolResultName | None = None
+ strict_tools: OpenAIStrictTools | None = None
+ cache_control: OpenAICacheControl | None = None
+ # New knobs are keyword-only: routing/extensions keep their original slots.
+ commentary_phase: OpenAIResponsesCommentaryPhase | None = field(default=None, kw_only=True)
+ edit_image_field: OpenAIResponsesEditImageField | None = field(default=None, kw_only=True)
+ builtin_tools: OpenAIResponsesBuiltinTools | None = field(default=None, kw_only=True)
+ tool_result_media: ToolResultMedia | None = field(default=None, kw_only=True)
+ routing: JsonObject | None = None
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_literal_or_none(self.tool_result_media, ToolResultMedia, "tool_result_media")
+ _check_literal_or_none(self.developer_role, OpenAIResponsesDeveloperRole, "developer_role")
+ _check_literal_or_none(self.commentary_phase, OpenAIResponsesCommentaryPhase, "commentary_phase")
+ _check_literal_or_none(self.edit_image_field, OpenAIResponsesEditImageField, "edit_image_field")
+ _check_literal_or_none(self.builtin_tools, OpenAIResponsesBuiltinTools, "builtin_tools")
+ _check_literal_or_none(
+ self.max_output_tokens_field,
+ OpenAIResponsesMaxOutputTokensField,
+ "max_output_tokens_field",
+ )
+ _check_literal_or_none(self.reasoning_format, OpenAIResponsesReasoningFormat, "reasoning_format")
+ _check_literal_or_none(self.tool_result_name, OpenAIToolResultName, "tool_result_name")
+ _check_literal_or_none(self.strict_tools, OpenAIStrictTools, "strict_tools")
+ _check_literal_or_none(self.cache_control, OpenAICacheControl, "cache_control")
+ _check_json_object_or_none(self.routing, "routing")
+ _check_json_object_or_none(self.extensions, "extensions")
+
+ @classmethod
+ def preset(cls, name: str) -> "OpenAIResponsesCompat":
+ """The named server dialect from :data:`OPENAI_RESPONSES_PRESETS`.
+
+ Accepts the permanent spelling aliases (``responses``, ``lm-studio``,
+ ``z.ai``); raises ``ValueError`` for an unknown name.
+ """
+ key = _preset_key(name)
+ try:
+ return OPENAI_RESPONSES_PRESETS[key]
+ except KeyError:
+ raise ValueError(f"unknown OpenAIResponsesCompat preset: {name!r}") from None
+
+
+# Named Responses-dialect servers. Same table shape as the chat dialect's
+# OPENAI_CHAT_PRESETS (the if-chain it replaced was the fifth copy of
+# provider knowledge the registry entry of 2026-09-03 set out to remove).
+OPENAI_RESPONSES_PRESETS: dict[str, OpenAIResponsesCompat] = {
+ "openai": OpenAIResponsesCompat(
+ developer_role="developer",
+ max_output_tokens_field="max_output_tokens",
+ reasoning_format="responses_reasoning",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai",
+ ),
+ "openrouter": OpenAIResponsesCompat(
+ developer_role="developer",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="openrouter",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai",
+ tool_result_media="reject", # MAP-10: no receipt on this door — reject until one exists
+ ),
+ "ollama": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="none",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: no receipt on this door — reject until one exists
+ ),
+ "vllm": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: no receipt on this door — reject until one exists
+ ),
+ "sglang": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: no receipt on this door — reject until one exists
+ ),
+ "qwen": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="qwen",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: no receipt on this door — reject until one exists
+ ),
+ "deepseek": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="deepseek",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: its Chat and Messages doors both show the model [Unsupported Image] — reject
+ ),
+ "zai": OpenAIResponsesCompat(
+ developer_role="system",
+ max_output_tokens_field="max_tokens",
+ reasoning_format="zai",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: no receipt on this door (zai Chat carries images) — reject until one exists
+ ),
+ # Meta Model API (dev.meta.ai, scraped 2026-09-03 —
+ # lm15-contract/scrapes/meta/pages): the Responses wire as OpenAI
+ # speaks it. `developer` role (protocols--responses.md), `max_output_
+ # tokens` (min 16), `reasoning.effort` + `reasoning.summary`
+ # (guide--reasoning.md; `none` is refused loudly by Muse Spark),
+ # `prompt_cache_key` and `prompt_cache_retention` honoured (guide--
+ # prompt-caching.md); the breakpoint mark is never sent (cache_control
+ # "openai_implicit": the server accepts it silently, live 2026-09-03).
+ "meta": OpenAIResponsesCompat(
+ developer_role="developer",
+ max_output_tokens_field="max_output_tokens",
+ reasoning_format="responses_reasoning",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai_implicit",
+ commentary_phase="tag",
+ edit_image_field="indexed",
+ builtin_tools="verbatim",
+ tool_result_media="native", # MAP-10: FunctionCallOutputContentListParam; image/mixed/pair/pdf received (muse-spark-1.3)
+ ),
+ # Moonshot AI over the Responses wire (platform.kimi.ai responses--
+ # create.md OpenAPI, scraped 2026-09-03): kimi-k3 only; `instructions`
+ # + `developer` role; `max_output_tokens`; `reasoning.effort` low|high|
+ # max; stateless (`store` always false, `previous_response_id` always
+ # null) and reasoning comes back as `summary` text with
+ # `encrypted_content: null`, replayed as-is; `prompt_cache_key` and
+ # `safety_identifier`; tools function|custom|namespace|web_search — the
+ # canonical name is the wire type (builtin_tools "verbatim").
+ "moonshotai": OpenAIResponsesCompat(
+ developer_role="developer",
+ max_output_tokens_field="max_output_tokens",
+ reasoning_format="responses_reasoning",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai_implicit",
+ builtin_tools="verbatim",
+ tool_result_media="images", # MAP-10: images received (kimi-k3); input_file is 400 "unknown content part type"
+ ),
+}
+
+# Default base URLs for the Responses presets that name a server (the
+# registry's access policies point here so each URL has one copy).
+OPENAI_RESPONSES_PRESET_BASE_URLS: dict[str, str] = {
+ "openai": "https://api.openai.com/v1",
+ "openrouter": "https://openrouter.ai/api/v1",
+ # dev.meta.ai overview.md: one base URL for every Meta Model API surface.
+ "meta": "https://api.meta.ai/v1",
+ # platform.kimi.ai api--overview.md: /v1/responses on the OpenAI root.
+ "moonshotai": "https://api.moonshot.ai/v1",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedOpenAIResponsesCompat:
+ """Fully resolved OpenAI Responses compatibility policy."""
+
+ developer_role: Literal["developer", "system"] = "developer"
+ max_output_tokens_field: Literal["max_output_tokens", "max_completion_tokens", "max_tokens"] = "max_output_tokens"
+ reasoning_format: Literal[
+ "none",
+ "responses_reasoning",
+ "reasoning_effort",
+ "openrouter",
+ "deepseek",
+ "qwen",
+ "qwen_chat_template",
+ "zai",
+ ] = "responses_reasoning"
+ tool_result_name: Literal["include", "omit"] = "omit"
+ strict_tools: Literal["include", "omit"] = "omit"
+ cache_control: Literal["none", "openai", "openai_implicit", "anthropic"] = "openai"
+ commentary_phase: Literal["omit", "tag"] = field(default="omit", kw_only=True)
+ edit_image_field: Literal["array", "indexed"] = field(default="array", kw_only=True)
+ builtin_tools: Literal["openai", "verbatim"] = field(default="openai", kw_only=True)
+ # The documented Responses wire takes input_image and input_file in a
+ # function_call_output array (MAP-10; openai gpt-5.4 exact, 2026-09-07).
+ tool_result_media: Literal["native", "images", "reject"] = field(default="native", kw_only=True)
+ routing: JsonObject | None = None
+ extensions: JsonObject | None = None
+
+
+# ─── OpenAI Chat Completions compatibility ───────────────────────────
+
+# Knobs a per-model override may set (OpenAIChatCompat.model_overrides).
+_CHAT_OVERRIDABLE: frozenset[str] = frozenset({
+ "instruction_role", "max_tokens_field", "stream_usage", "thinking_format", "thinking_replay",
+ "assistant_reasoning_content", "strict_tools", "cache_control", "user_field",
+ "forced_tool_choice", "json_schema", "reasoning_efforts", "tool_result_media",
+})
+
+OpenAIChatInstructionRole = Literal["auto", "developer", "system"]
+OpenAIChatMaxTokensField = Literal["auto", "max_completion_tokens", "max_tokens"]
+OpenAIChatStreamUsage = Literal["auto", "include", "omit"]
+OpenAIChatAssistantAfterToolResult = Literal["auto", "insert", "omit"]
+OpenAIChatThinkingReplay = Literal["auto", "native", "as_text", "omit"]
+OpenAIChatAssistantReasoningContent = Literal["auto", "include_empty", "omit"]
+# "deepseek" names a wire SHAPE — thinking={"type": enabled|disabled} plus
+# reasoning_effort — not a company: DeepSeek, xAI and Z.AI all speak it
+# (docs.z.ai chat--create.md ChatThinking; the earlier "zai" value sent
+# Qwen's enable_thinking and was never live-validated; removed 2026-09-03).
+# "kimi" is the union of Moonshot's two documented shapes, split by intent
+# rather than by model: an effort word goes out as top-level
+# `reasoning_effort` alone (kimi-k3: low|high|max, api--models-overview.md),
+# and off goes out as `thinking: {type: disabled}` alone (kimi-k2.6). Each
+# family rejects the other family's field loudly (live 2026-09-03), so
+# neither is ever sent alongside the one the docs name for that intent.
+OpenAIChatThinkingFormat = Literal[
+ "auto",
+ "none",
+ "reasoning_effort",
+ "openrouter",
+ "deepseek",
+ "kimi",
+ "qwen",
+ "qwen_chat_template",
+]
+# BuiltinTool policy for the chat dialect. The base Chat Completions wire
+# carries function/custom tools ONLY (doc: chat--create.md), and some
+# compat servers silently IGNORE unknown tool types (OpenRouter, verified
+# live 2026-09-01) — so "reject" (raise) is the only safe default.
+# "groq" maps canonical builtin names onto Groq's server-executed tool
+# types (browser_search / code_interpreter, both verified live
+# 2026-09-01).
+OpenAIChatBuiltinTools = Literal["auto", "reject", "groq"]
+# Which request field carries Config.user_id. OpenAI's dialect spells it
+# `user`; DeepSeek documents `user_id` (content-safety, KV-cache and
+# scheduling isolation, rate-limit.md) and accepts `user` silently (live
+# 2026-09-03: 200 either way, no echo) — so the documented name is the
+# only one that can be trusted to do anything. Meta deprecates `user` in
+# favour of `safety_identifier` (protocols--chat-completions.md § Parameters),
+# the same field the Responses dialect already sends.
+OpenAIChatUserField = Literal["auto", "user", "user_id", "safety_identifier"]
+# Whether the server honours a tool_choice other than "auto" (required,
+# none, a named function, an allowlist). "reject" makes the adapter raise
+# UnsupportedFeatureError before the wire. Z.AI documents auto only and
+# ignores the rest silently (live 2026-09-03: mode=required answered text,
+# mode=none called the tool) — a silent widen is worse than an error (MAP-8).
+OpenAIChatForcedToolChoice = Literal["auto", "send", "reject"]
+# Whether the server honours response_format.type=json_schema. "reject"
+# raises before the wire. DeepSeek answers 400 (loud, nothing to do); Z.AI
+# answers 200 with free-form, fenced JSON that ignores the schema (live
+# 2026-09-03) — silent, so the adapter must refuse.
+OpenAIChatJsonSchema = Literal["auto", "send", "reject"]
+# The server's native reasoning-effort levels, when the server does NOT
+# refuse the others. MAP-7 rule 2: a word with no native level raises
+# client-side rather than downgrading silently. Most servers answer 400 to
+# an unknown word and need nothing here (None); Moonshot's kimi-k3 documents
+# low|high|max and answers 200 to `medium` and to `bogus` alike (live
+# 2026-09-03), so the preset lists the three. `off` is never in the list:
+# the off switch is thinking_format's business.
+OpenAIChatReasoningEfforts = tuple[str, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAIChatCompat:
+ """Partial compatibility policy for OpenAI Chat Completions-family APIs.
+
+ This class is consumed by OpenAIChatLM (lm15.providers.openai_chat); it is
+ kept separate so profiles can describe chat-completions style endpoints
+ without overloading OpenAIResponsesCompat.
+ """
+
+ instruction_role: OpenAIChatInstructionRole | None = None
+ max_tokens_field: OpenAIChatMaxTokensField | None = None
+ stream_usage: OpenAIChatStreamUsage | None = None
+ tool_result_name: OpenAIToolResultName | None = None
+ assistant_after_tool_result: OpenAIChatAssistantAfterToolResult | None = None
+ thinking_format: OpenAIChatThinkingFormat | None = None
+ thinking_replay: OpenAIChatThinkingReplay | None = None
+ assistant_reasoning_content: OpenAIChatAssistantReasoningContent | None = None
+ strict_tools: OpenAIStrictTools | None = None
+ builtin_tools: OpenAIChatBuiltinTools | None = None
+ tool_result_media: ToolResultMedia | None = field(default=None, kw_only=True)
+ cache_control: OpenAICacheControl | None = None
+ user_field: OpenAIChatUserField | None = None
+ forced_tool_choice: OpenAIChatForcedToolChoice | None = None
+ json_schema: OpenAIChatJsonSchema | None = None
+ reasoning_efforts: OpenAIChatReasoningEfforts | None = field(default=None, kw_only=True)
+ routing: JsonObject | None = None
+ extensions: JsonObject | None = None
+ # Per-model-family overrides on a door that forwards knobs to many
+ # vendors' models (Bedrock's Chat Completions door, live 2026-09-03:
+ # DeepSeek/Mistral/Qwen/Z.AI honour tool_choice=required and
+ # json_schema, gpt-oss ignores both, Gemma ignores tool_choice). Each
+ # entry is (model-id prefix, {knob: value}); the first matching prefix
+ # wins; the knobs are the fields above. Resolved per request.
+ model_overrides: tuple[tuple[str, dict[str, str]], ...] = field(default=(), kw_only=True)
+
+ def __post_init__(self) -> None:
+ overrides = []
+ for prefix, knobs in self.model_overrides:
+ if not isinstance(prefix, str) or not prefix:
+ raise ValueError("model_overrides: each prefix is a non-empty string")
+ knobs = dict(knobs)
+ for name in knobs:
+ if name not in _CHAT_OVERRIDABLE:
+ raise ValueError(f"model_overrides: {name!r} is not an overridable knob ({sorted(_CHAT_OVERRIDABLE)})")
+ overrides.append((prefix, knobs))
+ object.__setattr__(self, "model_overrides", tuple(overrides))
+ _check_literal_or_none(self.instruction_role, OpenAIChatInstructionRole, "instruction_role")
+ _check_literal_or_none(self.max_tokens_field, OpenAIChatMaxTokensField, "max_tokens_field")
+ _check_literal_or_none(self.stream_usage, OpenAIChatStreamUsage, "stream_usage")
+ _check_literal_or_none(self.tool_result_name, OpenAIToolResultName, "tool_result_name")
+ _check_literal_or_none(
+ self.assistant_after_tool_result,
+ OpenAIChatAssistantAfterToolResult,
+ "assistant_after_tool_result",
+ )
+ _check_literal_or_none(self.thinking_format, OpenAIChatThinkingFormat, "thinking_format")
+ _check_literal_or_none(self.thinking_replay, OpenAIChatThinkingReplay, "thinking_replay")
+ _check_literal_or_none(
+ self.assistant_reasoning_content,
+ OpenAIChatAssistantReasoningContent,
+ "assistant_reasoning_content",
+ )
+ _check_literal_or_none(self.strict_tools, OpenAIStrictTools, "strict_tools")
+ _check_literal_or_none(self.builtin_tools, OpenAIChatBuiltinTools, "builtin_tools")
+ _check_literal_or_none(self.tool_result_media, ToolResultMedia, "tool_result_media")
+ _check_literal_or_none(self.cache_control, OpenAICacheControl, "cache_control")
+ _check_literal_or_none(self.user_field, OpenAIChatUserField, "user_field")
+ _check_literal_or_none(self.forced_tool_choice, OpenAIChatForcedToolChoice, "forced_tool_choice")
+ _check_literal_or_none(self.json_schema, OpenAIChatJsonSchema, "json_schema")
+ if self.reasoning_efforts is not None:
+ from .types import REASONING_EFFORTS
+
+ bad = [w for w in self.reasoning_efforts if w not in REASONING_EFFORTS or w == "off"]
+ if not isinstance(self.reasoning_efforts, tuple) or bad:
+ raise ValueError(
+ f"reasoning_efforts must be a tuple of ReasoningEffort words other than 'off'; got {self.reasoning_efforts!r}"
+ )
+ _check_json_object_or_none(self.routing, "routing")
+ _check_json_object_or_none(self.extensions, "extensions")
+
+
+ def for_model(self, model: str) -> "OpenAIChatCompat":
+ """This compat with the first matching ``model_overrides`` entry applied."""
+ for prefix, knobs in self.model_overrides:
+ if model.startswith(prefix):
+ return dataclasses.replace(self, model_overrides=(), **knobs)
+ return self
+
+ @classmethod
+ def preset(cls, name: str) -> "OpenAIChatCompat":
+ """The named server dialect from :data:`OPENAI_CHAT_PRESETS`.
+
+ Accepts the permanent spelling aliases (``lm-studio``, ``z.ai``,
+ ``openai_chat``); raises ``ValueError`` for an unknown name.
+ """
+ key = _preset_key(name)
+ try:
+ return OPENAI_CHAT_PRESETS[key]
+ except KeyError:
+ raise ValueError(f"unknown OpenAIChatCompat preset: {name!r}") from None
+
+
+def _preset_key(name: str) -> str:
+ key = name.lower().replace("-", "_").replace(" ", "_").replace(".", "_")
+ return _OPENAI_CHAT_PRESET_ALIASES.get(key, key)
+
+
+# Spelling aliases → canonical preset key. Every alias is permanent. One
+# map serves all three dialect tables: a name means the same server in each.
+_OPENAI_CHAT_PRESET_ALIASES: dict[str, str] = {
+ "openai_chat": "openai",
+ "chat": "openai",
+ "chat_completions": "openai",
+ "responses": "openai",
+ "openai_responses": "openai",
+ "lmstudio": "ollama",
+ "lm_studio": "ollama",
+ "dashscope_qwen": "qwen",
+ "z_ai": "zai",
+}
+
+# The Chat Completions server dialects lm15 knows, as data. A preset
+# describes ONE server's quirks (instruction role, token-limit field,
+# thinking wire shape, …); it says nothing about credentials or routing —
+# that is the provider registry (lm15.registry), which names a preset by
+# key. Every field value here is pinned by a live receipt or the server's
+# own documentation, cited inline; a preset changes with new evidence, not
+# with a hunch.
+OPENAI_CHAT_PRESETS: dict[str, OpenAIChatCompat] = {
+ "openai": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai",
+ tool_result_media="reject", # MAP-10: text-only tool row; gpt-5.4 received the USER image and not the tool image
+ ),
+ # ollama / LM Studio: max_tokens, no reasoning dial on the wire.
+ "ollama": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="none",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: openai.go builds image rows without ToolCallID; no receipt — reject until one exists
+ ),
+ # Groq: server-executed builtin tools (browser_search / code_interpreter,
+ # live 2026-09-01); reasoning_effort dial; no cache_control field.
+ "groq": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ builtin_tools="groq",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: server 400 "messages[2].content must be a string" despite the SDK union
+ ),
+ # OpenRouter: unified reasoning object; OpenAI-shaped cache_control.
+ "openrouter": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="openrouter",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai",
+ tool_result_media="reject", # MAP-10: schema says image; no receipt (401 during the pass) — reject until one exists
+ ),
+ # xAI, pinned live 2026-09-01 against grok-4.6: max_tokens accepted,
+ # reasoning arrives as message.reasoning_content (deepseek shape),
+ # stream_options.include_usage honored, no cache_control field (prompt
+ # caching is automatic; usage reports cached_tokens).
+ "xai": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="deepseek",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="images", # MAP-10: image tool results received (grok-4.20); documents 400 "use /v1/responses"
+ ),
+ "vllm": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: parser carries it; no server reachable in the pass — reject until a receipt
+ ),
+ "sglang": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject", # MAP-10: schema carries it; no server reachable in the pass — reject until a receipt
+ ),
+ # DeepSeek (api-docs.deepseek.com, scraped 2026-09-03 —
+ # lm15-contract/scrapes/deepseek/pages): thinking={"type": enabled|
+ # disabled} + reasoning_effort (guide--thinking-mode.md); max_tokens
+ # (chat--create.md); usage in the final stream chunk via
+ # stream_options.include_usage; context caching is automatic on disk,
+ # no cache_control field (guide--kv-cache.md). thinking_replay=native
+ # + include_empty: with tools present, every assistant turn must carry
+ # reasoning_content back — even turns that made no call — or the API
+ # answers 400 (guide--thinking-mode.md § Tool Calls).
+ "deepseek": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="deepseek",
+ thinking_replay="native",
+ assistant_reasoning_content="include_empty",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ user_field="user_id",
+ tool_result_media="reject", # MAP-10: HTTP 200 and the model sees [Unsupported Image] — silent degrade
+ ),
+ "qwen": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="qwen",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ ),
+ # Z.AI (docs.z.ai, scraped 2026-09-03 — lm15-contract/scrapes/zai/pages):
+ # thinking={"type": enabled|disabled} + reasoning_effort (chat--create.md
+ # ChatThinking, the deepseek wire shape; GLM-5.3 cannot disable and the
+ # request fails loudly — model--glm-5.3.md); max_tokens; interleaved
+ # thinking asks for reasoning_content to be returned with tool results
+ # (guide--thinking-mode.md); implicit context caching, usage in
+ # prompt_tokens_details.cached_tokens (guide--cache.md); user_id 6–128
+ # chars is the documented identity field (chat--create.md).
+ # Amazon Bedrock's OpenAI Chat Completions door on bedrock-runtime
+ # (live 2026-09-03, openai.gpt-oss-20b-1:0, SigV4; receipts/2026-09-03-
+ # bedrock-chat/): system role, max_completion_tokens, usage on the final
+ # chunk, reasoning_effort accepted, `user` accepted. The door forwards
+ # tool_choice and response_format to every vendor's model; whether a
+ # model honours them is per family (six families probed, family-*.json):
+ # the two that ignore them are refused per model (MAP-8) below.
+ "bedrock": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ user_field="user",
+ forced_tool_choice="send",
+ json_schema="send",
+ model_overrides=(
+ # receipts/2026-09-03-bedrock-chat/family-*.json: HTTP 200, the
+ # knob sent, the model answered as if it were absent.
+ ("openai.gpt-oss", {"forced_tool_choice": "reject", "json_schema": "reject"}),
+ ("google.gemma", {"forced_tool_choice": "reject"}),
+ ),
+ tool_result_media="reject", # MAP-10: 400 validation_error on the array form
+ ),
+ # Bedrock-mantle Chat Completions (live 2026-09-04, openai.gpt-oss-20b and
+ # deepseek.v3.2; receipts/2026-09-04-bedrock-chat/probe-mantle-chat-* and
+ # receipts/<date>-bedrock-mantle-chat/). Same Chat Completions dialect as
+ # `bedrock`, a different host: un-versioned ids, a working /models list,
+ # gpt-oss reasoning in `message.reasoning` (the parser already reads that
+ # field). tool_choice / json_schema overrides land from the family
+ # probes of this door, not copied from `bedrock` — mantle translates,
+ # so a silent ignore on runtime is not evidence here. Live 2026-09-04
+ # family probes: DeepSeek/Mistral/Qwen/Z.AI/Gemma honour both knobs
+ # (Gemma honours tool_choice here; it ignores it on bedrock-runtime);
+ # gpt-oss ignores both (HTTP 200, plain text / prose+JSON).
+ "bedrock_mantle": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ user_field="user",
+ forced_tool_choice="send",
+ json_schema="send",
+ model_overrides=(
+ ("openai.gpt-oss", {"forced_tool_choice": "reject", "json_schema": "reject"}),
+ ),
+ ),
+ "zai": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_tokens",
+ stream_usage="include",
+ thinking_format="deepseek",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ user_field="user_id",
+ forced_tool_choice="reject",
+ json_schema="reject",
+ tool_result_media="images", # MAP-10: image tool results received (glm-4.6v); a file part is 400 (code 1210)
+ ),
+ # Meta Model API (dev.meta.ai, scraped 2026-09-03 — lm15-contract/scrapes/
+ # meta/pages, protocols--chat-completions.md): `developer` is the
+ # documented instruction role (`system` is merged at the same level);
+ # `max_completion_tokens` (`max_tokens` is a deprecated alias); top-level
+ # `reasoning_effort` (Muse Spark always reasons — `none` is HTTP 400,
+ # loud); `stream_options.include_usage` documented (chat--schemas.md);
+ # `prompt_cache_key` honoured, caching otherwise automatic (guide--
+ # prompt-caching.md); `safety_identifier` supersedes `user`. The
+ # `reasoning_content` field on this wire is redacted to empty for
+ # external keys (guide--reasoning.md § Chat Completions), so nothing is
+ # replayed: thinking_replay stays at the dialect default.
+ "meta": OpenAIChatCompat(
+ instruction_role="developer",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai_implicit",
+ user_field="safety_identifier",
+ tool_result_media="reject", # MAP-10: 400 "did not match any supported type"; Meta's Responses door carries media
+ ),
+ # Moonshot AI / Kimi API Platform (platform.kimi.ai, scraped 2026-09-03 —
+ # lm15-contract/scrapes/moonshotai/pages, chat--create.md OpenAPI):
+ # `role: system` instructions; `max_completion_tokens` (`max_tokens` is
+ # marked deprecated); `stream_options.include_usage` documented; the
+ # reasoning dial is split by model family — kimi-k3 takes top-level
+ # `reasoning_effort` (low|high|max, always thinks), kimi-k2.6 takes
+ # `thinking: {type}` (guide--thinking-models.md) — which the "kimi" shape
+ # expresses by intent; every model returns `reasoning_content` and the
+ # docs require it back verbatim in multi-turn and tool loops
+ # (thinking_replay=native); context caching is automatic with
+ # `prompt_cache_key` as the only knob (guide--context-caching.md);
+ # `safety_identifier` is the documented identity field (no `user`).
+ "moonshotai": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="kimi",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="openai_implicit",
+ user_field="safety_identifier",
+ reasoning_efforts=("low", "high", "max"),
+ tool_result_media="images", # MAP-10: image tool results received (kimi-k2.6); a file part is 400
+ ),
+}
+
+
+# Default base URLs for the Chat Completions presets that name a server.
+# Used by OpenAIChatLM when a compat preset is given by name and no
+# explicit base_url overrides it; the provider registry's access policies
+# point here so there is one copy of each URL.
+OPENAI_CHAT_PRESET_BASE_URLS: dict[str, str] = {
+ "openai": "https://api.openai.com/v1",
+ "ollama": "http://localhost:11434/v1",
+ "groq": "https://api.groq.com/openai/v1",
+ "openrouter": "https://openrouter.ai/api/v1",
+ "xai": "https://api.x.ai/v1",
+ "vllm": "http://localhost:8000/v1",
+ "sglang": "http://localhost:30000/v1",
+ # api-docs.deepseek.com/first-call.md: base_url https://api.deepseek.com
+ # (no /v1; the site also answers /v1, but the documented form wins).
+ "deepseek": "https://api.deepseek.com",
+ # docs.z.ai introduction.md: the general endpoint. The GLM Coding Plan
+ # uses a different, subscription-bound endpoint that lm15 does not name.
+ "zai": "https://api.z.ai/api/paas/v4",
+ # dev.meta.ai overview.md: one base URL for every Meta Model API surface.
+ "meta": "https://api.meta.ai/v1",
+ # platform.kimi.ai api--overview.md: the OpenAI-compatible root (Chat
+ # Completions and Responses); the Anthropic wire lives at /anthropic.
+ "moonshotai": "https://api.moonshot.ai/v1",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedOpenAIChatCompat:
+ """Fully resolved OpenAI Chat Completions compatibility policy."""
+
+ instruction_role: Literal["developer", "system"] = "system"
+ max_tokens_field: Literal["max_completion_tokens", "max_tokens"] = "max_completion_tokens"
+ stream_usage: Literal["include", "omit"] = "include"
+ tool_result_name: Literal["include", "omit"] = "omit"
+ assistant_after_tool_result: Literal["insert", "omit"] = "omit"
+ thinking_format: Literal[
+ "none",
+ "reasoning_effort",
+ "openrouter",
+ "deepseek",
+ "kimi",
+ "qwen",
+ "qwen_chat_template",
+ ] = "reasoning_effort"
+ thinking_replay: Literal["native", "as_text", "omit"] = "as_text"
+ assistant_reasoning_content: Literal["include_empty", "omit"] = "omit"
+ strict_tools: Literal["include", "omit"] = "omit"
+ builtin_tools: Literal["reject", "groq"] = "reject"
+ # The base Chat wire's tool row takes text only (OpenAI's own schema; a
+ # 200 with the image not received on gpt-5.4, 2026-09-07): reject unless
+ # a preset proved the array form live (MAP-10).
+ tool_result_media: Literal["native", "images", "reject"] = field(default="reject", kw_only=True)
+ cache_control: Literal["none", "openai", "openai_implicit", "anthropic"] = "openai"
+ user_field: Literal["user", "user_id"] = "user"
+ forced_tool_choice: Literal["send", "reject"] = "send"
+ json_schema: Literal["send", "reject"] = "send"
+ reasoning_efforts: tuple[str, ...] | None = field(default=None, kw_only=True)
+ routing: JsonObject | None = None
+ extensions: JsonObject | None = None
+
+
+_CHAT_AUTO_DEFAULTS: dict[str, str] = {
+ "instruction_role": "system",
+ "max_tokens_field": "max_completion_tokens",
+ "stream_usage": "include",
+ "tool_result_name": "omit",
+ "assistant_after_tool_result": "omit",
+ "thinking_format": "reasoning_effort",
+ "thinking_replay": "as_text", # decision G (2026-09-01): unsigned thinking is replayed as text, never dropped
+ "assistant_reasoning_content": "omit",
+ "strict_tools": "omit",
+ "builtin_tools": "reject",
+ "tool_result_media": "reject",
+ "cache_control": "openai",
+ "user_field": "user",
+ "forced_tool_choice": "send",
+ "json_schema": "send",
+}
+
+
+def merge_openai_chat_compat(
+ base: OpenAIChatCompat,
+ override: OpenAIChatCompat | None,
+) -> OpenAIChatCompat:
+ """Merge partial OpenAI Chat compat objects.
+
+ None fields inherit. Non-None fields, including "auto", override.
+ """
+ if override is None:
+ return base
+
+ kwargs = {}
+ for f in fields(OpenAIChatCompat):
+ value = getattr(override, f.name)
+ if f.name == "extensions":
+ kwargs[f.name] = _merge_json_object(base.extensions, override.extensions)
+ else:
+ kwargs[f.name] = getattr(base, f.name) if value is None else value
+ return OpenAIChatCompat(**kwargs)
+
+
+def resolve_openai_chat_compat(partial: OpenAIChatCompat) -> ResolvedOpenAIChatCompat:
+ """Resolve a partial chat compat object into concrete serializer policy."""
+ kwargs: dict[str, object] = {}
+ for field_name, default in _CHAT_AUTO_DEFAULTS.items():
+ value = getattr(partial, field_name)
+ kwargs[field_name] = default if value in {None, "auto"} else value
+ return ResolvedOpenAIChatCompat(
+ reasoning_efforts=partial.reasoning_efforts,
+ routing=partial.routing,
+ extensions=partial.extensions,
+ **kwargs, # type: ignore[arg-type]
+ )
+
+
+# ─── Anthropic Messages compatibility ───────────────────────────────
+#
+# The Messages wire has few dialects, so this policy is small. It exists
+# for servers that speak the format but not all of it: DeepSeek's Anthropic
+# endpoint (api-docs.deepseek.com guide--anthropic-api.md, live 2026-09-03)
+# is the first. Fields default to None (inherit), "auto" is the dialect's
+# own behavior, same convention as the OpenAI policies above.
+
+# How reasoning is switched and steered. "anthropic": the model-class rule
+# (MAP-7 rule 10: manual class takes thinking.type=enabled + budget_tokens,
+# adaptive class takes thinking.type=adaptive + output_config.effort; off
+# is absence). "deepseek": thinking.type=enabled|disabled +
+# output_config.effort, no budget (the server ignores budget_tokens), and
+# off MUST be sent — absence means on for DeepSeek. "adaptive": every
+# model is the adaptive class (thinking.type=adaptive + output_config.
+# effort; `enabled` + budget_tokens is accepted but not translated) and
+# off MUST be sent as thinking.type=disabled — the server refuses it with
+# HTTP 400 rather than silently reasoning anyway (Meta Model API,
+# protocols--messages.md § Reasoning). "effort": the server documents no
+# `thinking` request field at all — output_config.effort is the whole dial
+# and goes out alone; off is sent as thinking.type=disabled, which the
+# server honours (Moonshot kimi-k3, messages--create.md; live 2026-09-03).
+AnthropicThinkingFormat = Literal["auto", "anthropic", "deepseek", "adaptive", "effort"]
+# How a ThinkingPart that carries no signature is replayed. "signed": the
+# dialect's rule — only a signed block goes back as `thinking`; an unsigned
+# one goes back as text (decision G: api.anthropic.com rejects unsigned
+# thinking blocks). "unsigned": the block goes back as `thinking` without
+# a signature — for servers that return `signature: ""` and accept the
+# block back (Moonshot, live 2026-09-03), where a text replay would put
+# the model's reasoning into its spoken turn.
+AnthropicThinkingReplay = Literal["auto", "signed", "unsigned"]
+# Whether temperature / top_p / top_k reach the wire. "reject" raises
+# before the wire on a server that documents none of them and swallows
+# them silently (Moonshot: `temperature: 0.5` is HTTP 200 here while the
+# same server's chat wire answers "only 1 is allowed for this model" —
+# live 2026-09-03; MAP-8 §2).
+AnthropicSamplingParams = Literal["auto", "send", "reject"]
+# Whether cache_control marks are placed. "none": the server ignores marks
+# and caches implicitly; nothing is placed and, as on the chat dialect's
+# "none", an explicit CacheConfig is not an error (implicit caching applies).
+AnthropicCacheControl = Literal["auto", "anthropic", "none"]
+# Whether output_config.format (a JSON schema) is honoured. "reject" raises
+# before the wire: DeepSeek answers 200 and ignores the schema (live
+# 2026-09-03) — silent, so the adapter refuses.
+AnthropicStructuredOutput = Literal["auto", "send", "reject"]
+# Whether disable_parallel_tool_use is honoured. DeepSeek documents it as
+# ignored; a silent no-op on ToolChoice.parallel=False is refused (MAP-8 §2).
+AnthropicParallelToolCalls = Literal["auto", "send", "reject"]
+
+
+@dataclass(frozen=True, slots=True)
+class AnthropicCompat:
+ """Partial compatibility policy for Anthropic Messages-family APIs.
+
+ ``model_prefixes`` refuses, before the wire, any model id that does not
+ start with one of the prefixes: DeepSeek's endpoint silently serves
+ ``claude-opus*`` as ``deepseek-v4-pro`` and ``claude-haiku*`` /
+ ``claude-sonnet*`` as ``deepseek-v4-flash`` (docs and live 2026-09-03);
+ lm15 does not take part in a substitution the caller cannot see.
+ None means any model id goes out as typed.
+ """
+
+ thinking_format: AnthropicThinkingFormat | None = None
+ # Preserve the original thinking_format/cache_control/... positional API.
+ thinking_replay: AnthropicThinkingReplay | None = field(default=None, kw_only=True)
+ cache_control: AnthropicCacheControl | None = None
+ structured_output: AnthropicStructuredOutput | None = None
+ parallel_tool_calls: AnthropicParallelToolCalls | None = None
+ sampling_params: AnthropicSamplingParams | None = field(default=None, kw_only=True)
+ tool_result_media: ToolResultMedia | None = field(default=None, kw_only=True)
+ reasoning_efforts: tuple[str, ...] | None = field(default=None, kw_only=True)
+ model_prefixes: tuple[str, ...] | None = None
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_literal_or_none(self.tool_result_media, ToolResultMedia, "tool_result_media")
+ _check_literal_or_none(self.thinking_format, AnthropicThinkingFormat, "thinking_format")
+ _check_literal_or_none(self.thinking_replay, AnthropicThinkingReplay, "thinking_replay")
+ _check_literal_or_none(self.cache_control, AnthropicCacheControl, "cache_control")
+ _check_literal_or_none(self.structured_output, AnthropicStructuredOutput, "structured_output")
+ _check_literal_or_none(self.parallel_tool_calls, AnthropicParallelToolCalls, "parallel_tool_calls")
+ _check_literal_or_none(self.sampling_params, AnthropicSamplingParams, "sampling_params")
+ if self.reasoning_efforts is not None:
+ from .types import REASONING_EFFORTS
+
+ bad = [w for w in self.reasoning_efforts if w not in REASONING_EFFORTS or w == "off"]
+ if not isinstance(self.reasoning_efforts, tuple) or bad:
+ raise ValueError(
+ f"reasoning_efforts must be a tuple of ReasoningEffort words other than 'off'; got {self.reasoning_efforts!r}"
+ )
+ if self.model_prefixes is not None:
+ object.__setattr__(self, "model_prefixes", tuple(str(p) for p in self.model_prefixes))
+ if not self.model_prefixes:
+ raise ValueError("model_prefixes must be None or a non-empty tuple")
+ _check_json_object_or_none(self.extensions, "extensions")
+
+ @classmethod
+ def preset(cls, name: str) -> "AnthropicCompat":
+ key = _preset_key(name)
+ try:
+ return ANTHROPIC_PRESETS[key]
+ except KeyError:
+ raise ValueError(f"unknown AnthropicCompat preset: {name!r}") from None
+
+
+ANTHROPIC_PRESETS: dict[str, AnthropicCompat] = {
+ "anthropic": AnthropicCompat(),
+ # DeepSeek over the Anthropic wire (api-docs.deepseek.com
+ # guide--anthropic-api.md; live 2026-09-03, receipts/2026-09-03-deepseek-anthropic):
+ # thinking={"type": enabled|disabled} + output_config.effort, budget_tokens
+ # ignored; cache_control ignored (implicit caching reports
+ # cache_read_input_tokens); output_config.format accepted and ignored;
+ # disable_parallel_tool_use ignored; claude-* model names silently
+ # remapped to DeepSeek models.
+ "deepseek": AnthropicCompat(
+ thinking_format="deepseek",
+ cache_control="none",
+ structured_output="reject",
+ parallel_tool_calls="reject",
+ model_prefixes=("deepseek-",),
+ tool_result_media="reject", # MAP-10: 200 and the model sees [Unsupported Image] — silent degrade
+ ),
+ # Meta Model API over the Anthropic wire (dev.meta.ai protocols--
+ # messages.md, scraped 2026-09-03): thinking={"type": "adaptive"} +
+ # output_config.effort low|medium|high|xhigh, `disabled` is HTTP 400;
+ # caching is automatic (guide--prompt-caching.md names no cache_control
+ # block on this wire) so no marks are placed; output_config.format
+ # (json_schema) and disable_parallel_tool_use are documented as honoured.
+ "meta": AnthropicCompat(
+ thinking_format="adaptive",
+ cache_control="none",
+ structured_output="send",
+ parallel_tool_calls="send",
+ tool_result_media="native", # MAP-10: image/mixed/pair/pdf received (muse-spark-1.3)
+ ),
+ # Moonshot AI over the Anthropic wire (platform.kimi.ai messages--
+ # create.md OpenAPI, scraped 2026-09-03): kimi-k3 only, always reasons;
+ # no `thinking` request field at all — `output_config.effort` low|high|
+ # max is the whole dial; `output_config.format` json_schema documented;
+ # caching automatic (no cache_control block documented); tool_choice
+ # auto|any|none. Live 2026-09-03 (receipts/2026-09-03-moonshotai-
+ # anthropic): `thinking: {type: disabled}` is honoured; `medium` and
+ # `bogus` efforts are accepted silently (allowlist); thinking blocks come
+ # back with `signature: ""` and an unsigned block is accepted back
+ # (replay "unsigned"); temperature and top_k are swallowed silently
+ # (reject); `disable_parallel_tool_use` is not in the schema (reject,
+ # the DeepSeek precedent).
+ "moonshotai": AnthropicCompat(
+ thinking_format="effort",
+ thinking_replay="unsigned",
+ cache_control="none",
+ structured_output="send",
+ parallel_tool_calls="reject",
+ sampling_params="reject",
+ reasoning_efforts=("low", "high", "max"),
+ model_prefixes=("kimi-",),
+ tool_result_media="images", # MAP-10: images received (kimi-k3); document block 400 "unsupported content type"
+ ),
+}
+
+# Default base URLs for the Anthropic presets that name a server.
+ANTHROPIC_PRESET_BASE_URLS: dict[str, str] = {
+ "anthropic": "https://api.anthropic.com/v1",
+ # api-docs.deepseek.com first-call.md: base_url https://api.deepseek.com/anthropic,
+ # which the Anthropic SDK completes to /anthropic/v1/messages (both the
+ # /anthropic and /anthropic/v1 roots answer, live 2026-09-03).
+ "deepseek": "https://api.deepseek.com/anthropic/v1",
+ # dev.meta.ai protocols--messages.md: base host https://api.meta.ai, the
+ # SDK appends /v1/messages — so the /v1 root, like the other two wires.
+ "meta": "https://api.meta.ai/v1",
+ # platform.kimi.ai api--overview.md: base_url https://api.moonshot.ai/anthropic,
+ # endpoint /anthropic/v1/messages — so the /anthropic/v1 root.
+ "moonshotai": "https://api.moonshot.ai/anthropic/v1",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedAnthropicCompat:
+ """Fully resolved Anthropic Messages compatibility policy."""
+
+ thinking_format: Literal["anthropic", "deepseek", "adaptive", "effort"] = "anthropic"
+ thinking_replay: Literal["signed", "unsigned"] = field(default="signed", kw_only=True)
+ cache_control: Literal["anthropic", "none"] = "anthropic"
+ structured_output: Literal["send", "reject"] = "send"
+ parallel_tool_calls: Literal["send", "reject"] = "send"
+ sampling_params: Literal["send", "reject"] = field(default="send", kw_only=True)
+ # tool_result.content takes image and document blocks (SDK ToolResultBlockParam;
+ # anthropic/claude-code exact 2026-09-07): native unless a server proved otherwise.
+ tool_result_media: Literal["native", "images", "reject"] = field(default="native", kw_only=True)
+ reasoning_efforts: tuple[str, ...] | None = field(default=None, kw_only=True)
+ model_prefixes: tuple[str, ...] | None = None
+ extensions: JsonObject | None = None
+
+
+_ANTHROPIC_AUTO_DEFAULTS: dict[str, str] = {
+ "thinking_format": "anthropic",
+ "thinking_replay": "signed",
+ "cache_control": "anthropic",
+ "structured_output": "send",
+ "parallel_tool_calls": "send",
+ "sampling_params": "send",
+ "tool_result_media": "native",
+}
+
+
+def resolve_anthropic_compat(partial: AnthropicCompat) -> ResolvedAnthropicCompat:
+ """Resolve a partial Anthropic compat object into concrete serializer policy."""
+ kwargs: dict[str, object] = {}
+ for field_name, default in _ANTHROPIC_AUTO_DEFAULTS.items():
+ value = getattr(partial, field_name)
+ kwargs[field_name] = default if value in {None, "auto"} else value
+ return ResolvedAnthropicCompat(
+ reasoning_efforts=partial.reasoning_efforts,
+ model_prefixes=partial.model_prefixes,
+ extensions=partial.extensions,
+ **kwargs, # type: ignore[arg-type]
+ )
+
+
+CompatProfile: TypeAlias = OpenAIResponsesCompat | OpenAIChatCompat | AnthropicCompat
+
+
+# ─── Merge helpers ──────────────────────────────────────────────────
+
+
+def merge_openai_responses_compat(
+ base: OpenAIResponsesCompat,
+ override: OpenAIResponsesCompat | None,
+) -> OpenAIResponsesCompat:
+ """Merge partial OpenAI Responses compat objects.
+
+ None fields inherit. Non-None fields, including "auto", override.
+ """
+ if override is None:
+ return base
+
+ kwargs = {}
+ for f in fields(OpenAIResponsesCompat):
+ value = getattr(override, f.name)
+ if f.name == "extensions":
+ kwargs[f.name] = _merge_json_object(base.extensions, override.extensions)
+ else:
+ kwargs[f.name] = getattr(base, f.name) if value is None else value
+ return OpenAIResponsesCompat(**kwargs)
+
+
+def resolve_openai_responses_compat(partial: OpenAIResponsesCompat) -> ResolvedOpenAIResponsesCompat:
+ """Resolve a partial compat object into concrete serializer policy."""
+ developer_role = partial.developer_role
+ if developer_role in {None, "auto"}:
+ developer_role = "developer"
+
+ max_field = partial.max_output_tokens_field
+ if max_field in {None, "auto"}:
+ max_field = "max_output_tokens"
+
+ reasoning_format = partial.reasoning_format
+ if reasoning_format in {None, "auto"}:
+ reasoning_format = "responses_reasoning"
+
+ tool_result_name = partial.tool_result_name
+ if tool_result_name in {None, "auto"}:
+ tool_result_name = "omit"
+
+ strict_tools = partial.strict_tools
+ if strict_tools in {None, "auto"}:
+ strict_tools = "omit"
+
+ cache_control = partial.cache_control
+ if cache_control in {None, "auto"}:
+ cache_control = "openai"
+
+ commentary_phase = partial.commentary_phase
+ if commentary_phase in {None, "auto"}:
+ commentary_phase = "omit"
+
+ edit_image_field = partial.edit_image_field
+ if edit_image_field in {None, "auto"}:
+ edit_image_field = "array"
+
+ builtin_tools = partial.builtin_tools
+ if builtin_tools in {None, "auto"}:
+ builtin_tools = "openai"
+
+ tool_result_media = partial.tool_result_media
+ if tool_result_media in {None, "auto"}:
+ tool_result_media = "native"
+
+ return ResolvedOpenAIResponsesCompat(
+ developer_role=developer_role, # type: ignore[arg-type]
+ max_output_tokens_field=max_field, # type: ignore[arg-type]
+ reasoning_format=reasoning_format, # type: ignore[arg-type]
+ tool_result_name=tool_result_name, # type: ignore[arg-type]
+ strict_tools=strict_tools, # type: ignore[arg-type]
+ cache_control=cache_control, # type: ignore[arg-type]
+ commentary_phase=commentary_phase, # type: ignore[arg-type]
+ edit_image_field=edit_image_field, # type: ignore[arg-type]
+ builtin_tools=builtin_tools, # type: ignore[arg-type]
+ tool_result_media=tool_result_media, # type: ignore[arg-type]
+ routing=partial.routing,
+ extensions=partial.extensions,
+ )
diff --git a/dspy/_vendor/lm15/credentials.py b/dspy/_vendor/lm15/credentials.py
new file mode 100644
index 000000000..120583b58
--- /dev/null
+++ b/dspy/_vendor/lm15/credentials.py
@@ -0,0 +1,190 @@
+"""
+lm15.credentials — a credential is a closed sum, not a string.
+
+spec/auth.md AUTH-2 (amended 2026-09-03, changes/2026-09-03-cloud-hosts.md):
+
+ ApiKey {"kind": "api_key", "value"}
+ BearerToken {"kind": "bearer_token", "value", "expires_at"?}
+ AwsCredentials {"kind": "aws", "access_key_id", "secret_access_key",
+ "session_token"?, "expires_at"?}
+
+A credential *provider* (the AUTH-2 zero-arg callable) returns one of these.
+A plain string anywhere a credential is accepted reads as an ``ApiKey`` —
+the shape every provider used before cloud hosts existed, kept so nothing
+a user wrote breaks. ``expires_at`` is an aware UTC datetime; absent
+means non-expiring.
+
+Secrecy (AUTH-5): reprs never show values; ``to_dict`` is the only way out
+and callers that serialize a credential are the ones sending it on the
+wire or writing a fixture on purpose.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Callable, Literal, Union
+
+__all__ = [
+ "ApiKey",
+ "AwsCredentials",
+ "BearerToken",
+ "CredentialKind",
+ "CredentialValue",
+ "CredentialProvider",
+ "CredentialLike",
+ "coerce_credential",
+ "credential_from_dict",
+ "credential_to_dict",
+ "parse_rfc3339",
+ "format_rfc3339",
+]
+
+CredentialKind = Literal["api_key", "bearer_token", "aws"]
+CREDENTIAL_KINDS: frozenset[str] = frozenset({"api_key", "bearer_token", "aws"})
+
+_EXPIRY_SKEW_SECONDS = 300 # AUTH-3: inside the skew window counts as expired.
+
+
+def parse_rfc3339(value: str) -> datetime:
+ """``2026-09-03T12:00:00Z`` (or an offset) → aware UTC datetime."""
+ text = value.strip()
+ if text.endswith("Z") or text.endswith("z"):
+ text = text[:-1] + "+00:00"
+ parsed = datetime.fromisoformat(text)
+ if parsed.tzinfo is None:
+ parsed = parsed.replace(tzinfo=timezone.utc)
+ return parsed.astimezone(timezone.utc)
+
+
+def format_rfc3339(value: datetime) -> str:
+ """Aware datetime → ``YYYY-MM-DDTHH:MM:SSZ`` (whole seconds, UTC)."""
+ if value.tzinfo is None:
+ value = value.replace(tzinfo=timezone.utc)
+ return value.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _expired(expires_at: datetime | None, now: datetime | None) -> bool:
+ if expires_at is None:
+ return False
+ current = now if now is not None else datetime.now(timezone.utc)
+ return (expires_at - current).total_seconds() <= _EXPIRY_SKEW_SECONDS
+
+
+@dataclass(frozen=True, slots=True)
+class ApiKey:
+ value: str
+
+ kind: Literal["api_key"] = field(default="api_key", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.value, str) or not self.value:
+ raise ValueError("ApiKey.value must be a non-empty string")
+
+ def __repr__(self) -> str: # AUTH-5
+ return "ApiKey(<redacted>)"
+
+ def is_expired(self, now: datetime | None = None) -> bool:
+ return False
+
+
+@dataclass(frozen=True, slots=True)
+class BearerToken:
+ value: str
+ expires_at: datetime | None = None
+
+ kind: Literal["bearer_token"] = field(default="bearer_token", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.value, str) or not self.value:
+ raise ValueError("BearerToken.value must be a non-empty string")
+ if self.expires_at is not None and self.expires_at.tzinfo is None:
+ raise ValueError("BearerToken.expires_at must be timezone-aware")
+
+ def __repr__(self) -> str: # AUTH-5
+ tail = f", expires_at={format_rfc3339(self.expires_at)}" if self.expires_at else ""
+ return f"BearerToken(<redacted>{tail})"
+
+ def is_expired(self, now: datetime | None = None) -> bool:
+ return _expired(self.expires_at, now)
+
+
+@dataclass(frozen=True, slots=True)
+class AwsCredentials:
+ access_key_id: str
+ secret_access_key: str
+ session_token: str | None = None
+ expires_at: datetime | None = None
+
+ kind: Literal["aws"] = field(default="aws", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.access_key_id, str) or not self.access_key_id or not isinstance(self.secret_access_key, str) or not self.secret_access_key:
+ raise ValueError("AwsCredentials needs non-empty string access_key_id and secret_access_key")
+ if self.session_token is not None and (not isinstance(self.session_token, str) or not self.session_token):
+ raise ValueError("AwsCredentials.session_token must be a non-empty string")
+ if self.expires_at is not None and self.expires_at.tzinfo is None:
+ raise ValueError("AwsCredentials.expires_at must be timezone-aware")
+
+ def __repr__(self) -> str: # AUTH-5: the key id is not secret, the rest is.
+ tail = f", expires_at={format_rfc3339(self.expires_at)}" if self.expires_at else ""
+ return f"AwsCredentials(access_key_id={self.access_key_id!r}, <redacted>{tail})"
+
+ def is_expired(self, now: datetime | None = None) -> bool:
+ return _expired(self.expires_at, now)
+
+
+CredentialValue = Union[ApiKey, BearerToken, AwsCredentials]
+CredentialProvider = Callable[[], Union[str, CredentialValue]]
+# What every ``api_key=`` argument accepts: a string, a value, or a provider.
+CredentialLike = Union[str, CredentialValue, CredentialProvider]
+
+
+def coerce_credential(value: str | CredentialValue) -> CredentialValue:
+ """A string reads as an ``ApiKey``; a value passes through."""
+ if isinstance(value, (ApiKey, BearerToken, AwsCredentials)):
+ return value
+ if isinstance(value, str):
+ return ApiKey(value)
+ raise TypeError(f"not a credential: {type(value).__name__}")
+
+
+def credential_to_dict(value: CredentialValue) -> dict:
+ """Canonical JSON (AUTH-2). Absent fields are omitted, never null."""
+ if isinstance(value, ApiKey):
+ return {"kind": "api_key", "value": value.value}
+ if isinstance(value, BearerToken):
+ out = {"kind": "bearer_token", "value": value.value}
+ if value.expires_at is not None:
+ out["expires_at"] = format_rfc3339(value.expires_at)
+ return out
+ if isinstance(value, AwsCredentials):
+ out = {
+ "kind": "aws",
+ "access_key_id": value.access_key_id,
+ "secret_access_key": value.secret_access_key,
+ }
+ if value.session_token is not None:
+ out["session_token"] = value.session_token
+ if value.expires_at is not None:
+ out["expires_at"] = format_rfc3339(value.expires_at)
+ return out
+ raise TypeError(f"not a credential: {type(value).__name__}")
+
+
+def credential_from_dict(data: dict) -> CredentialValue:
+ kind = data.get("kind")
+ expires = parse_rfc3339(str(data["expires_at"])) if data.get("expires_at") is not None else None
+ if kind == "api_key":
+ return ApiKey(data["value"])
+ if kind == "bearer_token":
+ return BearerToken(data["value"], expires_at=expires)
+ if kind == "aws":
+ token = data.get("session_token")
+ return AwsCredentials(
+ access_key_id=data["access_key_id"],
+ secret_access_key=data["secret_access_key"],
+ session_token=token,
+ expires_at=expires,
+ )
+ raise ValueError("unknown credential kind")
diff --git a/dspy/_vendor/lm15/doctor.py b/dspy/_vendor/lm15/doctor.py
new file mode 100644
index 000000000..4081f86b8
--- /dev/null
+++ b/dspy/_vendor/lm15/doctor.py
@@ -0,0 +1,360 @@
+"""
+lm15.doctor — explain how a provider's credential would resolve. No secrets.
+
+:func:`explain_auth` answers "why is my key (not) being used?" without a
+network call and without ever returning secret material. It walks the exact
+chain the router's ``lm()`` walks — explicit ``api_keys`` entry, declared
+environment variables in order, borrowed local CLI credentials for OAuth
+providers, a local server's placeholder key — and reports the state of every
+rung, including rungs that are set but shadowed by an earlier one.
+
+Purity note: both the router's lookup and ``explain_auth`` check
+configured keys and environment presence, so secret values transit process
+memory. Neither invokes credential providers during inspection. The doctor
+also reads local credential files to report stored-login availability.
+They are never stored on the report, never included in ``describe()``, and
+never part of any repr.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from .auth import (
+ CLAUDE_CODE_CREDENTIALS_PATH,
+ CODEX_CLI_AUTH_PATH,
+ LocalOAuthCredential,
+ _load_xai_with_source,
+ _xai_store_paths,
+ read_claude_code_credential,
+ read_codex_cli_credential,
+)
+from .errors import NotConfiguredError
+from .providers import Credential
+from .router import (
+ ADAPTERS,
+ RouterConfig,
+ Resolution,
+ _api_keys_source,
+ _canonical_provider,
+ _credential_policy,
+ _declared_env_keys,
+ _routable,
+)
+
+__all__ = ["AuthReport", "AuthStep", "explain_auth"]
+
+
+@dataclass(frozen=True, slots=True)
+class AuthStep:
+ """One rung of the credential chain.
+
+ ``state`` is one of:
+
+ - ``"selected"`` — this rung supplies the credential;
+ - ``"shadowed"`` — usable, but an earlier rung wins;
+ - ``"absent"`` — nothing here;
+ - ``"unprobed"`` — a network or subprocess rung of a cloud chain whose
+ configuration is present; the offline doctor did not contact it
+ (AUTH-7). It runs before any later ``selected`` rung at request time
+ and may win.
+
+ ``kind`` is the language-neutral source identifier from the contract
+ fixtures (lm15-contract/auth/resolution.json): ``"api_keys"``,
+ ``"env:<VAR>"``, ``"placeholder"``, or ``"oauth-file"``. Conformance
+ compares kinds, never display strings.
+
+ ``detail`` is human text and carries no secret material by construction.
+ """
+
+ kind: str
+ source: str
+ detail: str
+ state: str
+
+ def describe(self) -> str:
+ marker = {"selected": "=> ", "shadowed": " ~ ", "absent": " - ", "unprobed": " ? "}[self.state]
+ return f"{marker}{self.source}: {self.detail}"
+
+
+@dataclass(frozen=True, slots=True)
+class AuthReport:
+ provider: str
+ steps: tuple[AuthStep, ...]
+ configured: bool
+ settings: tuple[tuple[str, str], ...] = () # resolved host settings (AUTH-7: printed by name and value)
+
+ @property
+ def selected(self) -> AuthStep | None:
+ for step in self.steps:
+ if step.state == "selected":
+ return step
+ return None
+
+ def describe(self) -> str:
+ lines = [f"auth for provider {self.provider!r}:"]
+ lines += [f" {step.describe()}" for step in self.steps]
+ unprobed = [step for step in self.steps if step.state == "unprobed"]
+ if self.configured and self.selected is not None:
+ lines.append(f" configured: yes — {self.selected.source}")
+ if unprobed:
+ lines.append(f" note: {', '.join(s.source for s in unprobed)} run first at request time and may win")
+ elif self.configured:
+ lines.append(f" configured: probably — {', '.join(s.source for s in unprobed)} (unprobed offline)")
+ else:
+ lines.append(" configured: no")
+ for name, value in self.settings:
+ lines.append(f" setting {name}: {value}")
+ return "\n".join(lines)
+
+ def __str__(self) -> str:
+ return self.describe()
+
+
+def _expiry_detail(credential: LocalOAuthCredential) -> str:
+ if credential.expires_at is None:
+ return "no recorded expiry"
+ remaining_ms = credential.expires_at - int(time.time() * 1000)
+ if remaining_ms <= 0:
+ suffix = "refresh token present" if credential.refresh_token else "NO refresh token"
+ return f"expired, {suffix}"
+ minutes = remaining_ms // 60_000
+ hours, minutes = divmod(minutes, 60)
+ span = f"{hours}h {minutes:02d}m" if hours else f"{minutes}m"
+ return f"fresh, expires in {span}"
+
+
+def _usable_state(credential: LocalOAuthCredential, detail: str, shadowed: bool) -> str:
+ if "expired" in detail and not credential.refresh_token:
+ return "absent"
+ return "shadowed" if shadowed else "selected"
+
+
+def _oauth_step(provider: str, path_override: str | None) -> AuthStep:
+ if provider == "claude-code":
+ default_path, reader = CLAUDE_CODE_CREDENTIALS_PATH, read_claude_code_credential
+ else:
+ default_path, reader = CODEX_CLI_AUTH_PATH, read_codex_cli_credential
+ path = Path(path_override).expanduser() if path_override else default_path
+ source = f"local OAuth credential {path}"
+ credential = reader(path)
+ if credential is None:
+ return AuthStep(kind="oauth-file", source=source, detail="missing or unreadable", state="absent")
+ detail = _expiry_detail(credential)
+ return AuthStep(kind="oauth-file", source=source, detail=detail, state=_usable_state(credential, detail, shadowed=False))
+
+
+def _xai_oauth_step(path_override: str | None, shadowed: bool) -> AuthStep:
+ """The stored xAI subscription login (lm15's own store, then the Pi
+ agent store) — the middle rung of the oauth-unless-explicit chain:
+ beaten only by an explicit api_keys entry, and itself beating env."""
+ paths = (Path(path_override).expanduser(),) if path_override else _xai_store_paths()
+ try:
+ credential, path = _load_xai_with_source(path_override)
+ except NotConfiguredError:
+ checked = " or ".join(str(p) for p in paths)
+ return AuthStep(kind="oauth-file", source=f"local OAuth credential {checked}", detail="missing or unreadable", state="absent")
+ detail = _expiry_detail(credential)
+ return AuthStep(
+ kind="oauth-file",
+ source=f"local OAuth credential {path}",
+ detail=detail,
+ state=_usable_state(credential, detail, shadowed=shadowed),
+ )
+
+
+def explain_auth(
+ provider: str | Resolution,
+ *,
+ env: Mapping[str, str] | None = None,
+ api_keys: Mapping[str, Credential] | None = None,
+ claude_credentials_path: str | None = None,
+ codex_auth_path: str | None = None,
+ xai_credentials_path: str | None = None,
+ files: Mapping[str, str] | None = None,
+ home: str | None = None,
+ settings: Mapping[str, str] | None = None,
+ config: RouterConfig | None = None,
+) -> AuthReport:
+ """Explain, rung by rung, how ``provider``'s credential resolves.
+
+ Accepts a provider name or a router ``Resolution``. A resolution
+ supplies only the provider identity, not credentials: pass
+ ``config=router.config`` to inspect that router's explicit settings.
+
+ Mirrors the router's construction chain exactly; divergence between this
+ report and ``lm()`` behavior is a bug. ``env`` defaults to
+ ``os.environ`` (pass a mapping for hermetic tests). Never returns or
+ prints secret values, and performs no network I/O.
+
+ ``config`` is the router's own ``RouterConfig`` (``router.config``): its
+ ``env``, ``api_keys`` and the provider's ``settings`` entry are read, so
+ the report describes the router that will send the request. An
+ explicit ``env=``/``api_keys=``/``settings=`` argument wins over the
+ config's field.
+ """
+ import os
+
+ if isinstance(provider, Resolution):
+ provider = provider.provider
+ if not isinstance(provider, str):
+ raise TypeError("provider must be a provider name or Resolution")
+ canonical = _canonical_provider(provider)
+ if config is not None:
+ if env is None:
+ env = config.env
+ if api_keys is None:
+ api_keys = config.api_keys
+ if settings is None and config.settings is not None:
+ settings = config.settings.get(canonical) or config.settings.get(provider)
+ if not _routable(canonical, ADAPTERS):
+ from .registry import PROVIDERS
+
+ known = sorted(PROVIDERS)
+ raise ValueError(f"Unknown provider {provider!r}. Known providers: {', '.join(known)}")
+
+ policy = _credential_policy(canonical)
+ if policy in ("aws-chain", "azure-chain", "gcp-chain") or (
+ _bound_definition(canonical) is not None and _bound_definition(canonical).hosted
+ ):
+ return _explain_cloud(canonical, env=env, api_keys=api_keys, files=files, home=home, settings=settings)
+ if policy == "oauth":
+ override = claude_credentials_path if canonical == "claude-code" else codex_auth_path
+ step = _oauth_step(canonical, override)
+ return AuthReport(provider=canonical, steps=(step,), configured=step.state == "selected")
+
+ config = RouterConfig(env=env, api_keys=api_keys)
+ environment = env if env is not None else os.environ
+ steps: list[AuthStep] = []
+ selected = False
+
+ entry = _api_keys_source(config, canonical)
+ if entry is not None:
+ steps.append(
+ AuthStep(
+ kind="api_keys",
+ source=_entry_source(canonical, entry),
+ detail="provided (value never shown)",
+ state="selected",
+ )
+ )
+ selected = True
+ else:
+ steps.append(
+ AuthStep(
+ kind="api_keys",
+ source="explicit api_keys entry",
+ detail="not provided",
+ state="absent",
+ )
+ )
+
+ if policy == "oauth-unless-explicit":
+ # The stored subscription login outranks env keys (AUTH-1): it
+ # spends no money per token. Only the explicit api_keys entry
+ # above can shadow it.
+ step = _xai_oauth_step(xai_credentials_path, shadowed=selected)
+ steps.append(step)
+ selected = selected or step.state == "selected"
+
+ for key in _declared_env_keys(canonical, ADAPTERS):
+ if environment.get(key):
+ state = "shadowed" if selected else "selected"
+ steps.append(
+ AuthStep(kind=f"env:{key}", source=f"env ${key}", detail="set (value never shown)", state=state)
+ )
+ selected = True
+ else:
+ steps.append(
+ AuthStep(kind=f"env:{key}", source=f"env ${key}", detail="not set", state="absent")
+ )
+
+ from .registry import PROVIDERS
+
+ definition = PROVIDERS.get(canonical)
+ if definition is not None and definition.placeholder_key is not None:
+ state = "shadowed" if selected else "selected"
+ steps.append(
+ AuthStep(
+ kind="placeholder",
+ source="local-server placeholder key",
+ detail=f"preset default for keyless {canonical} servers",
+ state=state,
+ )
+ )
+ selected = True
+
+ return AuthReport(provider=canonical, steps=tuple(steps), configured=selected)
+
+
+def _entry_source(provider: str, entry: str | None) -> str:
+ source = "explicit api_keys entry"
+ if entry is not None and _canonical_provider(entry) != provider:
+ source += f" (via {entry!r}, shared env-key declarations)"
+ return source
+
+
+def _bound_definition(canonical: str):
+ from .registry import PROVIDERS
+
+ return PROVIDERS.get(canonical)
+
+
+def _explain_cloud(
+ canonical: str,
+ *,
+ env: Mapping[str, str] | None,
+ api_keys: Mapping[str, Credential] | None,
+ files: Mapping[str, str] | None,
+ home: str | None,
+ settings: Mapping[str, str] | None,
+) -> AuthReport:
+ """The cloud-chain walk (AUTH-1 aws/azure/gcp chains) through
+ ``lm15.cloud.chains.explain``: offline, files from ``files`` when the
+ harness materialized them, host settings resolved and printed."""
+ import os
+
+ from .cloud.chains import ChainContext, explain, profile_settings
+ from .cloud.hosts import resolve_settings
+
+ definition = _bound_definition(canonical)
+ policy = definition.access
+ environment = env if env is not None else os.environ
+ config = RouterConfig(env=env, api_keys=api_keys)
+ entry = _api_keys_source(config, canonical)
+ has_entry = entry is not None
+ resolved: dict[str, str] = {}
+ setting_error: str | None = None
+ ctx = ChainContext(
+ env=environment,
+ home=Path(home).expanduser() if home else (Path(environment["HOME"]) if environment.get("HOME") else Path.home()),
+ files=files,
+ )
+ try:
+ resolved = resolve_settings(policy.host, settings, environment, provider=canonical, profile=profile_settings(policy, ctx))
+ except NotConfiguredError as exc:
+ setting_error = str(exc).splitlines()[0]
+ ctx.settings = resolved
+ if policy.cloud_chain:
+ steps, configured = explain(policy, ctx, explicit=has_entry)
+ out = [AuthStep(kind=s.kind, source=_entry_source(canonical, entry) if s.kind == "api_keys" else s.source,
+ detail=s.detail, state=s.state) for s in steps]
+ else:
+ # A hosted door with the ordinary key chain (vertex-express).
+ out = [AuthStep("api_keys", _entry_source(canonical, entry),
+ "provided (value never shown)" if has_entry else "not provided",
+ "selected" if has_entry else "absent")]
+ configured = has_entry
+ for key in policy.env_keys:
+ if environment.get(key):
+ out.append(AuthStep(f"env:{key}", f"env ${key}", "set (value never shown)", "shadowed" if configured else "selected"))
+ configured = True
+ else:
+ out.append(AuthStep(f"env:{key}", f"env ${key}", "not set", "absent"))
+ shown = tuple(sorted(resolved.items()))
+ if setting_error:
+ shown = shown + (("error", setting_error),)
+ return AuthReport(provider=canonical, steps=tuple(out), configured=configured, settings=shown)
diff --git a/dspy/_vendor/lm15/errors.py b/dspy/_vendor/lm15/errors.py
new file mode 100644
index 000000000..1bafc5f56
--- /dev/null
+++ b/dspy/_vendor/lm15/errors.py
@@ -0,0 +1,523 @@
+"""
+lm15.errors — Canonical error taxonomy.
+
+Every provider maps its idiosyncratic error shapes onto this hierarchy.
+Error classes are the primary signal; canonical string codes exist for
+serialization and wire formats.
+
+Hierarchy:
+ LM15Error
+ ├── TransportError (network/connection failures at the LM layer)
+ ├── LockTimeoutError (the credential-file lock could not be taken; local, transient)
+ ├── StreamAssemblyError (a stream cannot become a Response without inventing a fact; MAP-9)
+ ├── ConfigurationError (local SDK/configuration failures)
+ │ ├── NotConfiguredError (no API key or required provider config)
+ │ ├── UnknownModelError (the router: a model string that routes nowhere)
+ │ └── AmbiguousModelError (the router: a catalog match under more than one provider)
+ ├── CapabilityError (local provider-adapter capability failures)
+ │ └── UnsupportedFeatureError
+ └── ProviderError (provider returned an error response)
+ ├── AuthError (401/403 — bad or missing API key)
+ ├── BillingError (402 — payment/quota issue)
+ ├── RateLimitError (429 — too many requests)
+ ├── InvalidRequestError (4xx request-shape/resource errors)
+ │ ├── ContextLengthError (input too long for model)
+ │ └── UnsupportedModelError
+ ├── TimeoutError (408/504 — request timed out)
+ └── ServerError (5xx — provider-side failure)
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING: # pragma: no cover
+ from .types import Response
+
+
+class LM15Error(Exception):
+ """Base for all lm15 errors.
+
+ Errors keep the human-readable exception message in ``str(error)`` while
+ also exposing structured metadata for logging, telemetry, retries, and
+ programmatic handling.
+ """
+
+ default_code: str | None = None
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ code: str | None = None,
+ provider: str | None = None,
+ provider_code: str | None = None,
+ status: int | None = None,
+ request_id: str | None = None,
+ retry_after: float | None = None,
+ ) -> None:
+ self.message = message
+ self.code = code or self.default_code
+ self.provider = provider
+ self.provider_code = provider_code
+ self.status = status
+ self.request_id = request_id
+ # Number rule (docs/serde-rules.md): retry_after is float-typed;
+ # same-valued int input (e.g. a Retry-After header of "30") coerces.
+ if type(retry_after) is int:
+ retry_after = float(retry_after)
+ self.retry_after = retry_after
+ super().__init__(message)
+
+
+class TransportError(LM15Error):
+ """High-level LM transport failure.
+
+ Provider LMs wrap lower-level ``lm15.transports.TransportError`` exceptions
+ into this class.
+ """
+
+ default_code = "transport"
+
+
+class LockTimeoutError(LM15Error):
+ """The credential-file lock (spec/auth.md AUTH-4) could not be taken
+ within the timeout: another lm15 process is refreshing the same
+ credential (``lock_timeout``, 2026-09-08).
+
+ Local and transient — a root-level class beside :class:`TransportError`,
+ never a :class:`ProviderError` (no provider was asked) and never an
+ :class:`AuthError` (nothing is wrong with the credential; AUTH-6).
+ Retryable. Carries ``path`` (the guarded file) and ``lock_path``.
+ :class:`lm15.auth.CredentialLockTimeout` is this class and the builtin
+ ``TimeoutError`` at once, so ``except TimeoutError`` keeps working.
+ """
+
+ default_code = "lock_timeout"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ path: str = "",
+ lock_path: str = "",
+ **kwargs,
+ ) -> None:
+ self.path = path
+ self.lock_path = lock_path
+ super().__init__(message, **kwargs)
+
+
+class StreamAssemblyError(LM15Error):
+ """A stream could not be assembled into a Response without inventing a fact.
+
+ Raised by the accumulator (MAP-9) when a tool call's fragments never
+ carried a name: an unnamed call is not actionable (MAP-1), and guessing
+ a name from the request dispatches the wrong function silently. This is
+ an adapter defect, not model behaviour — every shipped dialect names a
+ call on its first fragment — so the message points at the adapter.
+
+ ``partial`` is everything that did assemble (text, thinking, other
+ parts, usage, finish reason) with the unnamed call(s) left out, so a
+ caller that wants to salvage the turn can; ``part_index`` is the first
+ offending part.
+ """
+
+ default_code = "stream_assembly"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ partial: "Response | None" = None,
+ part_index: int | None = None,
+ **kwargs,
+ ) -> None:
+ super().__init__(message, **kwargs)
+ self.partial = partial
+ self.part_index = part_index
+
+
+class ConfigurationError(LM15Error):
+ """Local SDK or provider-adapter configuration failure."""
+
+ default_code = "not_configured"
+
+
+class CapabilityError(LM15Error):
+ """Requested capability is not supported by this provider adapter."""
+
+ default_code = "unsupported_feature"
+
+
+class ProviderError(LM15Error):
+ """The provider returned an error response."""
+
+ default_code = "provider"
+
+ def __str__(self) -> str:
+ # The displayed form carries provider / HTTP status / request id so
+ # a bare relay like "model: x" still says who said it. The
+ # ``message`` FIELD stays untouched (it is what the contract pins).
+ context = ", ".join(
+ item
+ for item in (
+ self.provider,
+ f"HTTP {self.status}" if self.status is not None else None,
+ f"request {self.request_id}" if self.request_id else None,
+ )
+ if item
+ )
+ base = self.message or self.code
+ if not context:
+ return base
+ head, sep, tail = base.partition("\n\n")
+ suffix = f" ({context})"
+ return f"{head}{suffix}\n\n{tail}" if sep else f"{base}{suffix}"
+
+
+class AuthError(ProviderError):
+ """Authentication failed — invalid, expired, or missing API key."""
+
+ default_code = "auth"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ provider: str | None = None,
+ env_keys: tuple[str, ...] = (),
+ credential_hint: str | None = None,
+ **kwargs,
+ ) -> None:
+ if provider is not None:
+ kwargs.setdefault("provider", provider)
+ provider_name = provider or kwargs.get("provider")
+ self.env_keys = tuple(env_keys)
+ self.credential_hint = credential_hint
+
+ if credential_hint:
+ # Subscription/OAuth adapters: guidance is how to re-login, not
+ # which env var to set (there is none).
+ guidance = f"\n\n To fix:\n - {credential_hint}\n"
+ else:
+ guidance = (
+ "\n\n"
+ " To fix:\n"
+ " - Check that your API key is correct and not expired\n"
+ )
+ if self.env_keys:
+ keys = " or ".join(f"{key}=..." for key in self.env_keys)
+ guidance += f" - Set the provider API key in your environment: {keys}\n"
+ else:
+ guidance += " - Set the provider API key in your environment\n"
+ if provider_name:
+ guidance += f" - Verify your {provider_name} account/project has access\n"
+
+ super().__init__(_append_guidance(message, guidance), **kwargs)
+
+
+class RateLimitError(ProviderError):
+ """Rate limited by the provider (HTTP 429)."""
+
+ default_code = "rate_limit"
+
+ def __init__(self, message: str = "", **kwargs) -> None:
+ guidance = (
+ "\n\n"
+ " To fix:\n"
+ " - Wait a moment and retry\n"
+ " - Retry with backoff in your application layer (lm15 never retries for you)\n"
+ " - Reduce request rate or upgrade your API plan\n"
+ )
+ super().__init__(_append_guidance(message, guidance), **kwargs)
+
+
+class BillingError(ProviderError):
+ """402 — billing or payment issue."""
+
+ default_code = "billing"
+
+
+class TimeoutError(ProviderError, builtins.TimeoutError):
+ """Provider request timed out.
+
+ Also subclasses the builtin ``TimeoutError`` so a user's bare
+ ``except TimeoutError:`` catches lm15 timeouts. ``ProviderError`` comes
+ first in the MRO, so lm15 metadata (``code``, ``status``, ...) wins.
+ """
+
+ default_code = "timeout"
+
+
+# Descriptive alias that avoids shadowing Python's built-in TimeoutError in new code.
+RequestTimeoutError = TimeoutError
+
+
+class InvalidRequestError(ProviderError):
+ """Bad request shape or invalid provider resource (4xx)."""
+
+ default_code = "invalid_request"
+
+
+class ContextLengthError(InvalidRequestError):
+ """The input exceeds the model's context window."""
+
+ default_code = "context_length"
+
+ def __init__(self, message: str = "", **kwargs) -> None:
+ guidance = (
+ "\n\n"
+ " To fix:\n"
+ " - Reduce the prompt or system prompt length\n"
+ " - Clear conversation history\n"
+ " - Use a model with a larger context window\n"
+ " - Lower max_tokens to leave more room for input\n"
+ )
+ super().__init__(_append_guidance(message, guidance), **kwargs)
+
+
+class UnsupportedModelError(InvalidRequestError):
+ """Model not found, unavailable, or unsupported by the provider."""
+
+ default_code = "unsupported_model"
+
+
+class ServerError(ProviderError):
+ """Provider-side failure (5xx)."""
+
+ default_code = "server"
+
+
+class UnsupportedFeatureError(CapabilityError):
+ """Feature not supported by this provider adapter."""
+
+ default_code = "unsupported_feature"
+
+
+class NotConfiguredError(ConfigurationError):
+ """No API key or required provider configuration was found."""
+
+ default_code = "not_configured"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ provider: str | None = None,
+ env_keys: tuple[str, ...] = (),
+ credential_hint: str | None = None,
+ **kwargs,
+ ) -> None:
+ if provider is not None:
+ kwargs.setdefault("provider", provider)
+ provider_name = provider or kwargs.get("provider")
+ self.env_keys = tuple(env_keys)
+ self.credential_hint = credential_hint
+
+ guidance = ""
+ if credential_hint:
+ guidance = f"\n\n To fix:\n - {credential_hint}\n"
+ elif self.env_keys or provider_name:
+ guidance = "\n\n To fix:\n"
+ if self.env_keys:
+ keys = " or ".join(f"{key}=..." for key in self.env_keys)
+ guidance += f" - Set the provider API key in your environment: {keys}\n"
+ if provider_name:
+ guidance += f" - Configure credentials for {provider_name}\n"
+
+ message = _append_guidance(message, guidance) if guidance else message
+ super().__init__(message, **kwargs)
+
+
+class UnknownModelError(ConfigurationError):
+ """The router found no provider for a model string.
+
+ No routable provider prefix, no catalog match, and no rule matched
+ (spec/vocabularies.md ``unknown_model``, 2026-09-08). Local and
+ pre-network: no provider was asked — a provider's own "no such model"
+ reply is :class:`UnsupportedModelError`. Carries ``model`` (the string
+ as requested); ``rules_tried`` and ``catalog_searched`` are the
+ reference's diagnostics, not contract payload.
+ """
+
+ default_code = "unknown_model"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ model: str = "",
+ rules_tried: tuple = (),
+ catalog_searched: bool = False,
+ **kwargs,
+ ) -> None:
+ self.model = model
+ self.rules_tried = tuple(rules_tried)
+ self.catalog_searched = catalog_searched
+ super().__init__(message, **kwargs)
+
+
+class AmbiguousModelError(ConfigurationError):
+ """The catalog matched a model string under more than one provider, or
+ under more than one entry of one provider (``ambiguous_model``,
+ 2026-09-08). The fix is an explicit ``provider:`` prefix. Carries
+ ``model`` and ``providers`` (every candidate, catalog order,
+ deduplicated).
+ """
+
+ default_code = "ambiguous_model"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ model: str = "",
+ providers: tuple[str, ...] = (),
+ **kwargs,
+ ) -> None:
+ self.model = model
+ self.providers = tuple(providers)
+ self.candidates = self.providers # alias: full candidate list
+ super().__init__(message, **kwargs)
+
+
+_GUIDANCE_MARKER = "\n\n To fix:"
+
+
+def with_credential_hint(error: ProviderError, hint: str) -> ProviderError:
+ """Rewrite an AuthError's guidance for subscription (OAuth) adapters.
+
+ API-key adapters point at env vars; subscription adapters have no env
+ var — the fix is re-running the provider CLI login. Non-auth errors pass
+ through unchanged.
+ """
+ if not isinstance(error, AuthError):
+ return error
+ base = error.message.split(_GUIDANCE_MARKER, 1)[0]
+ return AuthError(
+ base,
+ provider=error.provider,
+ credential_hint=hint,
+ provider_code=error.provider_code,
+ status=error.status,
+ request_id=error.request_id,
+ retry_after=error.retry_after,
+ )
+
+
+# ─── HTTP status → error class mapping ───────────────────────────────
+
+def map_http_error(
+ status: int,
+ message: str,
+ *,
+ provider: str | None = None,
+ env_keys: tuple[str, ...] = (),
+ provider_code: str | None = None,
+ request_id: str | None = None,
+ retry_after: float | None = None,
+) -> ProviderError:
+ """Map HTTP status + message to a typed ProviderError.
+
+ Provider LMs extract the human-readable message and provider-specific code
+ from the provider's error body in their ``normalize_error`` override. This
+ function only maps HTTP status codes.
+ """
+ kwargs = _metadata_kwargs(
+ provider=provider,
+ provider_code=provider_code,
+ status=status,
+ request_id=request_id,
+ retry_after=retry_after,
+ )
+ if status in (401, 403):
+ return AuthError(message, env_keys=env_keys, **kwargs)
+ if status == 402:
+ return BillingError(message, **kwargs)
+ if status in (408, 504):
+ return TimeoutError(message, **kwargs)
+ if status == 429:
+ return RateLimitError(message, **kwargs)
+ if status in (400, 404, 409, 413, 422):
+ return InvalidRequestError(message, **kwargs)
+ if 500 <= status <= 599:
+ return ServerError(message, **kwargs)
+ return ProviderError(message, **kwargs)
+
+
+# ─── Canonical error codes ───────────────────────────────────────────
+
+# Bidirectional mapping between error classes and string codes.
+# Codes are provider-agnostic and stable across LMs. More-specific classes must
+# appear before their base classes.
+
+_CLASS_TO_CODE: dict[type[LM15Error], str] = {
+ ContextLengthError: "context_length",
+ UnsupportedModelError: "unsupported_model",
+ AuthError: "auth",
+ BillingError: "billing",
+ RateLimitError: "rate_limit",
+ InvalidRequestError: "invalid_request",
+ TimeoutError: "timeout",
+ ServerError: "server",
+ UnsupportedFeatureError: "unsupported_feature",
+ NotConfiguredError: "not_configured",
+ UnknownModelError: "unknown_model",
+ AmbiguousModelError: "ambiguous_model",
+ TransportError: "transport",
+ LockTimeoutError: "lock_timeout",
+ ProviderError: "provider",
+}
+
+_CODE_TO_CLASS: dict[str, type[LM15Error]] = {v: k for k, v in _CLASS_TO_CODE.items()}
+
+
+def canonical_error_code(error: type[LM15Error] | LM15Error) -> str:
+ """Return the canonical string code for an error class or instance."""
+ cls = error if isinstance(error, type) else type(error)
+ for check_cls, code in _CLASS_TO_CODE.items():
+ if issubclass(cls, check_cls):
+ return code
+ default_code = getattr(cls, "default_code", None)
+ return default_code or "provider"
+
+
+def error_class_for_code(code: str) -> type[LM15Error]:
+ """Return the LM15Error subclass for a canonical string code."""
+ return _CODE_TO_CLASS.get(code, ProviderError)
+
+
+# Errors that are safe to retry; lm15 never retries itself — this
+# classification is data for the caller's own retry policy.
+RETRYABLE_ERRORS = (RateLimitError, TimeoutError, ServerError, TransportError, LockTimeoutError)
+
+
+def _append_guidance(message: str, guidance: str) -> str:
+ """Append guidance once while preserving the original provider message."""
+ if guidance.strip() in message:
+ return message
+ return message.rstrip() + guidance
+
+
+def _metadata_kwargs(
+ *,
+ provider: str | None = None,
+ provider_code: str | None = None,
+ status: int | None = None,
+ request_id: str | None = None,
+ retry_after: float | None = None,
+) -> dict[str, object]:
+ kwargs: dict[str, object] = {}
+ if provider:
+ kwargs["provider"] = provider
+ if provider_code:
+ kwargs["provider_code"] = provider_code
+ if status is not None:
+ kwargs["status"] = status
+ if request_id:
+ kwargs["request_id"] = request_id
+ if retry_after is not None:
+ kwargs["retry_after"] = retry_after
+ return kwargs
diff --git a/dspy/_vendor/lm15/features.py b/dspy/_vendor/lm15/features.py
new file mode 100644
index 000000000..0c012d788
--- /dev/null
+++ b/dspy/_vendor/lm15/features.py
@@ -0,0 +1,316 @@
+"""
+lm15.features — Provider capability and endpoint declarations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Literal, Mapping
+
+# How a provider's credential is obtained (spec/auth.md AUTH-1):
+#
+# - "key" — the ordinary chain: explicit api_keys entry, then the declared
+# env vars in order, then (local-server presets only) the
+# preset's placeholder key.
+# - "oauth" — self-resolving local OAuth only. The adapter reads a local
+# credential file; the chain above never runs and a failed OAuth
+# load never falls back to an env var.
+# - "oauth-unless-explicit" — an explicit api_keys entry wins; otherwise a
+# usable stored OAuth login wins; env vars are consulted only
+# when no usable login is stored. Rationale: deliberate
+# in-process configuration always wins, but between two kinds of
+# stored state — a subscription login and an ambient env var —
+# the subscription wins because it spends no money per token
+# (lm15's durable constraint: normal inference must not
+# unexpectedly spend money). Stated trade-off: with a login
+# stored, a set env key is silently ignored; pass the key
+# explicitly to force it. Adapters declaring this policy MUST
+# expose ``has_stored_credential()`` — an offline, classmethod
+# probe the router calls to decide the chain.
+#
+# The router and doctor derive their behavior from this declaration; there
+# is no parallel provider-name list to keep in sync.
+# - "aws-chain" / "azure-chain" / "gcp-chain" — the cloud SDK's own default
+# resolution order (spec/auth.md AUTH-1, amended 2026-09-03),
+# rung by rung in ``lm15.cloud.chains``. Rung 0 is the explicit
+# api_keys entry; the door's own key variable is rung 1; then
+# the SDK chain. Same principal as boto3 / azure-identity /
+# google-auth on the same machine — anything else is a security
+# bug, not a convenience gap.
+CredentialPolicy = Literal["key", "oauth", "oauth-unless-explicit", "aws-chain", "azure-chain", "gcp-chain"]
+CREDENTIAL_POLICIES: frozenset[str] = frozenset(
+ {"key", "oauth", "oauth-unless-explicit", "aws-chain", "azure-chain", "gcp-chain"}
+)
+_CLOUD_CHAINS: frozenset[str] = frozenset({"aws-chain", "azure-chain", "gcp-chain"})
+
+# spec/auth.md AUTH-11: the mechanisms a cloud chain is made of. A chain
+# is data over these; a new kind is a spec change.
+RungKind = Literal[
+ "env", "ini-profile", "json-file", "subprocess", "http-metadata",
+ "http-token-exchange", "sigv4-sts", "unsigned-sts", "jwt-rs256", "file-cache",
+]
+RUNG_KINDS: frozenset[str] = frozenset({
+ "env", "ini-profile", "json-file", "subprocess", "http-metadata",
+ "http-token-exchange", "sigv4-sts", "unsigned-sts", "jwt-rs256", "file-cache",
+})
+
+# spec/auth.md AUTH-7: what the doctor says about a rung.
+AuthStepState = Literal["selected", "shadowed", "absent", "unprobed"]
+AUTH_STEP_STATES: frozenset[str] = frozenset({"selected", "shadowed", "absent", "unprobed"})
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointSupport:
+ complete: bool = True
+ stream: bool = True
+ live: bool = False
+ files: bool = False
+ batches: bool = False
+ images: bool = False
+ speech: bool = False
+ video: bool = False
+ responses_api: bool = False
+ models: bool = False
+ caches: bool = False
+
+ # Escape hatch for endpoint names not yet promoted to typed booleans.
+ extra: frozenset[str] = field(default_factory=frozenset)
+
+ def supports_endpoint(self, name: str) -> bool:
+ if name in self.extra:
+ return True
+ return bool(getattr(self, name, False))
+
+
+# How a credential travels (spec/vocabularies.md AuthScheme, AUTH-10). A
+# policy lists the schemes its door accepts, in preference order; the
+# credential KIND picks one: an ApiKey goes out under the first header
+# scheme, AwsCredentials under ``sigv4``.
+AuthScheme = Literal["bearer", "x-api-key", "api-key", "query-key", "sigv4"]
+AUTH_SCHEMES: frozenset[str] = frozenset({"bearer", "x-api-key", "api-key", "query-key", "sigv4"})
+# The earlier two-value name, kept for callers that spelled the header.
+AuthHeader = Literal["bearer", "x-api-key"]
+
+StreamFraming = Literal["sse", "aws-event-stream"]
+STREAM_FRAMINGS: frozenset[str] = frozenset({"sse", "aws-event-stream"})
+ModelPlacement = Literal["body", "path"]
+MODEL_PLACEMENTS: frozenset[str] = frozenset({"body", "path"})
+
+
+@dataclass(frozen=True, slots=True)
+class HostSetting:
+ """One host setting: its name, the env variables consulted in order when
+ the caller did not pass it, and its default (``None`` = required)."""
+
+ name: str
+ env: tuple[str, ...] = ()
+ default: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class HostSpec:
+ """How a dialect reaches a cloud door (spec/auth.md AUTH-10 ``host``).
+
+ ``base_url`` template over the settings: ``{region}``,
+ ``{project}``, ``{location}``, ``{location_host}``
+ (derived from ``location``), ``{resource}``.
+ ``settings`` the settings this host needs, with env fallbacks.
+ ``paths`` endpoint-path overrides keyed by the dialect's
+ endpoint name (``messages``, ``messages/stream``);
+ ``{model}`` is the request's model. Absent means
+ the dialect's own path under ``base_url``.
+ ``model_in`` ``body`` (default) or ``path`` — when ``path``,
+ the model field is removed from the payload.
+ ``anthropic_version_in`` ``header`` (default) or ``body:<value>``.
+ ``stream_framing`` ``sse`` or ``aws-event-stream``.
+ ``required_headers`` ``(header name, setting name)`` pairs sent on every
+ request from the resolved settings.
+ ``sigv4_service`` the SigV4 credential-scope service name.
+ """
+
+ base_url: str
+ settings: tuple[HostSetting, ...] = ()
+ paths: Mapping[str, str] = field(default_factory=dict)
+ model_in: ModelPlacement = "body"
+ anthropic_version_in: str = "header"
+ stream_framing: StreamFraming = "sse"
+ required_headers: tuple[tuple[str, str], ...] = ()
+ sigv4_service: str | None = None
+
+ def __post_init__(self) -> None:
+ if self.model_in not in MODEL_PLACEMENTS:
+ raise ValueError(f"HostSpec.model_in {self.model_in!r} not in {sorted(MODEL_PLACEMENTS)}")
+ if self.stream_framing not in STREAM_FRAMINGS:
+ raise ValueError(f"HostSpec.stream_framing {self.stream_framing!r} not in {sorted(STREAM_FRAMINGS)}")
+ if self.anthropic_version_in != "header" and not self.anthropic_version_in.startswith("body:"):
+ raise ValueError("HostSpec.anthropic_version_in is 'header' or 'body:<value>'")
+ object.__setattr__(self, "settings", tuple(self.settings))
+ object.__setattr__(self, "paths", dict(self.paths))
+ object.__setattr__(self, "required_headers", tuple((str(k), str(v)) for k, v in self.required_headers))
+
+ @property
+ def setting_names(self) -> tuple[str, ...]:
+ return tuple(s.name for s in self.settings)
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class AccessPolicy:
+ """How an adapter reaches a backend. Pure data; ports copy it as a table.
+
+ See ``lm15.access`` for the table of policies and the rationale
+ (spec/auth.md AUTH-9).
+
+ The constructor retains the original positional ``auth_header`` slot.
+ Omitted (``None``), it leaves ``auth_scheme`` unchanged; explicitly supplied,
+ it replaces the schemes with that single header, including in ``replace``.
+ ``auth_scheme`` and ``host`` are keyword-only.
+
+ ``provider`` canonical provider string (errors, routing, doctor).
+ ``supports`` endpoint surfaces this access path carries; a
+ dialect that implements a surface still RAISES when
+ the policy does not carry it (a subscription token
+ has no files or batch).
+ ``credential_policy`` spec/auth.md AUTH-1: key | oauth |
+ oauth-unless-explicit.
+ ``auth_modes``, ``env_keys``, ``enterprise_variants``: as before
+ (support-matrix pinned).
+ ``auth_scheme`` the schemes this door accepts, in preference order
+ (``bearer``, ``x-api-key``, ``api-key``,
+ ``query-key``, ``sigv4``); the credential kind
+ selects one. ``auth_header`` is the first header
+ scheme, kept for the dialects that spell it.
+ ``host`` the cloud door (``HostSpec``), or None for the
+ dialect's public API.
+ ``headers`` static headers on every request, in order. A header
+ the dialect also sets is merged by the dialect's
+ stated rule (Anthropic joins ``anthropic-beta``).
+ ``login_hint`` appended to auth errors when the credential is a
+ local login and there is no env var to set.
+ ``backend`` dialect-consulted variant name; ``"api"`` is the
+ provider's public API.
+ ``backend_options`` string knobs the backend variant needs (the Codex
+ models endpoint wants a ``client_version``).
+ ``system_prefix`` text the backend requires first in the system
+ prompt / instructions (Claude Code, Codex).
+ ``base_url`` this access path's default base URL, when it is
+ not the dialect's.
+ """
+
+ provider: str
+ supports: EndpointSupport = field(default_factory=EndpointSupport)
+ auth_modes: tuple[str, ...] = field(default_factory=tuple)
+ enterprise_variants: tuple[str, ...] = field(default_factory=tuple)
+ env_keys: tuple[str, ...] = field(default_factory=tuple)
+ credential_policy: CredentialPolicy = "key"
+ auth_scheme: tuple[AuthScheme, ...] = field(default=("bearer",), kw_only=True)
+ headers: tuple[tuple[str, str], ...] = ()
+ host: HostSpec | None = field(default=None, kw_only=True)
+ login_hint: str | None = None
+ backend: str = "api"
+ backend_options: Mapping[str, str] = field(default_factory=dict)
+ system_prefix: str | None = None
+ base_url: str | None = None
+
+ # Keep the original positional API, including pattern matching. The legacy
+ # header is a constructor input/property, NOT a second stored authority.
+ __match_args__ = (
+ "provider", "supports", "auth_modes", "enterprise_variants", "env_keys",
+ "credential_policy", "auth_header", "headers", "login_hint", "backend",
+ "backend_options", "system_prefix", "base_url",
+ )
+
+ def __init__(
+ self,
+ provider: str,
+ supports: EndpointSupport | None = None,
+ auth_modes: tuple[str, ...] = (),
+ enterprise_variants: tuple[str, ...] = (),
+ env_keys: tuple[str, ...] = (),
+ credential_policy: CredentialPolicy = "key",
+ auth_header: AuthHeader | None = None,
+ headers: tuple[tuple[str, str], ...] = (),
+ login_hint: str | None = None,
+ backend: str = "api",
+ backend_options: Mapping[str, str] | None = None,
+ system_prefix: str | None = None,
+ base_url: str | None = None,
+ *,
+ auth_scheme: tuple[AuthScheme, ...] = ("bearer",),
+ host: HostSpec | None = None,
+ ) -> None:
+ # None means the legacy spelling was omitted (the effective default
+ # remains bearer). An explicit legacy header overrides the scheme input:
+ # replace(policy, auth_header=...) also supplies the stored auth_scheme.
+ # Keeping auth_header out of dataclass fields means ordinary replace and
+ # with_headers never feed its lossy projection back into auth_scheme.
+ if auth_header is not None:
+ if auth_header not in ("bearer", "x-api-key"):
+ raise ValueError(f"{provider}: unknown auth_header {auth_header!r}")
+ auth_scheme = (auth_header,)
+ object.__setattr__(self, "provider", provider)
+ object.__setattr__(self, "supports", EndpointSupport() if supports is None else supports)
+ object.__setattr__(self, "auth_modes", auth_modes)
+ object.__setattr__(self, "enterprise_variants", enterprise_variants)
+ object.__setattr__(self, "env_keys", env_keys)
+ object.__setattr__(self, "credential_policy", credential_policy)
+ object.__setattr__(self, "auth_scheme", auth_scheme)
+ object.__setattr__(self, "headers", headers)
+ object.__setattr__(self, "host", host)
+ object.__setattr__(self, "login_hint", login_hint)
+ object.__setattr__(self, "backend", backend)
+ object.__setattr__(self, "backend_options", {} if backend_options is None else backend_options)
+ object.__setattr__(self, "system_prefix", system_prefix)
+ object.__setattr__(self, "base_url", base_url)
+ self.__post_init__()
+
+ def __post_init__(self) -> None:
+ if not self.provider:
+ raise ValueError("AccessPolicy.provider must be non-empty")
+ if self.credential_policy == "oauth" and self.env_keys:
+ # AUTH-1: an oauth manifest declares no environment keys.
+ raise ValueError(f"{self.provider}: an 'oauth' access policy declares no env_keys")
+ if self.credential_policy not in CREDENTIAL_POLICIES:
+ raise ValueError(f"{self.provider}: unknown credential_policy {self.credential_policy!r}")
+ schemes = (self.auth_scheme,) if isinstance(self.auth_scheme, str) else tuple(self.auth_scheme)
+ if not schemes:
+ raise ValueError(f"{self.provider}: auth_scheme must name at least one scheme")
+ for scheme in schemes:
+ if scheme not in AUTH_SCHEMES:
+ raise ValueError(f"{self.provider}: unknown auth_scheme {scheme!r}")
+ if "sigv4" in schemes and (self.host is None or self.host.sigv4_service is None):
+ raise ValueError(f"{self.provider}: sigv4 needs a host with sigv4_service")
+ if self.credential_policy in _CLOUD_CHAINS and self.host is None and self.provider != "vertex-express":
+ raise ValueError(f"{self.provider}: a cloud chain policy needs a host")
+ object.__setattr__(self, "auth_scheme", schemes)
+ object.__setattr__(self, "auth_modes", tuple(self.auth_modes))
+ object.__setattr__(self, "env_keys", tuple(self.env_keys))
+ object.__setattr__(self, "enterprise_variants", tuple(self.enterprise_variants))
+ object.__setattr__(self, "headers", tuple((str(k), str(v)) for k, v in self.headers))
+ object.__setattr__(self, "backend_options", dict(self.backend_options))
+
+ @property
+ def auth_header(self) -> AuthHeader:
+ """The first header-carrying scheme (``bearer`` or ``x-api-key``);
+ the two-value spelling the dialects consult for an ``ApiKey``.
+ ``api-key`` reports as ``x-api-key`` here — dialects that can send
+ either read ``auth_scheme`` directly."""
+ for scheme in self.auth_scheme:
+ if scheme == "bearer":
+ return "bearer"
+ if scheme in ("x-api-key", "api-key"):
+ return "x-api-key"
+ return "bearer"
+
+ @property
+ def cloud_chain(self) -> bool:
+ return self.credential_policy in _CLOUD_CHAINS
+
+ def with_headers(self, headers: Mapping[str, str]) -> "AccessPolicy":
+ """A copy with these static headers replaced or appended (names compared case-insensitively)."""
+ lowered = {k.lower() for k in headers}
+ kept = tuple((k, v) for k, v in self.headers if k.lower() not in lowered)
+ return replace(self, headers=kept + tuple(headers.items()))
+
+
+# The earlier name: an adapter's manifest is its access policy.
+ProviderManifest = AccessPolicy
diff --git a/dspy/_vendor/lm15/live.py b/dspy/_vendor/lm15/live.py
new file mode 100644
index 000000000..41af1104d
--- /dev/null
+++ b/dspy/_vendor/lm15/live.py
@@ -0,0 +1,537 @@
+"""
+lm15.live — WebSocket live session wrapper.
+
+Provider-agnostic session around a WebSocket connection for realtime
+(live) interactions with foundation models.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import threading
+from collections import deque
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Callable, Deque
+
+from .types import (
+ ErrorDetail,
+ LiveClientAudioEvent,
+ LiveClientEndAudioEvent,
+ LiveClientEvent,
+ LiveClientImageEvent,
+ LiveClientInterruptEvent,
+ LiveClientTextEvent,
+ LiveClientToolResultEvent,
+ LiveClientTurnEvent,
+ LiveServerEvent,
+ PART_CLASSES,
+ Part,
+ PartInput,
+ TextPart,
+ ToolCallInfo,
+ Usage,
+ _normalize_parts,
+)
+
+EncodeEventFn = Callable[[LiveClientEvent], list[dict[str, Any]]]
+DecodeEventFn = Callable[[str | bytes], list[LiveServerEvent]]
+
+
+def require_websocket_sync_connect():
+ """Return `websockets.sync.client.connect` or raise a helpful ImportError."""
+ try:
+ from websockets.sync.client import connect # type: ignore
+ except Exception as exc:
+ raise ImportError(
+ "Live sessions require the optional 'websockets' dependency.\n\n"
+ " Install it with:\n"
+ " pip install lm15[live]\n"
+ ) from exc
+ return connect
+
+
+def require_websocket_async_connect():
+ """Return `websockets.asyncio.client.connect` or raise a helpful ImportError."""
+ try:
+ from websockets.asyncio.client import connect # type: ignore
+ except Exception as exc:
+ raise ImportError(
+ "Live sessions require the optional 'websockets' dependency.\n\n"
+ " Install it with:\n"
+ " pip install lm15[live]\n"
+ ) from exc
+ return connect
+
+
+# ─── Turn: half-duplex ergonomics over the event stream ─────────────
+#
+# A live session is FULL-duplex: with voice-activity detection the model
+# can speak spontaneously and turns can overlap after interruptions.
+# Plain session iteration is the primary surface for that. `turn()` and
+# `Turn` serve the half-duplex idiom (send, then listen until the turn
+# ends) — the shape every scripted recipe and turn-based voice app has.
+# They are per-language ergonomics like BatchJob, not canonical wire
+# types: ports choose their own idiom; the transcript harness pins the
+# event stream, not this sugar.
+
+_TURN_TERMINAL = frozenset({"turn_end", "interrupted", "error"})
+
+
+@dataclass(frozen=True)
+class Turn:
+ """One materialized turn.
+
+ ``ended_by`` is one of ``turn_end`` / ``interrupted`` / ``error`` /
+ ``tool_call``. ``usage`` is the field-wise sum of every ``usage`` and
+ ``turn_end`` event the turn saw: a tool-call response's tokens arrive
+ as a ``usage`` event at the start of the continuation turn, and a
+ cancelled response's tokens precede its ``interrupted``. A ``tool_call`` ending mirrors the non-live
+ ``finish_reason="tool_call"`` contract: the model is waiting for
+ YOUR result — answer with ``send_tool_result()`` and materialize the
+ next turn. Materializing buffers text and audio in memory until the
+ turn ends; for latency-sensitive playback iterate events instead.
+ """
+
+ ended_by: str
+ text: str = ""
+ audio: bytes = b""
+ audio_media_type: str | None = None
+ tool_calls: tuple[ToolCallInfo, ...] = ()
+ usage: "Usage | None" = None
+ error: "ErrorDetail | None" = None
+ events: tuple[LiveServerEvent, ...] = ()
+
+ @property
+ def ok(self) -> bool:
+ return self.ended_by == "turn_end"
+
+
+def _sum_usage(acc: "Usage | None", more: Usage) -> Usage:
+ """Field-wise sum of two Usage values from one session (same provider,
+ same taxonomy). INV-029: a counter absent on either side is unknown
+ in the sum, never zero."""
+ if acc is None:
+ return more
+ fields = ("input_tokens", "output_tokens", "total_tokens", "cache_read_tokens", "cache_write_tokens",
+ "reasoning_tokens", "input_audio_tokens", "output_audio_tokens")
+ values = {}
+ for name in fields:
+ a, b = getattr(acc, name), getattr(more, name)
+ values[name] = a + b if a is not None and b is not None else None
+ return Usage(**values)
+
+
+def _materialize_turn(events: tuple[LiveServerEvent, ...]) -> Turn:
+ text_parts: list[str] = []
+ audio = bytearray()
+ audio_media_type: str | None = None
+ tool_calls: list[ToolCallInfo] = []
+ usage: Usage | None = None
+ error: ErrorDetail | None = None
+ for event in events:
+ if event.type == "text":
+ text_parts.append(event.text)
+ elif event.type == "audio":
+ audio.extend(base64.b64decode(event.data))
+ if audio_media_type is None and event.media_type is not None:
+ audio_media_type = event.media_type
+ elif event.type == "tool_call":
+ tool_calls.append(ToolCallInfo(id=event.id, name=event.name, input=event.input))
+ elif event.type in ("turn_end", "usage"):
+ # A turn's bill is every usage-bearing event it saw: the
+ # usage event of a tool-call response (which arrives after the
+ # tool_call that ended the previous result(), i.e. at the start
+ # of the continuation turn — the semantic turn stayed open) and
+ # the usage of a cancelled response before its interrupted.
+ usage = _sum_usage(usage, event.usage)
+ elif event.type == "error":
+ error = event.error
+ ended_by = events[-1].type if events and events[-1].type in (_TURN_TERMINAL | {"tool_call"}) else "error"
+ return Turn(
+ ended_by=ended_by,
+ text="".join(text_parts),
+ audio=bytes(audio),
+ audio_media_type=audio_media_type,
+ tool_calls=tuple(tool_calls),
+ usage=usage,
+ error=error,
+ events=events,
+ )
+
+
+class TurnView:
+ """Iterator over one turn's server events.
+
+ Ends itself after yielding the terminal event (``turn_end`` /
+ ``interrupted`` / ``error``) — the same self-ending idiom as
+ ``stream()``. Tool calls are yielded mid-iteration (you hold the
+ session, so you can answer and keep iterating); ``result()`` cannot
+ answer for you, so it returns at a ``tool_call`` instead of
+ deadlocking against a model that is waiting for your result.
+ """
+
+ def __init__(self, session: Any) -> None:
+ self._session = session
+ self._done = False
+
+ def __iter__(self):
+ return self
+
+ def __next__(self) -> LiveServerEvent:
+ if self._done:
+ raise StopIteration
+ event = self._session.recv()
+ if event.type in _TURN_TERMINAL:
+ self._done = True
+ return event
+
+ def result(self) -> Turn:
+ events: list[LiveServerEvent] = []
+ for event in self:
+ events.append(event)
+ if event.type == "tool_call":
+ break
+ return _materialize_turn(tuple(events))
+
+
+class AsyncTurnView:
+ """Async twin of :class:`TurnView`."""
+
+ def __init__(self, session: Any) -> None:
+ self._session = session
+ self._done = False
+
+ def __aiter__(self):
+ return self
+
+ async def __anext__(self) -> LiveServerEvent:
+ if self._done:
+ raise StopAsyncIteration
+ event = await self._session.recv()
+ if event.type in _TURN_TERMINAL:
+ self._done = True
+ return event
+
+ async def result(self) -> Turn:
+ events: list[LiveServerEvent] = []
+ async for event in self:
+ events.append(event)
+ if event.type == "tool_call":
+ break
+ return _materialize_turn(tuple(events))
+
+
+class WebSocketLiveSession:
+ """Provider-agnostic session wrapper around a WebSocket connection."""
+
+ def __init__(
+ self,
+ *,
+ ws: Any,
+ encode_event: EncodeEventFn,
+ decode_event: DecodeEventFn,
+ ) -> None:
+ self._ws = ws
+ self._encode_event = encode_event
+ self._decode_event = decode_event
+ self._pending: Deque[LiveServerEvent] = deque()
+ self._send_lock = threading.Lock()
+ self._closed = False
+
+ def send(
+ self,
+ event: LiveClientEvent | None = None,
+ *,
+ audio: bytes | str | None = None,
+ audio_media_type: str = "audio/pcm;rate=16000",
+ image: bytes | str | None = None,
+ image_media_type: str = "image/jpeg",
+ text: str | None = None,
+ turn: PartInput | None = None,
+ tool_result: dict[str, Any] | None = None,
+ interrupt: bool = False,
+ end_audio: bool = False,
+ ) -> None:
+ if self._closed:
+ raise RuntimeError("live session is closed")
+
+ if event is not None:
+ has_payload = any(x is not None for x in (audio, image, text, turn, tool_result))
+ if has_payload or interrupt or end_audio:
+ raise ValueError("pass either `event` or keyword payload, not both")
+ events = [event]
+ else:
+ events = _events_from_kwargs(
+ audio=audio,
+ audio_media_type=audio_media_type,
+ image=image,
+ image_media_type=image_media_type,
+ text=text,
+ turn=turn,
+ tool_result=tool_result,
+ interrupt=interrupt,
+ end_audio=end_audio,
+ )
+
+ with self._send_lock:
+ for evt in events:
+ payloads = self._encode_event(evt)
+ for payload in payloads:
+ self._ws.send(json.dumps(payload))
+
+ def send_turn(self, content: PartInput, *, turn_complete: bool = True) -> None:
+ self.send(LiveClientTurnEvent(parts=_normalize_parts(content), turn_complete=turn_complete))
+
+ def send_audio(self, data: bytes | str, *, media_type: str = "audio/pcm;rate=16000") -> None:
+ self.send(LiveClientAudioEvent(data=_to_base64_str(data), media_type=media_type))
+
+ def send_image(self, data: bytes | str, *, media_type: str = "image/jpeg") -> None:
+ self.send(LiveClientImageEvent(data=_to_base64_str(data), media_type=media_type))
+
+ def send_text(self, text: str) -> None:
+ self.send(LiveClientTextEvent(text=text))
+
+ def send_tool_result(self, results: dict[str, Any]) -> None:
+ self.send(tool_result=results)
+
+ def interrupt(self) -> None:
+ self.send(interrupt=True)
+
+ def end_audio(self) -> None:
+ self.send(end_audio=True)
+
+ def recv(self) -> LiveServerEvent:
+ if self._closed:
+ raise RuntimeError("live session is closed")
+
+ while True:
+ if self._pending:
+ return self._pending.popleft()
+
+ raw = self._ws.recv()
+ decoded = self._decode_event(raw)
+ if not decoded:
+ continue
+
+ for event in decoded:
+ self._pending.append(event)
+
+ def turn(self) -> TurnView:
+ """Iterate one turn; see :class:`TurnView` and :class:`Turn`."""
+ return TurnView(self)
+
+ def close(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ try:
+ self._ws.close()
+ except Exception:
+ return
+
+ def __iter__(self):
+ return self
+
+ def __next__(self) -> LiveServerEvent:
+ if self._closed:
+ raise StopIteration
+ try:
+ return self.recv()
+ except RuntimeError:
+ raise StopIteration
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, *_args) -> None:
+ self.close()
+
+
+def _events_from_kwargs(
+ *,
+ audio: bytes | str | None,
+ audio_media_type: str,
+ image: bytes | str | None,
+ image_media_type: str,
+ text: str | None,
+ turn: PartInput | None,
+ tool_result: dict[str, Any] | None,
+ interrupt: bool,
+ end_audio: bool,
+) -> list[LiveClientEvent]:
+ events: list[LiveClientEvent] = []
+
+ if audio is not None:
+ events.append(LiveClientAudioEvent(data=_to_base64_str(audio), media_type=audio_media_type))
+ if image is not None:
+ events.append(LiveClientImageEvent(data=_to_base64_str(image), media_type=image_media_type))
+ if turn is not None:
+ events.append(LiveClientTurnEvent(parts=_normalize_parts(turn)))
+ if text is not None:
+ events.append(LiveClientTextEvent(text=text))
+
+ if tool_result:
+ for call_id, value in tool_result.items():
+ content = tuple(_tool_result_parts(value))
+ events.append(LiveClientToolResultEvent(id=call_id, content=content))
+
+ if interrupt:
+ events.append(LiveClientInterruptEvent())
+ if end_audio:
+ events.append(LiveClientEndAudioEvent())
+
+ if not events:
+ raise ValueError("nothing to send")
+ return events
+
+class AsyncWebSocketLiveSession:
+ """Native async live session over `websockets.asyncio`.
+
+ NOT a thread wrapper: a blocked sync ``recv()`` inside a worker
+ thread cannot be cancelled from the event loop, and cancellation
+ (barge-in, hangup) is the heart of realtime. Here ``recv()`` is a
+ real awaitable — cancelling the task cancels the read. The pure
+ encode/decode codecs are shared with the sync session verbatim.
+ """
+
+ def __init__(
+ self,
+ *,
+ ws: Any,
+ encode_event: EncodeEventFn,
+ decode_event: DecodeEventFn,
+ ) -> None:
+ self._ws = ws
+ self._encode_event = encode_event
+ self._decode_event = decode_event
+ self._pending: Deque[LiveServerEvent] = deque()
+ self._send_lock = asyncio.Lock()
+ self._closed = False
+
+ async def send(
+ self,
+ event: LiveClientEvent | None = None,
+ *,
+ audio: bytes | str | None = None,
+ audio_media_type: str = "audio/pcm;rate=16000",
+ image: bytes | str | None = None,
+ image_media_type: str = "image/jpeg",
+ text: str | None = None,
+ turn: PartInput | None = None,
+ tool_result: dict[str, Any] | None = None,
+ interrupt: bool = False,
+ end_audio: bool = False,
+ ) -> None:
+ if self._closed:
+ raise RuntimeError("live session is closed")
+
+ if event is not None:
+ has_payload = any(x is not None for x in (audio, image, text, turn, tool_result))
+ if has_payload or interrupt or end_audio:
+ raise ValueError("pass either `event` or keyword payload, not both")
+ events = [event]
+ else:
+ events = _events_from_kwargs(
+ audio=audio,
+ audio_media_type=audio_media_type,
+ image=image,
+ image_media_type=image_media_type,
+ text=text,
+ turn=turn,
+ tool_result=tool_result,
+ interrupt=interrupt,
+ end_audio=end_audio,
+ )
+
+ async with self._send_lock:
+ for evt in events:
+ for payload in self._encode_event(evt):
+ await self._ws.send(json.dumps(payload))
+
+ async def send_turn(self, content: PartInput, *, turn_complete: bool = True) -> None:
+ await self.send(LiveClientTurnEvent(parts=_normalize_parts(content), turn_complete=turn_complete))
+
+ async def send_audio(self, data: bytes | str, *, media_type: str = "audio/pcm;rate=16000") -> None:
+ await self.send(LiveClientAudioEvent(data=_to_base64_str(data), media_type=media_type))
+
+ async def send_image(self, data: bytes | str, *, media_type: str = "image/jpeg") -> None:
+ await self.send(LiveClientImageEvent(data=_to_base64_str(data), media_type=media_type))
+
+ async def send_text(self, text: str) -> None:
+ await self.send(LiveClientTextEvent(text=text))
+
+ async def send_tool_result(self, results: dict[str, Any]) -> None:
+ await self.send(tool_result=results)
+
+ async def interrupt(self) -> None:
+ await self.send(interrupt=True)
+
+ async def end_audio(self) -> None:
+ await self.send(end_audio=True)
+
+ async def recv(self) -> LiveServerEvent:
+ if self._closed:
+ raise RuntimeError("live session is closed")
+
+ while True:
+ if self._pending:
+ return self._pending.popleft()
+
+ raw = await self._ws.recv()
+ decoded = self._decode_event(raw)
+ if not decoded:
+ continue
+
+ for event in decoded:
+ self._pending.append(event)
+
+ def turn(self) -> AsyncTurnView:
+ """Iterate one turn; see :class:`AsyncTurnView` and :class:`Turn`."""
+ return AsyncTurnView(self)
+
+ async def close(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ try:
+ await self._ws.close()
+ except Exception:
+ return
+
+ def __aiter__(self):
+ return self
+
+ async def __anext__(self) -> LiveServerEvent:
+ if self._closed:
+ raise StopAsyncIteration
+ try:
+ return await self.recv()
+ except RuntimeError:
+ raise StopAsyncIteration
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, *_args) -> None:
+ await self.close()
+
+
+def _tool_result_parts(value: Any) -> list[Part]:
+ if isinstance(value, str):
+ return [TextPart(text=value)]
+ if isinstance(value, PART_CLASSES):
+ return [value]
+ if isinstance(value, Sequence) and not isinstance(value, (bytes, bytearray)):
+ parts = list(value)
+ if all(isinstance(part, PART_CLASSES) for part in parts):
+ return parts
+ return [TextPart(text=str(value))]
+
+
+def _to_base64_str(data: bytes | str) -> str:
+ if isinstance(data, bytes):
+ return base64.b64encode(data).decode("ascii")
+ return data
diff --git a/dspy/_vendor/lm15/lm15-python2.code-workspace b/dspy/_vendor/lm15/lm15-python2.code-workspace
new file mode 100644
index 000000000..072451b85
--- /dev/null
+++ b/dspy/_vendor/lm15/lm15-python2.code-workspace
@@ -0,0 +1,11 @@
+{
+ "folders": [
+ {
+ "path": ".."
+ },
+ {
+ "path": "../../curl-fixtures/api-references"
+ }
+ ],
+ "settings": {}
+}
\ No newline at end of file
diff --git a/dspy/_vendor/lm15/model_registry.py b/dspy/_vendor/lm15/model_registry.py
new file mode 100644
index 000000000..c070687e9
--- /dev/null
+++ b/dspy/_vendor/lm15/model_registry.py
@@ -0,0 +1,9 @@
+"""Compatibility wrapper for the model registry API.
+
+ModelRegistry lives in lm15.models alongside ModelInfo. This module exists for
+users who prefer importing it from lm15.model_registry.
+"""
+
+from .models import ModelRegistry
+
+__all__ = ["ModelRegistry"]
diff --git a/dspy/_vendor/lm15/models.py b/dspy/_vendor/lm15/models.py
new file mode 100644
index 000000000..e8c927529
--- /dev/null
+++ b/dspy/_vendor/lm15/models.py
@@ -0,0 +1,301 @@
+"""
+lm15.models — Optional model metadata and registry utilities.
+
+The canonical inference request remains Request(model="..."). ModelInfo and
+ModelRegistry are optional helpers for model discovery, validation, routing, and
+cost estimation. Model capabilities are endpoint-specific (`inference` today)
+so new endpoint families can be described later without breaking the
+inference model. Fine-tune PROVENANCE stays describable through ModelOrigin
+(`type`, `base_model`) — lm15 does inference with tuned models, not training.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from .compat import CompatProfile
+from .types import JsonObject
+
+
+# ─── Validation helpers ──────────────────────────────────────────────
+
+
+def _check_nonempty_text(value: object, field_name: str) -> None:
+ if not isinstance(value, str) or not value:
+ raise ValueError(f"{field_name} must be a non-empty string")
+
+
+def _check_positive_or_none(value: int | None, field_name: str) -> None:
+ if value is not None and (not isinstance(value, int) or isinstance(value, bool) or value <= 0):
+ raise ValueError(f"{field_name} must be a positive integer or None")
+
+
+def _check_non_negative_or_none(value: float | None, field_name: str) -> None:
+ if value is None:
+ return
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ raise ValueError(f"{field_name} must be a number or None")
+ if value < 0:
+ raise ValueError(f"{field_name} must be >= 0")
+
+
+def _coerce_float_field(obj: object, field_name: str) -> None:
+ """Number rule (docs/serde-rules.md): float fields have ONE wire form.
+
+ Same-valued int input is coerced (1 -> 1.0); bool never coerces.
+ """
+ value = getattr(obj, field_name)
+ if type(value) is int:
+ object.__setattr__(obj, field_name, float(value))
+
+
+def _coerce_int_field(obj: object, field_name: str) -> None:
+ """Number rule: int fields coerce same-valued floats, reject the rest."""
+ value = getattr(obj, field_name)
+ if type(value) is float:
+ if not value.is_integer():
+ raise ValueError(f"{field_name} must be an integer")
+ object.__setattr__(obj, field_name, int(value))
+
+
+def _check_json_object_or_none(value: object, field_name: str) -> None:
+ if value is None:
+ return
+ if not isinstance(value, dict):
+ raise TypeError(f"{field_name} must be a JSON object or None")
+
+
+# ─── Pricing ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class InferencePricing:
+ input_per_million: float | None = None
+ output_per_million: float | None = None
+ cache_read_per_million: float | None = None
+ cache_write_per_million: float | None = None
+ currency: str = "USD"
+ dimensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ for name in (
+ "input_per_million",
+ "output_per_million",
+ "cache_read_per_million",
+ "cache_write_per_million",
+ ):
+ _check_non_negative_or_none(getattr(self, name), name)
+ _coerce_float_field(self, name)
+ _check_nonempty_text(self.currency, "currency")
+ _check_json_object_or_none(self.dimensions, "dimensions")
+
+ def estimate(
+ self,
+ *,
+ input_tokens: int | None = None,
+ output_tokens: int | None = None,
+ cache_read_tokens: int | None = None,
+ cache_write_tokens: int | None = None,
+ ) -> float:
+ """Estimate cost for the given token counts.
+
+ ``None`` means "count unknown / not reported" (the ``Usage``
+ zeros-vs-absent distinction) and is SKIPPED: an unknown dimension
+ contributes nothing to the estimate, the same as a dimension whose
+ rate is unset. It is NOT treated as zero tokens — the returned
+ figure is a lower bound when any dimension is unknown. Pass an
+ explicit ``0`` for a known-zero count.
+ """
+ total = 0.0
+ if self.input_per_million is not None and input_tokens is not None:
+ total += input_tokens * self.input_per_million / 1_000_000
+ if self.output_per_million is not None and output_tokens is not None:
+ total += output_tokens * self.output_per_million / 1_000_000
+ if self.cache_read_per_million is not None and cache_read_tokens is not None:
+ total += cache_read_tokens * self.cache_read_per_million / 1_000_000
+ if self.cache_write_per_million is not None and cache_write_tokens is not None:
+ total += cache_write_tokens * self.cache_write_per_million / 1_000_000
+ return total
+
+
+# ─── Endpoint-specific model capabilities ────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class InferenceModelInfo:
+ input_modalities: tuple[str, ...] = ("text",)
+ output_modalities: tuple[str, ...] = ("text",)
+ context_window: int | None = None
+ max_output_tokens: int | None = None
+ supports_reasoning: bool = False
+ reasoning_efforts: tuple[str, ...] = ()
+ pricing: InferencePricing | None = None
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ object.__setattr__(self, "input_modalities", tuple(self.input_modalities))
+ object.__setattr__(self, "output_modalities", tuple(self.output_modalities))
+ object.__setattr__(self, "reasoning_efforts", tuple(self.reasoning_efforts))
+ if any(not isinstance(v, str) or not v for v in self.input_modalities):
+ raise ValueError("input_modalities must contain non-empty strings")
+ if any(not isinstance(v, str) or not v for v in self.output_modalities):
+ raise ValueError("output_modalities must contain non-empty strings")
+ if any(not isinstance(v, str) or not v for v in self.reasoning_efforts):
+ raise ValueError("reasoning_efforts must contain non-empty strings")
+ _coerce_int_field(self, "context_window")
+ _coerce_int_field(self, "max_output_tokens")
+ _check_positive_or_none(self.context_window, "context_window")
+ _check_positive_or_none(self.max_output_tokens, "max_output_tokens")
+ _check_json_object_or_none(self.extensions, "extensions")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelOrigin:
+ type: str = "provider"
+ id: str | None = None
+ base_model: str | None = None
+ provider_data: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_nonempty_text(self.type, "ModelOrigin.type")
+ if self.id is not None:
+ _check_nonempty_text(self.id, "ModelOrigin.id")
+ if self.base_model is not None:
+ _check_nonempty_text(self.base_model, "ModelOrigin.base_model")
+ _check_json_object_or_none(self.provider_data, "provider_data")
+
+
+@dataclass(frozen=True, slots=True)
+class ModelInfo:
+ id: str
+ provider: str
+ api_family: str
+ aliases: tuple[str, ...] = ()
+ origin: ModelOrigin = field(default_factory=ModelOrigin)
+ inference: InferenceModelInfo | None = None
+ compat: CompatProfile | None = None
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_nonempty_text(self.id, "ModelInfo.id")
+ _check_nonempty_text(self.provider, "ModelInfo.provider")
+ _check_nonempty_text(self.api_family, "ModelInfo.api_family")
+ object.__setattr__(self, "aliases", tuple(self.aliases))
+ if any(not isinstance(a, str) or not a for a in self.aliases):
+ raise ValueError("ModelInfo.aliases must contain non-empty strings")
+ if not isinstance(self.origin, ModelOrigin):
+ raise TypeError("ModelInfo.origin must be a ModelOrigin")
+ _check_json_object_or_none(self.extensions, "extensions")
+
+
+# ─── Registry ────────────────────────────────────────────────────────
+
+
+@dataclass(slots=True)
+class ModelRegistry:
+ _models: dict[tuple[str, str], ModelInfo] = field(default_factory=dict)
+ _aliases: dict[tuple[str, str], tuple[str, str]] = field(default_factory=dict)
+
+ def add(self, model: ModelInfo, *, replace: bool = True) -> None:
+ if not isinstance(model, ModelInfo):
+ raise TypeError("model must be a ModelInfo")
+ key = (model.provider, model.id)
+ if not replace and key in self._models:
+ raise ValueError(f"model already registered: {model.provider}/{model.id}")
+ self._models[key] = model
+ for alias in model.aliases:
+ self._aliases[(model.provider, alias)] = key
+
+ def add_profile(self, profile: object, *, replace: bool = True) -> None:
+ models = getattr(profile, "models", None)
+ if models is None:
+ raise TypeError("profile must have a models attribute")
+ for model in models:
+ self.add(model, replace=replace)
+
+ def get(self, provider: str, model: str) -> ModelInfo | None:
+ key = (provider, model)
+ if key in self._models:
+ return self._models[key]
+ target = self._aliases.get(key)
+ if target is not None:
+ return self._models.get(target)
+ return None
+
+ def resolve(self, model: str, provider: str | None = None) -> ModelInfo | None:
+ if provider is not None:
+ return self.get(provider, model)
+ matches = [
+ info
+ for (_provider, model_id), info in self._models.items()
+ if model_id == model or model in info.aliases
+ ]
+ return matches[0] if len(matches) == 1 else None
+
+ def list(self, provider: str | None = None) -> tuple[ModelInfo, ...]:
+ values = tuple(self._models.values())
+ if provider is None:
+ return values
+ return tuple(m for m in values if m.provider == provider)
+
+ def providers(self) -> tuple[str, ...]:
+ return tuple(sorted({provider for provider, _ in self._models}))
+
+ @classmethod
+ def from_profiles(cls, profiles: Iterable[object]) -> "ModelRegistry":
+ registry = cls()
+ for profile in profiles:
+ registry.add_profile(profile)
+ return registry
+
+ @classmethod
+ def from_dicts(cls, dicts: Iterable[dict]) -> "ModelRegistry":
+ """Build a registry from canonical ModelInfo dicts.
+
+ Each dict is validated through ``serde.model_info_from_dict``; the
+ ModelInfo constructors reject junk (negative prices, empty modality
+ names, missing id/provider) by raising ValueError/TypeError.
+ """
+ from .serde import model_info_from_dict
+
+ registry = cls()
+ for d in dicts:
+ registry.add(model_info_from_dict(d))
+ return registry
+
+ @classmethod
+ def discover(cls, *, group: str = "lm15.model_catalogs") -> "ModelRegistry":
+ """Hydrate a registry from installed entry-point catalogs.
+
+ Each entry point in ``group`` must load to a zero-argument callable
+ returning an iterable of canonical ModelInfo dicts
+ (docs/model-hydration.md). Catalogs are processed sorted by
+ entry-point name; on duplicate (provider, id) keys the FIRST
+ occurrence wins. A catalog that raises is skipped with a warning —
+ discovery never crashes the host application.
+
+ Hydrated data is ADVISORY metadata only: it must never change what
+ build_request produces.
+ """
+ import warnings
+ from importlib.metadata import entry_points
+
+ from .serde import model_info_from_dict
+
+ registry = cls()
+ for ep in sorted(entry_points(group=group), key=lambda e: e.name):
+ try:
+ catalog = ep.load()
+ models = [model_info_from_dict(d) for d in catalog()]
+ except Exception as exc:
+ warnings.warn(
+ f"lm15 model catalog {ep.name!r} failed and was skipped: {exc}",
+ stacklevel=2,
+ )
+ continue
+ for model in models:
+ if (model.provider, model.id) in registry._models:
+ continue # first occurrence wins
+ registry.add(model)
+ return registry
diff --git a/dspy/_vendor/lm15/profiles.py b/dspy/_vendor/lm15/profiles.py
new file mode 100644
index 000000000..d84175922
--- /dev/null
+++ b/dspy/_vendor/lm15/profiles.py
@@ -0,0 +1,229 @@
+"""
+lm15.profiles — Provider endpoint profiles and compatibility resolution.
+
+ProviderProfile connects endpoint metadata, model metadata, and typed
+compatibility policy. It is optional: provider adapters can still be used with
+just api_key/base_url and Request(model="...").
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .compat import (
+ CompatProfile,
+ OpenAIChatCompat,
+ OpenAIResponsesCompat,
+ ResolvedOpenAIResponsesCompat,
+ merge_openai_responses_compat,
+ resolve_openai_responses_compat as resolve_openai_responses_compat_partial,
+)
+from .models import (
+ InferenceModelInfo,
+ InferencePricing,
+ ModelInfo,
+ ModelOrigin,
+ ModelRegistry,
+)
+from .types import JsonObject
+
+
+# Re-export commonly used model/compat classes from lm15.profiles for ergonomic
+# imports while keeping their implementation in compat.py/models.py.
+__all__ = [
+ "CompatProfile",
+ "EndpointProfile",
+ "InferenceModelInfo",
+ "InferencePricing",
+ "ModelInfo",
+ "ModelOrigin",
+ "ModelRegistry",
+ "OpenAIChatCompat",
+ "OpenAIResponsesCompat",
+ "ProviderProfile",
+ "ResolvedOpenAIResponsesCompat",
+ "resolve_openai_responses_compat",
+]
+
+
+# ─── Validation helpers ──────────────────────────────────────────────
+
+
+def _check_nonempty_text(value: object, field_name: str) -> None:
+ if not isinstance(value, str) or not value:
+ raise ValueError(f"{field_name} must be a non-empty string")
+
+
+def _check_json_object_or_none(value: object, field_name: str) -> None:
+ if value is None:
+ return
+ if not isinstance(value, dict):
+ raise TypeError(f"{field_name} must be a JSON object or None")
+
+
+# ─── Provider profiles ───────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class EndpointProfile:
+ name: str
+ api_family: str
+ base_url: str | None = None
+ compat: CompatProfile | None = None
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_nonempty_text(self.name, "EndpointProfile.name")
+ _check_nonempty_text(self.api_family, "EndpointProfile.api_family")
+ if self.base_url is not None:
+ _check_nonempty_text(self.base_url, "EndpointProfile.base_url")
+ _check_json_object_or_none(self.extensions, "EndpointProfile.extensions")
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderProfile:
+ provider: str
+ endpoints: dict[str, EndpointProfile] = field(default_factory=dict)
+ models: tuple[ModelInfo, ...] = ()
+ extensions: JsonObject | None = None
+
+ def __post_init__(self) -> None:
+ _check_nonempty_text(self.provider, "ProviderProfile.provider")
+ object.__setattr__(self, "endpoints", dict(self.endpoints))
+ object.__setattr__(self, "models", tuple(self.models))
+ for name, endpoint in self.endpoints.items():
+ _check_nonempty_text(name, "ProviderProfile endpoint name")
+ if not isinstance(endpoint, EndpointProfile):
+ raise TypeError("ProviderProfile.endpoints values must be EndpointProfile")
+ if not all(isinstance(m, ModelInfo) for m in self.models):
+ raise TypeError("ProviderProfile.models must contain ModelInfo objects")
+ _check_json_object_or_none(self.extensions, "ProviderProfile.extensions")
+
+ @classmethod
+ def inference(
+ cls,
+ *,
+ provider: str,
+ api_family: str,
+ base_url: str | None = None,
+ compat: CompatProfile | None = None,
+ models: tuple[ModelInfo, ...] = (),
+ extensions: JsonObject | None = None,
+ ) -> "ProviderProfile":
+ return cls(
+ provider=provider,
+ endpoints={
+ "inference": EndpointProfile(
+ name="inference",
+ api_family=api_family,
+ base_url=base_url,
+ compat=compat,
+ )
+ },
+ models=models,
+ extensions=extensions,
+ )
+
+ def endpoint(self, name: str = "inference") -> EndpointProfile | None:
+ return self.endpoints.get(name)
+
+ def model(self, model_id: str) -> ModelInfo | None:
+ for model in self.models:
+ if model.id == model_id or model_id in model.aliases:
+ return model
+ return None
+
+
+# ─── Compatibility resolution ────────────────────────────────────────
+
+
+def openai_responses_compat_from_extensions(extensions: JsonObject | None) -> OpenAIResponsesCompat | None:
+ """Read request-level OpenAI Responses compat from Config.extensions.
+
+ Supported shapes:
+
+ {"openai_responses_compat": {...}}
+ {"openai_compat": {...}} # backwards-friendly alias
+ {"compat": {"openai_responses": {...}}}
+ {"compat": {"openai": {...}}} # generic OpenAI alias
+
+ This is an escape hatch. Normal configuration should use ProviderProfile.
+ """
+ if not extensions:
+ return None
+
+ raw: Any = extensions.get("openai_responses_compat")
+ if raw is None:
+ raw = extensions.get("openai_compat")
+ if raw is None:
+ compat = extensions.get("compat")
+ if isinstance(compat, dict):
+ raw = compat.get("openai_responses") or compat.get("openai")
+
+ if not isinstance(raw, dict):
+ return None
+
+ allowed = {
+ "developer_role",
+ "max_output_tokens_field",
+ "reasoning_format",
+ "tool_result_name",
+ "strict_tools",
+ "cache_control",
+ "commentary_phase",
+ "edit_image_field",
+ "builtin_tools",
+ "tool_result_media",
+ "routing",
+ "extensions",
+ }
+ kwargs = {k: v for k, v in raw.items() if k in allowed}
+ return OpenAIResponsesCompat(**kwargs) # type: ignore[arg-type]
+
+
+def resolve_openai_responses_compat(
+ *,
+ base_url: str,
+ model: str,
+ profile: ProviderProfile | None,
+ request_extensions: JsonObject | None,
+ base: OpenAIResponsesCompat | None = None,
+) -> ResolvedOpenAIResponsesCompat:
+ """Resolve effective OpenAI Responses compatibility policy.
+
+ Layering:
+
+ bound compat (``OpenAILM(compat=...)``), else the base URL default
+ < endpoint compat
+ < model compat
+ < request extension override
+ """
+ partial = base if base is not None else _default_openai_responses_compat_for_base_url(base_url)
+
+ endpoint = profile.endpoint("inference") if profile else None
+ if isinstance(endpoint and endpoint.compat, OpenAIResponsesCompat):
+ partial = merge_openai_responses_compat(partial, endpoint.compat)
+
+ model_info = profile.model(model) if profile else None
+ if isinstance(model_info and model_info.compat, OpenAIResponsesCompat):
+ partial = merge_openai_responses_compat(partial, model_info.compat)
+
+ partial = merge_openai_responses_compat(
+ partial,
+ openai_responses_compat_from_extensions(request_extensions),
+ )
+ return resolve_openai_responses_compat_partial(partial)
+
+
+def _default_openai_responses_compat_for_base_url(base_url: str) -> OpenAIResponsesCompat:
+ lower = base_url.lower()
+ if "openrouter.ai" in lower:
+ return OpenAIResponsesCompat.preset("openrouter")
+ if "api.openai.com" in lower:
+ return OpenAIResponsesCompat.preset("openai")
+ if "api.meta.ai" in lower:
+ return OpenAIResponsesCompat.preset("meta")
+ # Preserve the current OpenAILM Responses serializer behavior for unknown
+ # endpoints unless a profile/preset explicitly overrides it.
+ return OpenAIResponsesCompat.preset("openai")
diff --git a/dspy/_vendor/lm15/protocols.py b/dspy/_vendor/lm15/protocols.py
new file mode 100644
index 000000000..1bb2471a2
--- /dev/null
+++ b/dspy/_vendor/lm15/protocols.py
@@ -0,0 +1,84 @@
+"""
+lm15.protocols — Protocol definitions for provider LMs and sessions.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Iterator, Protocol
+
+from .features import EndpointSupport, ProviderManifest
+from .models import ModelInfo
+from .types import (
+ CachedPrefix,
+ CacheInfo,
+ CachePage,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ VideoPart,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ BatchRequest,
+ BatchEntry,
+ BatchJobInfo,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ LiveClientEvent,
+ LiveConfig,
+ LiveServerEvent,
+ PartInput,
+ Request,
+ Response,
+ StreamEvent,
+)
+
+
+
+class LiveSession(Protocol):
+ def send(self, event: LiveClientEvent | None = None, **kwargs: Any) -> None: ...
+ def send_turn(self, content: PartInput, *, turn_complete: bool = True) -> None: ...
+ def send_audio(self, data: bytes | str, *, media_type: str = "audio/pcm;rate=16000") -> None: ...
+ def send_image(self, data: bytes | str, *, media_type: str = "image/jpeg") -> None: ...
+ def send_text(self, text: str) -> None: ...
+ def send_tool_result(self, results: dict[str, Any]) -> None: ...
+ def interrupt(self) -> None: ...
+ def end_audio(self) -> None: ...
+ def recv(self) -> LiveServerEvent: ...
+ def close(self) -> None: ...
+
+
+class ProviderLM(Protocol):
+ provider: str
+ supports: EndpointSupport
+ manifest: ProviderManifest
+
+ def complete(self, request: Request) -> Response: ...
+ def stream(self, request: Request) -> Iterator[StreamEvent]: ...
+ def live(self, config: LiveConfig) -> LiveSession: ...
+ def file_upload(self, request: FileUploadRequest) -> FileInfo: ...
+ def file_get(self, file_id: str) -> FileInfo: ...
+ def file_list(self, limit: int = 20, cursor: str | None = None) -> FilePage: ...
+ def file_delete(self, file_id: str) -> None: ...
+ def file_download(self, file_id: str) -> bytes: ...
+ def file_wait_ready(self, file_id: str, poll_every: float = 2.0, timeout: float | None = None) -> FileInfo: ...
+ def batch_submit(self, request: BatchRequest) -> BatchJobInfo: ...
+ def batch_status(self, batch_id: str) -> BatchJobInfo: ...
+ def batch_results(self, batch_id: str) -> tuple[BatchEntry, ...]: ...
+ def batch_cancel(self, batch_id: str) -> BatchJobInfo: ...
+ def batch_list(self, limit: int = 20) -> tuple[BatchJobInfo, ...]: ...
+ def image_generate(self, request: ImageGenerationRequest) -> ImageGenerationResponse: ...
+ def speech_generate(self, request: SpeechGenerationRequest) -> SpeechGenerationResponse: ...
+ def video_submit(self, request: VideoGenerationRequest) -> VideoJobInfo: ...
+ def video_status(self, video_id: str) -> VideoJobInfo: ...
+ def video_result(self, video_id: str) -> VideoPart: ...
+ def video_list(self, limit: int = 20, model: str | None = None) -> tuple[VideoJobInfo, ...]: ...
+ def list_models(self) -> tuple[ModelInfo, ...]: ...
+ def cache_create(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None) -> CacheInfo: ...
+ def cache_get(self, cache_id: str) -> CacheInfo: ...
+ def cache_list(self, limit: int = 20, cursor: str | None = None) -> CachePage: ...
+ def cache_delete(self, cache_id: str) -> None: ...
+ def cache_update(self, cache_id: str, *, ttl_seconds: int) -> CacheInfo: ...
+ def cache(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None) -> CachedPrefix: ...
diff --git a/dspy/_vendor/lm15/providers/__init__.py b/dspy/_vendor/lm15/providers/__init__.py
new file mode 100644
index 000000000..c61f3a46a
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/__init__.py
@@ -0,0 +1,44 @@
+from .anthropic import AnthropicLM
+from .async_base import (
+ AsyncAnthropicLM,
+ AsyncBaseProviderLM,
+ AsyncClaudeCodeLM,
+ AsyncGeminiLM,
+ AsyncOpenAIChatLM,
+ AsyncOpenAICodexLM,
+ AsyncOpenAILM,
+ AsyncTransport,
+ AsyncXaiLM,
+)
+from .base import BaseProviderLM, Credential, HttpResponse, ProviderDialect, SyncTransport, resolve_credential
+from .claude_code import ClaudeCodeLM
+from .gemini import GeminiLM
+from .openai import OpenAILM
+from .openai_chat import OpenAIChatLM
+from .openai_codex import OpenAICodexLM
+from .xai import XaiLM
+
+__all__ = [
+ "OpenAILM",
+ "OpenAIChatLM",
+ "AnthropicLM",
+ "GeminiLM",
+ "ClaudeCodeLM",
+ "OpenAICodexLM",
+ "XaiLM",
+ "AsyncXaiLM",
+ "AsyncOpenAILM",
+ "AsyncOpenAIChatLM",
+ "AsyncAnthropicLM",
+ "AsyncGeminiLM",
+ "AsyncClaudeCodeLM",
+ "AsyncOpenAICodexLM",
+ "ProviderDialect",
+ "BaseProviderLM",
+ "AsyncBaseProviderLM",
+ "HttpResponse",
+ "SyncTransport",
+ "AsyncTransport",
+ "Credential",
+ "resolve_credential",
+]
diff --git a/dspy/_vendor/lm15/providers/anthropic.py b/dspy/_vendor/lm15/providers/anthropic.py
new file mode 100644
index 000000000..8668453ba
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/anthropic.py
@@ -0,0 +1,1187 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import json
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable, ClassVar, Iterator, Mapping
+
+from ..errors import (
+ AuthError,
+ BillingError,
+ ContextLengthError,
+ InvalidRequestError,
+ ProviderError,
+ RateLimitError,
+ ServerError,
+ TimeoutError,
+ UnsupportedFeatureError,
+ UnsupportedModelError,
+ canonical_error_code,
+ map_http_error,
+)
+from ..access import ANTHROPIC_API
+from ..compat import ANTHROPIC_PRESET_BASE_URLS, AnthropicCompat, ResolvedAnthropicCompat, resolve_anthropic_compat
+from ..features import ProviderManifest
+from ..sse import SSEEvent
+from ..transports import TransportRequest
+from ..types import (
+ BatchEntry,
+ BatchJobInfo,
+ BatchRequest,
+ BuiltinTool,
+ CitationDelta,
+ ContinuationDelta,
+ ContinuationState,
+ CitationPart,
+ DocumentPart,
+ ErrorDetail,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ FunctionTool,
+ ImagePart,
+ Message,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ StreamEvent,
+ StreamStartEvent,
+ TextDelta,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ ToolCallDelta,
+ continuation_data,
+ ToolCallPart,
+ ToolResultPart,
+ Usage,
+)
+from .base import (
+ BaseProviderLM,
+ Credential,
+ HttpResponse,
+ SyncTransport,
+ batch_entry_http,
+ batch_entry_request,
+ default_transport,
+)
+from .common import EFFORT_THINKING_BUDGETS, MEDIA_KINDS, anthropic_source, check_tool_result_media, iso_utc, model_infos_from_entries, multipart_form_body, parts_to_text, path_id, unnamed_tool_call_error
+
+# Canonical builtin tool name → Anthropic tool format
+_ANTHROPIC_BUILTIN_MAP: dict[str, str] = {
+ "web_search": "web_search_20250305",
+ "code_execution": "code_execution_20250522",
+}
+
+ANTHROPIC_PROVIDER_EXECUTED_BLOCKS = {
+ "server_tool_use",
+ "web_search_tool_result",
+ "code_execution_tool_result",
+}
+
+_DEFAULT_ANTHROPIC_VISIBLE_TOKENS = 1024
+_DEFAULT_ANTHROPIC_THINKING_BUDGET = 1024
+
+
+def _attach_unmapped(provider_data: dict[str, Any], unmapped: list[dict[str, str]]) -> dict[str, Any]:
+ if not unmapped:
+ return provider_data
+ out = dict(provider_data)
+ out["_lm15_unmapped"] = unmapped
+ return out
+
+
+def _record_unmapped(unmapped: list[dict[str, str]], path: str, typ: Any) -> None:
+ unmapped.append({"path": path, "type": str(typ or "<missing>")})
+
+
+def _builtin_to_anthropic(tool: BuiltinTool) -> dict[str, Any]:
+ out: dict[str, Any] = {"type": _ANTHROPIC_BUILTIN_MAP.get(tool.name, tool.name), "name": tool.name}
+ if tool.config:
+ out.update(tool.config)
+ return out
+
+
+def _response_format_to_anthropic_output_config(format_config: dict[str, Any]) -> dict[str, Any]:
+ """Canonical response_format (INV-050) -> Anthropic output_config.
+
+ The Messages API has no any-JSON mode: `format.schema` must be an object
+ schema with `additionalProperties: false` (HTTP 400 otherwise, live
+ 2026-09-02), so `json_object` RAISES. `strict` is satisfied (always
+ constrained); `name` is a label with no slot (dropped, stated in MAP-8).
+ """
+ if format_config["type"] == "json_object":
+ raise UnsupportedFeatureError(
+ "anthropic: response_format json_object is not supported — the Messages API has no "
+ "any-JSON mode; give a json_schema (objects need additionalProperties: false)",
+ provider="anthropic",
+ )
+ return {"format": {"type": "json_schema", "schema": format_config["schema"]}}
+
+
+def _reasoning_tokens(usage_payload: dict) -> int | None:
+ # The wire nests thinking spend under output_tokens_details; absent
+ # when thinking never ran, so None stays the honest "not reported".
+ details = usage_payload.get("output_tokens_details")
+ if isinstance(details, dict) and details.get("thinking_tokens") is not None:
+ return int(details["thinking_tokens"])
+ return None
+
+
+_ADAPTIVE_CLASS_MARKERS = ("sonnet-5", "opus-5", "sonnet-4-6", "opus-4-6", "opus-4-7", "opus-4-8", "fable", "mythos", "haiku-5")
+
+
+def anthropic_adaptive_class(model: str) -> bool:
+ """True for models that take `thinking: {type: adaptive}` + `output_config.effort`.
+
+ MAP-7 rule 10: a model-name table, receipted 2026-09-02 (Sonnet 5 accepts
+ adaptive and rejects `enabled`; Sonnet 4.5 and Haiku 4.5 do the reverse).
+ A table that rots: a new model outside it is treated as the manual class
+ and the server answers with a clear 400 ("thinking.type.enabled is not
+ supported for this model"); `extensions={"thinking": ...}` overrides.
+ """
+ lowered = model.lower()
+ return any(marker in lowered for marker in _ADAPTIVE_CLASS_MARKERS)
+
+
+def _reasoning_thinking_budget(request: Request) -> int | None:
+ """Manual class only: the budget on the wire (MAP-7 rules 3 and 5)."""
+ reasoning = request.config.reasoning
+ if reasoning is None or reasoning.is_off:
+ return None
+ if reasoning.thinking_budget is not None:
+ return reasoning.thinking_budget
+ return EFFORT_THINKING_BUDGETS[reasoning.effort]
+
+
+def _max_tokens_for_anthropic(request: Request, thinking_budget: int | None) -> int:
+ """Manual class: max_tokens includes thinking, so the wire ceiling is the
+ budget plus the visible cap. Adaptive class (thinking_budget None):
+ Config.max_tokens is the total ceiling — provider semantics, stated in
+ spec/types.md."""
+ if thinking_budget is None:
+ return request.config.max_tokens or _DEFAULT_ANTHROPIC_VISIBLE_TOKENS
+ visible_budget = request.config.max_tokens or _DEFAULT_ANTHROPIC_VISIBLE_TOKENS
+ return thinking_budget + visible_budget
+
+
+def _finish_reason(stop_reason: str | None, *, has_tool_call: bool = False) -> str:
+ if has_tool_call:
+ return "tool_call"
+ reason = str(stop_reason or "").lower()
+ if reason in {"max_tokens", "model_context_window_exceeded"}:
+ return "length"
+ if reason in {"tool_use", "pause_turn"}:
+ return "tool_call"
+ if reason in {"refusal", "safety", "content_filter"}:
+ return "content_filter"
+ return "stop"
+
+
+def _anthropic_batch_status(data: dict[str, Any]) -> str:
+ """Map an Anthropic Message Batch object to the canonical BatchStatus.
+
+ ``ended`` is Anthropic's single terminal processing_status; the
+ canonical terminal splits on request_counts — all-cancelled →
+ ``cancelled``, all-expired → ``expired``, anything else →
+ ``completed`` (per-entry outcomes live in the results, not the job).
+ """
+ status = str(data.get("processing_status") or "").lower()
+ if status == "in_progress":
+ return "running"
+ if status == "canceling":
+ return "cancelling"
+ if status == "ended":
+ counts = data.get("request_counts") or {}
+
+ def n(key: str) -> int:
+ try:
+ return int(counts.get(key) or 0)
+ except (TypeError, ValueError):
+ return 0
+
+ if n("canceled") and not (n("succeeded") or n("errored") or n("expired")):
+ return "cancelled"
+ if n("expired") and not (n("succeeded") or n("errored") or n("canceled")):
+ return "expired"
+ return "completed"
+ return "queued"
+
+
+def _citation_from_anthropic(citation: dict[str, Any]) -> CitationPart | None:
+ url = citation.get("url") or citation.get("uri")
+ title = citation.get("title") or citation.get("document_title") or citation.get("source_title")
+ text = citation.get("cited_text") or citation.get("text") or citation.get("quote")
+ url_s = str(url) if url else None
+ title_s = str(title) if title else None
+ text_s = str(text) if text else None
+ if url_s is None and title_s is None and text_s is None:
+ return None
+ return CitationPart(url=url_s, title=title_s, text=text_s)
+
+
+_DEFAULT_BASE_URL = "https://api.anthropic.com/v1"
+
+
+@dataclass(slots=True)
+class AnthropicLM(BaseProviderLM):
+ """Anthropic Messages dialect, bound to an access policy.
+
+ ``access`` defaults to the API-key policy (``lm15.access.ANTHROPIC_API``);
+ ``lm15.access.CLAUDE_CODE`` binds the same dialect to a local Claude
+ Code login (``ClaudeCodeLM`` is that binding under a name). The policy
+ is consulted at exactly these points: the auth header, static headers
+ (``anthropic-beta`` is joined with the dialect's own betas), the system
+ prefix, the login hint on errors, and the endpoint surfaces.
+ """
+
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: SyncTransport = field(default_factory=default_transport)
+ base_url: str = _DEFAULT_BASE_URL
+ api_version: str = "2023-06-01"
+ compat: AnthropicCompat | str | None = None
+ access: ProviderManifest | None = None
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="anthropic", init=False)
+ account_id: str | None = field(default=None, init=False, repr=False)
+ manifest: ClassVar[ProviderManifest] = ANTHROPIC_API
+ _resolved_compat: ResolvedAnthropicCompat = field(init=False, repr=False, default=ResolvedAnthropicCompat())
+
+ def __post_init__(self) -> None:
+ self._bind_access(self.access, credentials_path=self.credentials_path, default_base_url=_DEFAULT_BASE_URL, settings=self.settings)
+ compat = self.compat if self.compat is not None else self._registry_compat()
+ if isinstance(compat, str):
+ # A preset name also supplies that server's default base_url; an
+ # explicit non-default base_url argument always wins (same rule
+ # as OpenAIChatLM).
+ resolved = resolve_anthropic_compat(AnthropicCompat.preset(compat))
+ if self.base_url == _DEFAULT_BASE_URL:
+ self.base_url = ANTHROPIC_PRESET_BASE_URLS.get(compat.lower(), _DEFAULT_BASE_URL)
+ elif isinstance(compat, AnthropicCompat):
+ resolved = resolve_anthropic_compat(compat)
+ else:
+ resolved = resolve_anthropic_compat(AnthropicCompat())
+ self._resolved_compat = resolved
+
+ _error_type_map: ClassVar[dict[str, type[ProviderError]]] = {
+ "authentication_error": AuthError,
+ "permission_error": AuthError,
+ "billing_error": BillingError,
+ "rate_limit_error": RateLimitError,
+ "request_too_large": InvalidRequestError,
+ "not_found_error": InvalidRequestError,
+ "resource_not_found_error": InvalidRequestError, # Moonshot's Anthropic wire (errors.md)
+ "DeploymentNotFound": UnsupportedModelError, # Azure Foundry: top-level code, model string = deployment
+ "invalid_authentication_error": AuthError, # Moonshot's Anthropic wire (errors.md)
+ "invalid_request_error": InvalidRequestError,
+ "api_error": ServerError,
+ "overloaded_error": ServerError,
+ "timeout_error": TimeoutError,
+ }
+
+ @staticmethod
+ def _is_context_length_message(msg: str) -> bool:
+ lowered = msg.lower()
+ return (
+ "prompt is too long" in lowered
+ or "too many tokens" in lowered
+ or "context window" in lowered
+ or "context length" in lowered
+ or ("token" in lowered and ("limit" in lowered or "exceed" in lowered))
+ )
+
+ @staticmethod
+ def _is_model_error(message: str) -> bool:
+ lowered = message.lower()
+ return "model" in lowered and any(
+ marker in lowered
+ for marker in (
+ "not found",
+ "does not exist",
+ "not exist",
+ "not supported",
+ "unsupported",
+ "not available",
+ "unknown",
+ )
+ )
+
+ def _error_detail(self, provider_code: str, message: str) -> ErrorDetail:
+ cls = self._error_type_map.get(provider_code, ProviderError)
+ if self._is_context_length_message(message):
+ cls = ContextLengthError
+ elif provider_code == "not_found_error" and self._is_model_error(message):
+ cls = UnsupportedModelError
+ return ErrorDetail(
+ code=canonical_error_code(cls),
+ message=message or provider_code or "provider error",
+ provider_code=provider_code or "provider",
+ )
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ try:
+ data = json.loads(body)
+ inner = data.get("error") if isinstance(data, dict) else None
+ # Anthropic's envelope nests under `error`; Azure Foundry's
+ # gateway uses top-level {code, message} before a deployment is
+ # reached (live 2026-09-04). Keep both shapes on one wire.
+ err = inner if isinstance(inner, (dict, str)) else data if isinstance(data, dict) else {}
+ msg = err.get("message", "") if isinstance(err, dict) else str(err)
+ err_type = str(err.get("type") or err.get("code") or "") if isinstance(err, dict) else ""
+ request_id = str(data.get("request_id") or "") if isinstance(data, dict) else ""
+
+ if self._is_context_length_message(msg):
+ return self._provider_error(
+ ContextLengthError,
+ msg,
+ status=status,
+ provider_code=err_type or None,
+ request_id=request_id or None,
+ )
+ # `resource_not_found_error` is Moonshot's spelling of the same
+ # 404 on its Anthropic wire ("Not found the model …", live
+ # 2026-09-03); the message rule decides, as on the chat wire.
+ if err_type == "DeploymentNotFound" or (
+ err_type in ("not_found_error", "resource_not_found_error") and self._is_model_error(msg)
+ ):
+ return self._provider_error(
+ UnsupportedModelError,
+ msg,
+ status=status,
+ provider_code=err_type,
+ request_id=request_id or None,
+ )
+
+ cls = self._error_type_map.get(err_type)
+ if cls:
+ return self._provider_error(
+ cls,
+ msg,
+ status=status,
+ provider_code=err_type or None,
+ request_id=request_id or None,
+ )
+ if err_type and err_type not in msg:
+ msg = f"{msg} ({err_type})"
+ except Exception:
+ msg = body.strip()[:500] or f"HTTP {status}"
+ err_type = ""
+ request_id = ""
+ return self._with_login_hint(map_http_error(
+ status,
+ msg,
+ provider=self.provider,
+ env_keys=self.access.env_keys,
+ provider_code=err_type or None,
+ request_id=request_id or None,
+ ))
+
+ def _headers(self, request: Request | None = None) -> dict[str, str]:
+ # The auth header is the policy's business: _emit applies it once per
+ # request for every scheme (AUTH-2, AUTH-10).
+ headers: dict[str, str] = {}
+ headers["anthropic-version"] = self.api_version
+ headers["content-type"] = "application/json"
+ betas: list[str] = []
+ for key, static in self.access.headers:
+ if key.lower() == "anthropic-beta":
+ betas.extend(b for b in static.split(",") if b)
+ else:
+ headers[key] = static
+ if request is not None and any(
+ isinstance(tool, BuiltinTool) and tool.name == "code_execution"
+ for tool in request.tools
+ ):
+ betas.append("code-execution-2025-05-22")
+ if betas:
+ headers["anthropic-beta"] = ",".join(betas)
+ return headers
+
+ # ─── Request serialization ──────────────────────────────────────
+
+ def _part(self, part) -> dict[str, Any]:
+ if isinstance(part, TextPart):
+ return {"type": "text", "text": part.text}
+ if isinstance(part, ImagePart):
+ return {"type": "image", "source": anthropic_source(part)}
+ if isinstance(part, DocumentPart):
+ return {"type": "document", "source": anthropic_source(part)}
+ if isinstance(part, ToolCallPart):
+ return {"type": "tool_use", "id": part.id, "name": part.name, "input": part.input}
+ if isinstance(part, ToolResultPart):
+ check_tool_result_media(self.provider, part, self._resolved_compat.tool_result_media, wire="a tool_result block")
+ content_blocks = [self._tool_result_content(p) for p in part.content]
+ out: dict[str, Any] = {"type": "tool_result", "tool_use_id": part.id}
+ if content_blocks:
+ # Anthropic accepts either a string or content blocks. Blocks
+ # preserve image/document tool outputs when present.
+ if len(content_blocks) == 1 and content_blocks[0].get("type") == "text":
+ out["content"] = content_blocks[0]["text"]
+ else:
+ out["content"] = content_blocks
+ if part.is_error:
+ out["is_error"] = True
+ return out
+ if isinstance(part, ThinkingPart):
+ redacted = continuation_data(part, "anthropic", "redacted_thinking")
+ if redacted is not None:
+ return {"type": "redacted_thinking", **redacted}
+ signature = continuation_data(part, "anthropic", "thinking_signature")
+ if signature and signature.get("signature"):
+ return {
+ "type": "thinking",
+ "thinking": part.text,
+ "signature": signature["signature"],
+ }
+ if self._resolved_compat.thinking_replay == "unsigned" and part.text:
+ # The server signs nothing (`signature: ""`) and takes the
+ # block back unsigned (Moonshot, live 2026-09-03); a text
+ # replay would turn the reasoning into a spoken turn.
+ return {"type": "thinking", "thinking": part.text}
+ return {"type": "text", "text": part.text}
+ return {"type": "text", "text": getattr(part, "text", "") or ""}
+
+ def _tool_result_content(self, part) -> dict[str, Any]:
+ if isinstance(part, TextPart):
+ return {"type": "text", "text": part.text}
+ if isinstance(part, ImagePart):
+ return {"type": "image", "source": anthropic_source(part)}
+ if isinstance(part, DocumentPart):
+ return {"type": "document", "source": anthropic_source(part)}
+ if part.type in MEDIA_KINDS:
+ # ToolResultBlockParam takes text, image and document blocks only.
+ raise UnsupportedFeatureError(
+ f"{self.provider}: a {part.type} part cannot reach a tool_result block (text, image and document only; MAP-10)",
+ provider=self.provider,
+ )
+ return {"type": "text", "text": parts_to_text((part,), provider=self.provider)}
+
+ def _message(self, msg: Message) -> dict[str, Any]:
+ role = "assistant" if msg.role == "assistant" else "user"
+ parts = [self._part(part) for part in msg.parts]
+ if msg.role == "developer":
+ text = parts_to_text(msg.parts)
+ parts = [{"type": "text", "text": f"[developer]\n{text}"}]
+ return {"role": role, "content": parts}
+
+ def _tool_choice_payload(self, request: Request) -> dict[str, Any] | None:
+ tc = request.config.tool_choice
+ if tc is None:
+ return None
+
+ payload: dict[str, Any] = {}
+ if tc.mode == "none":
+ payload["type"] = "none"
+ elif tc.allowed:
+ # {"type": "tool", "name": ...} forces client tools AND server
+ # tools — verified live 2026-09-01 with web_search (the API
+ # reference is silent on server tools; the capture is the
+ # evidence). Builtin names ride the same form because
+ # _builtin_to_anthropic puts the canonical name on the wire.
+ if len(tc.allowed) == 1 and tc.mode == "required":
+ payload["type"] = "tool"
+ payload["name"] = tc.allowed[0]
+ elif set(tc.allowed) == {t.name for t in request.tools}:
+ # Allowing every declared tool is no restriction at all.
+ payload["type"] = "any" if tc.mode == "required" else "auto"
+ else:
+ # A proper-subset allowlist has no Anthropic wire form.
+ # Degrading to any/auto would let the model call excluded
+ # tools — raise, never silently widen the caller's policy.
+ raise UnsupportedFeatureError(
+ "anthropic: tool_choice.allowed subsets are not supported — "
+ "the Messages API can force one named tool or allow all "
+ "declared tools, but cannot restrict to a subset. Send only "
+ "the allowed tools in Request.tools instead",
+ provider=self.provider,
+ )
+ elif tc.mode == "required":
+ payload["type"] = "any"
+ else:
+ payload["type"] = "auto"
+
+ if tc.parallel is False and payload["type"] != "none":
+ payload["disable_parallel_tool_use"] = True
+
+ return payload
+
+ def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ compat = self._resolved_compat
+ if compat.model_prefixes is not None and not request.model.startswith(compat.model_prefixes):
+ # The server maps foreign model names onto its own models without
+ # saying so (DeepSeek: claude-opus* → deepseek-v4-pro, live
+ # 2026-09-03, the response `model` field is the only tell).
+ raise UnsupportedModelError(
+ f"{self.provider}: model {request.model!r} is not one this endpoint serves as typed "
+ f"(expected a prefix in {list(compat.model_prefixes)}); it would be silently "
+ "substituted by another model. Name the model you actually want.",
+ provider=self.provider,
+ )
+ cache_cfg = request.config.cache
+ # cache_control="none": the server ignores marks and caches
+ # implicitly; nothing is placed and an explicit CacheConfig is not an
+ # error — the same rule as the chat dialect's "none" presets.
+ use_cache = cache_cfg is not None and cache_cfg.mode != "off" and compat.cache_control == "anthropic"
+ long_cache = cache_cfg is not None and cache_cfg.retention == "long" and compat.cache_control == "anthropic"
+
+ messages = [self._message(m) for m in request.messages]
+
+ # MAP-6 marks. prefix_until_index=N and prefix="history" (N = last
+ # message) put cache_control on the last block of message N; the
+ # explicit block form rather than the top-level automatic marker,
+ # which walks backwards silently when the last block is ineligible.
+ # prefix="stable" (and plain auto) mark the system block below.
+ # key / resource name mechanisms the Messages API does not have.
+ if use_cache and cache_cfg is not None:
+ if cache_cfg.key is not None:
+ raise UnsupportedFeatureError(
+ "anthropic: cache.key is not supported — the Messages API has no "
+ "cache affinity key (OpenAI's prompt_cache_key); marks on blocks "
+ "are the mechanism (prefix / prefix_until_index)",
+ provider=self.provider,
+ )
+ if cache_cfg.resource is not None:
+ raise UnsupportedFeatureError(
+ "anthropic: cache.resource is not supported — the Messages API has no "
+ "stored-cache tier; it caches by marks on blocks",
+ provider=self.provider,
+ )
+ idx = None
+ if cache_cfg.prefix_until_index is not None:
+ idx = min(cache_cfg.prefix_until_index, len(messages) - 1)
+ elif cache_cfg.prefix == "history":
+ idx = len(messages) - 1
+ if idx is not None and idx >= 0 and messages[idx].get("content"):
+ last_block = messages[idx]["content"][-1]
+ if isinstance(last_block, dict):
+ marker: dict[str, Any] = {"type": "ephemeral"}
+ if long_cache:
+ marker["ttl"] = "1h"
+ last_block.setdefault("cache_control", marker)
+
+ reasoning = request.config.reasoning
+ deepseek_thinking = compat.thinking_format == "deepseek"
+ # "adaptive": every model on this server is the adaptive class (Meta
+ # Model API, protocols--messages.md § Reasoning) — no model-name table.
+ always_adaptive = compat.thinking_format == "adaptive"
+ # "effort": no `thinking` object exists on this server; the dial is
+ # output_config.effort alone (Moonshot messages--create.md).
+ effort_only = compat.thinking_format == "effort"
+ adaptive = (
+ reasoning is not None and not reasoning.is_off
+ and (deepseek_thinking or always_adaptive or effort_only or anthropic_adaptive_class(request.model))
+ )
+ if reasoning is not None and not reasoning.is_off:
+ if compat.reasoning_efforts is not None and reasoning.effort not in compat.reasoning_efforts:
+ # MAP-7 rule 2: a word with no native level raises here when
+ # the server would not refuse it (Moonshot's Anthropic wire
+ # answered 200 to `medium` and to `bogus`, live 2026-09-03).
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.effort={reasoning.effort!r} has no level on this server "
+ f"(it accepts {', '.join(compat.reasoning_efforts)}) and would be accepted silently",
+ provider=self.provider,
+ )
+ if reasoning.summary in ("concise", "detailed"):
+ raise UnsupportedFeatureError(
+ f"anthropic: reasoning.summary={reasoning.summary!r} is an OpenAI detail level; "
+ "the Messages API returns thinking blocks whenever thinking runs (use 'auto' or None)",
+ provider=self.provider,
+ )
+ if adaptive:
+ if reasoning.thinking_budget is not None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.thinking_budget is not supported on {request.model} — "
+ + ("this server ignores budget_tokens (a silent no-op); effort is the dial"
+ if deepseek_thinking else
+ "this server accepts budget_tokens without translating it (a silent no-op); "
+ "effort is the dial (protocols--messages.md)"
+ if always_adaptive else
+ "this model class takes thinking.type 'adaptive' with output_config.effort; "
+ "budget_tokens is rejected by the API (live 2026-09-02)"),
+ provider=self.provider,
+ )
+ # MAP-7: the word goes verbatim on the always-adaptive server;
+ # it answers an unsupported level with a 400 of its own.
+ if reasoning.effort == "minimal" and not (deepseek_thinking or always_adaptive or effort_only):
+ raise UnsupportedFeatureError(
+ "anthropic: reasoning.effort='minimal' has no level on this model class "
+ "(output_config.effort is low|medium|high|xhigh|max); 'low' is the floor",
+ provider=self.provider,
+ )
+ thinking_budget = None if adaptive else _reasoning_thinking_budget(request)
+ payload: dict[str, Any] = {
+ "model": request.model,
+ "messages": messages,
+ "stream": stream,
+ "max_tokens": _max_tokens_for_anthropic(request, thinking_budget),
+ }
+
+ if request.system:
+ system_text = request.system if isinstance(request.system, str) else parts_to_text(request.system)
+ if use_cache:
+ cache_marker: dict[str, Any] = {"type": "ephemeral"}
+ if long_cache:
+ cache_marker["ttl"] = "1h"
+ payload["system"] = [{"type": "text", "text": system_text, "cache_control": cache_marker}]
+ else:
+ payload["system"] = system_text
+ if compat.sampling_params == "reject":
+ for name in ("temperature", "top_p", "top_k"):
+ if getattr(request.config, name) is not None:
+ # The server documents none of these and swallows them
+ # silently (Moonshot, live 2026-09-03: temperature 0.5 is
+ # HTTP 200 here, "only 1 is allowed" on its chat wire).
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.{name} is silently ignored by this server "
+ "(the model's sampling is fixed); omit it",
+ provider=self.provider,
+ )
+ if request.config.temperature is not None:
+ payload["temperature"] = request.config.temperature
+ if request.config.top_p is not None:
+ payload["top_p"] = request.config.top_p
+ if request.config.top_k is not None:
+ payload["top_k"] = request.config.top_k
+ if request.config.stop:
+ payload["stop_sequences"] = list(request.config.stop)
+ if request.tools:
+ tools_wire: list[dict[str, Any]] = []
+ for tool in request.tools:
+ if isinstance(tool, FunctionTool):
+ tools_wire.append({"name": tool.name, "description": tool.description, "input_schema": tool.parameters})
+ elif isinstance(tool, BuiltinTool):
+ tools_wire.append(_builtin_to_anthropic(tool))
+ payload["tools"] = tools_wire
+ tool_choice = self._tool_choice_payload(request)
+ if tool_choice is not None:
+ tc = request.config.tool_choice
+ if compat.parallel_tool_calls == "reject" and tc is not None and tc.parallel is not None:
+ # disable_parallel_tool_use is documented as ignored
+ # (guide--anthropic-api.md); a silent no-op is refused (MAP-8 §2).
+ raise UnsupportedFeatureError(
+ f"{self.provider}: tool_choice.parallel is silently ignored by this server "
+ "(disable_parallel_tool_use is not applied); omit it",
+ provider=self.provider,
+ )
+ payload["tool_choice"] = tool_choice
+ if deepseek_thinking:
+ # DeepSeek over the Anthropic wire (guide--anthropic-api.md; live
+ # 2026-09-03): thinking is ON by default, so absence is not off —
+ # an explicit off must reach the wire. On: type=enabled and
+ # output_config.effort (budget_tokens is ignored by the server).
+ if reasoning is not None and reasoning.is_off:
+ payload["thinking"] = {"type": "disabled"}
+ elif reasoning is not None:
+ payload["thinking"] = {"type": "enabled"}
+ payload["output_config"] = {"effort": reasoning.effort}
+ elif effort_only:
+ # Moonshot over the Anthropic wire (messages--create.md): no
+ # thinking object is documented; output_config.effort alone.
+ # Off goes out as thinking.type=disabled, which the server
+ # honours (live 2026-09-03: no thinking block, no thinking_tokens).
+ if reasoning is not None and reasoning.is_off:
+ payload["thinking"] = {"type": "disabled"}
+ elif reasoning is not None:
+ payload["output_config"] = {"effort": reasoning.effort}
+ elif always_adaptive and reasoning is not None and reasoning.is_off:
+ # The server reasons by default and cannot stop (Meta: Muse Spark
+ # "always reasons"). Explicit off must reach the wire so the
+ # server refuses it loudly (HTTP 400) instead of spending hidden
+ # reasoning tokens the caller asked to disable.
+ payload["thinking"] = {"type": "disabled"}
+ elif adaptive:
+ # MAP-7 rule 2 on the adaptive class (live 2026-09-02, Sonnet 5):
+ # the model decides when to think; effort steers depth.
+ payload["thinking"] = {"type": "adaptive"}
+ payload["output_config"] = {"effort": reasoning.effort}
+ elif thinking_budget is not None:
+ payload["thinking"] = {
+ "type": "enabled",
+ "budget_tokens": thinking_budget,
+ }
+ if request.config.response_format:
+ if compat.structured_output == "reject":
+ # The server accepts output_config.format and ignores the
+ # schema (DeepSeek, live 2026-09-03: 200 with keys the schema
+ # never named). Silent, so refuse before the wire.
+ raise UnsupportedFeatureError(
+ f"{self.provider}: response_format is silently ignored by this server "
+ "(output_config.format is accepted and not applied); describe the shape in the prompt",
+ provider=self.provider,
+ )
+ output_config = _response_format_to_anthropic_output_config(request.config.response_format)
+ payload["output_config"] = {**payload.get("output_config", {}), **output_config}
+ # Promoted cross-provider knobs (changes/2026-09-01-extensions-burn-down):
+ # user_id rides Anthropic's metadata.user_id; store has no Anthropic
+ # wire field — raise, never silently drop.
+ if request.config.service_tier is not None:
+ payload["service_tier"] = request.config.service_tier
+ if request.config.user_id is not None:
+ payload["metadata"] = {"user_id": request.config.user_id}
+ if request.config.store is not None:
+ raise UnsupportedFeatureError(
+ "anthropic: config.store is not supported — the Messages API has no "
+ "response-storage opt-out field (OpenAI and Gemini carry it)",
+ provider=self.provider,
+ )
+ if request.config.logprobs is not None:
+ raise UnsupportedFeatureError(
+ "anthropic: config.logprobs is not supported — the Messages API "
+ "does not expose token log probabilities (OpenAI and Gemini "
+ "carry them)",
+ provider=self.provider,
+ )
+ if request.config.extensions:
+ passthrough = {k: v for k, v in request.config.extensions.items() if k != "prompt_caching"}
+ payload.update(passthrough)
+ if self.access.system_prefix:
+ # The access path requires this text first in the system prompt
+ # (Claude Code's backend checks for it); the caller's system
+ # follows, cache markers and all.
+ prefix = {"type": "text", "text": self.access.system_prefix}
+ existing = payload.get("system")
+ if existing is None:
+ payload["system"] = [prefix]
+ elif isinstance(existing, list):
+ payload["system"] = [prefix, *existing]
+ else:
+ payload["system"] = [prefix, {"type": "text", "text": str(existing)}]
+ return payload
+
+ def build_request(self, request: Request, stream: bool) -> TransportRequest:
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/messages",
+ headers=self._headers(request),
+ payload=self._payload(request, stream=stream),
+ endpoint="messages",
+ stream=stream,
+ model=request.model,
+ read_timeout=120.0 if stream else 60.0,
+ )
+
+ # ─── Response parsing ───────────────────────────────────────────
+
+ def parse_response(self, request: Request, response: HttpResponse) -> Response:
+ data = response.json()
+ parts: list[Any] = []
+ unmapped: list[dict[str, str]] = []
+ for block_index, block in enumerate(data.get("content", []) or []):
+ if not isinstance(block, dict):
+ _record_unmapped(unmapped, f"content[{block_index}]", type(block).__name__)
+ continue
+ block_type = block.get("type")
+ if block_type == "text":
+ parts.append(TextPart(text=str(block.get("text") or "")))
+ for citation_payload in block.get("citations", []) or []:
+ if not isinstance(citation_payload, dict):
+ continue
+ citation = _citation_from_anthropic(citation_payload)
+ if citation is not None:
+ parts.append(citation)
+ elif block_type == "tool_use":
+ if not block.get("name"):
+ raise unnamed_tool_call_error(self.provider, f"content[{block_index}]")
+ parts.append(ToolCallPart(
+ id=str(block.get("id") or f"tool_{len(parts)}"),
+ name=str(block["name"]),
+ input=block.get("input") if isinstance(block.get("input"), dict) else {},
+ ))
+ elif block_type == "thinking":
+ continuation: tuple[ContinuationState, ...] = ()
+ if block.get("signature"):
+ continuation = (
+ ContinuationState(
+ provider="anthropic",
+ kind="thinking_signature",
+ data={"signature": str(block.get("signature"))},
+ ),
+ )
+ parts.append(
+ ThinkingPart(
+ text=str(block.get("thinking") or block.get("text") or ""),
+ continuation=continuation,
+ )
+ )
+ elif block_type == "redacted_thinking":
+ # MAP-7 rule 11: hidden thinking is empty text plus replay
+ # state; the blob goes back verbatim as redacted_thinking.
+ continuation = ()
+ redacted_payload = block.get("data")
+ if redacted_payload is not None:
+ continuation = (
+ ContinuationState(
+ provider="anthropic",
+ kind="redacted_thinking",
+ data={"data": redacted_payload},
+ ),
+ )
+ parts.append(ThinkingPart(text="", continuation=continuation))
+ elif block_type in ANTHROPIC_PROVIDER_EXECUTED_BLOCKS:
+ continue
+ else:
+ _record_unmapped(unmapped, f"content[{block_index}]", block_type)
+
+ if not parts:
+ parts = [TextPart(text="")]
+
+ usage_payload = data.get("usage", {}) or {}
+ # INV-029: absent counters stay None; Usage sums the total itself
+ # only when both primaries are present.
+ usage = Usage(
+ input_tokens=usage_payload.get("input_tokens"),
+ output_tokens=usage_payload.get("output_tokens"),
+ cache_read_tokens=usage_payload.get("cache_read_input_tokens"),
+ cache_write_tokens=usage_payload.get("cache_creation_input_tokens"),
+ reasoning_tokens=_reasoning_tokens(usage_payload),
+ )
+ has_tool = any(isinstance(part, ToolCallPart) for part in parts)
+ # D8 (2026-09-06): Response.id carries the message id; no
+ # message-level continuation state is minted for it.
+ return Response(
+ id=str(data.get("id")) if data.get("id") else None,
+ model=str(data.get("model") or request.model),
+ message=Message(role="assistant", parts=tuple(parts)),
+ finish_reason=_finish_reason(data.get("stop_reason"), has_tool_call=has_tool),
+ usage=usage,
+ provider_data=_attach_unmapped(data, unmapped),
+ )
+
+ def parse_stream_events(self, request: Request, raw_event: SSEEvent) -> Iterator[StreamEvent]:
+ if not raw_event.data:
+ return
+ payload = json.loads(raw_event.data)
+ et = payload.get("type")
+ if et == "message_start":
+ msg = payload.get("message", {}) if isinstance(payload.get("message"), dict) else {}
+ yield StreamStartEvent(
+ id=str(msg.get("id")) if msg.get("id") else None,
+ model=str(msg.get("model") or request.model),
+ )
+ return
+ if et == "content_block_start":
+ block = payload.get("content_block", {}) if isinstance(payload.get("content_block"), dict) else {}
+ if block.get("type") == "tool_use":
+ # A streamed tool_use block opens with input: {} and the
+ # arguments arrive as input_json_delta fragments; the empty
+ # object is a placeholder, not a fragment. Serialising it
+ # produced "{}" + '{"city": ...}' — unparseable — the day
+ # the first streaming tool call was pinned (2026-09-02). A
+ # non-empty input on the start frame is kept verbatim.
+ start_input = block.get("input")
+ yield StreamDeltaEvent(
+ delta=ToolCallDelta(
+ input=json.dumps(start_input, separators=(",", ":")) if isinstance(start_input, dict) and start_input else ("" if isinstance(start_input, dict) else str(start_input or "")),
+ part_index=int(payload.get("index", 0) or 0),
+ id=str(block.get("id") or "") or None,
+ name=str(block.get("name") or "") or None,
+ )
+ )
+ return
+ if block.get("type") == "redacted_thinking" and block.get("data") is not None:
+ # MAP-7 rule 11: an empty thinking delta opens the hidden
+ # block; its replay state is the block's only content. The
+ # block has no interior frames, so the state is emitted here
+ # (the adapter is stateless per frame) and the trace reads the
+ # same as an emission at content_block_stop.
+ idx = int(payload.get("index", 0) or 0)
+ yield StreamDeltaEvent(delta=ThinkingDelta(text="", part_index=idx))
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider="anthropic",
+ kind="redacted_thinking",
+ data={"data": block.get("data")},
+ part_index=idx,
+ )
+ )
+ return
+ if et == "content_block_delta":
+ delta = payload.get("delta", {}) if isinstance(payload.get("delta"), dict) else {}
+ idx = int(payload.get("index", 0) or 0)
+ dtype = delta.get("type")
+ if dtype == "text_delta":
+ yield StreamDeltaEvent(delta=TextDelta(text=str(delta.get("text") or ""), part_index=idx))
+ elif dtype == "input_json_delta":
+ yield StreamDeltaEvent(delta=ToolCallDelta(input=str(delta.get("partial_json") or ""), part_index=idx))
+ elif dtype == "thinking_delta":
+ yield StreamDeltaEvent(delta=ThinkingDelta(text=str(delta.get("thinking") or ""), part_index=idx))
+ elif dtype == "signature_delta" and delta.get("signature"):
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider="anthropic",
+ kind="thinking_signature",
+ data={"signature": str(delta.get("signature"))},
+ part_index=idx,
+ )
+ )
+ elif dtype in {"citation_delta", "citations_delta"}:
+ citation = delta.get("citation", {}) if isinstance(delta.get("citation"), dict) else delta
+ yield StreamDeltaEvent(delta=CitationDelta(
+ part_index=idx,
+ text=str(citation.get("cited_text") or citation.get("text") or "") or None,
+ url=str(citation.get("url") or "") or None,
+ title=str(citation.get("title") or "") or None,
+ ))
+ return
+ if et == "message_delta":
+ # Anthropic sends the authoritative stop_reason and final usage here;
+ # message_stop is just the terminator and carries neither.
+ delta = payload.get("delta", {}) if isinstance(payload.get("delta"), dict) else {}
+ usage_payload = payload.get("usage", {}) if isinstance(payload.get("usage"), dict) else {}
+ usage = None
+ if usage_payload:
+ usage = Usage(
+ input_tokens=usage_payload.get("input_tokens"),
+ output_tokens=usage_payload.get("output_tokens"),
+ cache_read_tokens=usage_payload.get("cache_read_input_tokens"),
+ cache_write_tokens=usage_payload.get("cache_creation_input_tokens"),
+ reasoning_tokens=_reasoning_tokens(usage_payload),
+ )
+ stop_reason = delta.get("stop_reason")
+ if stop_reason is not None or usage is not None:
+ # MAP-3 (D9, 2026-09-06): this frame supplied usage (and the
+ # stop reason), so it is the end event's provider_data,
+ # verbatim; the bare message_stop contributes nothing.
+ yield StreamEndEvent(
+ finish_reason=_finish_reason(stop_reason) if stop_reason is not None else None,
+ usage=usage,
+ provider_data=payload,
+ )
+ return
+ if et == "message_stop":
+ yield StreamEndEvent()
+ return
+ if et == "error":
+ err = payload.get("error")
+ if isinstance(err, dict):
+ provider_code = str(err.get("type") or err.get("code") or payload.get("code") or "provider")
+ message = str(err.get("message") or payload.get("message") or "")
+ else:
+ provider_code = str(payload.get("code") or payload.get("error_type") or "provider")
+ message = str(payload.get("message") or "")
+ yield StreamErrorEvent(error=self._error_detail(provider_code, message))
+
+ # ─── Other endpoints ────────────────────────────────────────────
+
+ # ─── Live model listing (provisional endpoint) ──────────────────────
+
+ def _models_request(self):
+ # limit=1000 is the endpoint maximum; the catalog fits in one page
+ # today (has_more=false observed live 2026-08-31).
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/models",
+ params={"limit": 1000},
+ headers=self._headers(),
+ read_timeout=30.0,
+ )
+
+ def _models_from_body(self, body: str):
+ data = json.loads(body)
+ entries = data.get("data") if isinstance(data, dict) else None
+ return model_infos_from_entries(
+ entries,
+ provider=self.provider,
+ api_family="anthropic_messages",
+ id_of=lambda entry: entry.get("id"),
+ )
+
+ # ─── File hooks (Files API, GA) ──────────────────────────────
+ #
+ # Wire shapes verified live 2026-08-31 (curl-fixtures/files-2026-08-31/):
+ # multipart/form-data upload with NO beta header (GA), file objects
+ # carry mime_type / size_bytes / downloadable verbatim, list paginates
+ # with an opaque `next_page` token passed back as `?page=`, download
+ # is refused for non-tool-generated files (400, forwarded typed).
+
+ def _file_upload_request(self, request: FileUploadRequest) -> TransportRequest:
+ content_type, body = multipart_form_body(
+ fields=[(k, str(v)) for k, v in (request.extensions or {}).items()],
+ files=[("file", request.filename, request.media_type, request.bytes)],
+ )
+ headers = self._headers()
+ headers["content-type"] = content_type
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/files",
+ headers=list(headers.items()),
+ body=body,
+ read_timeout=300.0,
+ )
+
+ def _file_info_from_body(self, body: str) -> FileInfo:
+ return self._file_info(json.loads(body))
+
+ def _file_info(self, data: dict[str, Any]) -> FileInfo:
+ file_id = data.get("id")
+ if not isinstance(file_id, str) or not file_id:
+ raise ProviderError("anthropic: file object carries no id", provider=self.provider)
+ filename = data.get("filename")
+ mime = data.get("mime_type")
+ return FileInfo(
+ id=file_id,
+ filename=filename if isinstance(filename, str) and filename else None,
+ media_type=mime if isinstance(mime, str) and mime else None,
+ size_bytes=data.get("size_bytes") if isinstance(data.get("size_bytes"), int) else None,
+ created_at=iso_utc(data.get("created_at")),
+ expires_at=iso_utc(data.get("expires_at")),
+ readiness="ready", # Anthropic files have no processing state
+ downloadable=data.get("downloadable") if isinstance(data.get("downloadable"), bool) else None,
+ provider_data=data,
+ )
+
+ def _file_get_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ params: dict[str, Any] = {"limit": limit}
+ if cursor is not None:
+ params["page"] = cursor
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files",
+ params=params, headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_page_from_list_body(self, body: str) -> FilePage:
+ data = json.loads(body)
+ entries = data.get("data") if isinstance(data.get("data"), list) else []
+ items = tuple(self._file_info(entry) for entry in entries if isinstance(entry, dict))
+ cursor = data.get("next_page")
+ return FilePage(items=items, next_cursor=cursor if isinstance(cursor, str) and cursor else None)
+
+ def _file_delete_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="DELETE", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_download_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}/content",
+ headers=self._headers(), read_timeout=300.0,
+ )
+
+ # ─── Batch hooks (Message Batches API) ────────────────────────
+
+ def _batch_submit_request(self, request: BatchRequest, upload_body: dict[str, Any] | None) -> TransportRequest:
+ if request.label is not None:
+ raise UnsupportedFeatureError(
+ "anthropic: batch labels are not supported — the Message Batches "
+ "create body has no metadata field (verified live 2026-08-31); "
+ "submit without a label and correlate by id",
+ provider=self.provider,
+ )
+ payload = {
+ "requests": [
+ {"custom_id": str(i), "params": self._payload(nested, stream=False)}
+ for i, nested in enumerate(request.requests)
+ ],
+ **(request.extensions or {}),
+ }
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/messages/batches",
+ headers=self._headers(),
+ payload=payload,
+ read_timeout=120.0,
+ )
+
+ def _batch_job_from_body(self, body: str) -> BatchJobInfo:
+ return self._batch_job_info(json.loads(body))
+
+ def _batch_job_info(self, data: dict[str, Any]) -> BatchJobInfo:
+ batch_id = data.get("id")
+ if not isinstance(batch_id, str) or not batch_id:
+ raise ProviderError("anthropic: batch object carries no id", provider=self.provider)
+ return BatchJobInfo(
+ id=batch_id,
+ status=_anthropic_batch_status(data),
+ created_at=iso_utc(data.get("created_at")),
+ provider_data=data,
+ )
+
+ def _batch_status_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/messages/batches/{path_id(batch_id)}",
+ headers=self._headers(),
+ read_timeout=60.0,
+ )
+
+ def _batch_cancel_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/messages/batches/{path_id(batch_id)}/cancel",
+ headers=self._headers(),
+ read_timeout=60.0,
+ )
+
+ def _batch_result_fetches(self, status_body: dict[str, Any]) -> tuple[TransportRequest, ...]:
+ url = status_body.get("results_url")
+ if not isinstance(url, str) or not url:
+ raise ProviderError("anthropic: ended batch carries no results_url", provider=self.provider)
+ return (self._emit(method="GET", url=url, headers=self._headers(), read_timeout=300.0),)
+
+ def _batch_entries(self, status_body: dict[str, Any], fetched: tuple[str, ...]) -> tuple[BatchEntry, ...]:
+ entries: list[BatchEntry] = []
+ for line in fetched[0].splitlines():
+ if not line.strip():
+ continue
+ item = json.loads(line)
+ index = int(str(item.get("custom_id")))
+ result = item.get("result") or {}
+ rtype = str(result.get("type") or "")
+ if rtype == "succeeded":
+ message = result.get("message") or {}
+ response = self.parse_response(
+ batch_entry_request(message.get("model")), batch_entry_http(message)
+ )
+ entries.append(BatchEntry(index=index, outcome="succeeded", response=response))
+ elif rtype == "errored":
+ raw = result.get("error") or {}
+ envelope = raw if isinstance(raw, dict) and "error" in raw else {"error": raw}
+ err = self.normalize_error(400, json.dumps(envelope))
+ entries.append(BatchEntry(
+ index=index,
+ outcome="errored",
+ error=ErrorDetail(
+ code=canonical_error_code(err),
+ message=err.message or "batch entry errored",
+ provider_code=err.provider_code,
+ ),
+ ))
+ elif rtype == "canceled":
+ entries.append(BatchEntry(index=index, outcome="cancelled"))
+ elif rtype == "expired":
+ entries.append(BatchEntry(index=index, outcome="expired"))
+ else:
+ entries.append(BatchEntry(
+ index=index,
+ outcome="errored",
+ error=ErrorDetail(code="provider", message=f"unrecognized batch result type {rtype!r}"),
+ ))
+ return tuple(sorted(entries, key=lambda e: e.index))
+
+ def _batch_list_request(self, limit: int) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/messages/batches",
+ params={"limit": int(limit)},
+ headers=self._headers(),
+ read_timeout=60.0,
+ )
+
+ def _batch_jobs_from_list_body(self, body: str) -> tuple[BatchJobInfo, ...]:
+ data = json.loads(body)
+ items = data.get("data") if isinstance(data, dict) else None
+ return tuple(self._batch_job_info(item) for item in (items or []) if isinstance(item, dict))
diff --git a/dspy/_vendor/lm15/providers/async_base.py b/dspy/_vendor/lm15/providers/async_base.py
new file mode 100644
index 000000000..f8de27102
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/async_base.py
@@ -0,0 +1,860 @@
+"""Async mirror provider LMs.
+
+Each Async* class is a perfect mirror of its sync sibling: same constructor
+fields, same canonical Request in, same canonical Response / StreamEvents
+out — ``await`` is the only user-visible difference.
+
+Design (see docs/design-rationale.md, "Async"): composition, not
+inheritance. Subclassing the sync adapter and overriding sync methods with
+async ones would be a typing violation (``complete`` would no longer be
+substitutable). Instead each async class owns the async transport and
+delegates ALL pure mapping — build_request, parse_response,
+parse_stream_events, normalize_error, payload/header helpers — to an inner
+instance of the sync adapter class, constructed with a transport that raises
+if it is ever used: the inner adapter must never touch the network.
+"""
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+import os
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator, Callable, ClassVar, Mapping, Protocol, TypeVar
+
+from ..errors import (
+ ProviderError,
+ TransportError as LM15TransportError,
+ UnsupportedFeatureError,
+)
+from ..features import EndpointSupport, ProviderManifest
+from ..sse import aparse_sse
+from ..transports import (
+ AsyncTransportResponse,
+ StdlibAsyncTransport,
+ TransportRequest,
+ TransportError as NetworkTransportError,
+)
+from ..types import (
+ VideoGenerationRequest,
+ SpeechGenerationRequest,
+ BatchRequest,
+ FileUploadRequest,
+ ImageGenerationRequest,
+ LiveConfig,
+ Request,
+ Response,
+ StreamEvent,
+)
+from .anthropic import AnthropicLM
+from .base import BaseProviderLM, Credential, HttpResponse
+from .claude_code import DEFAULT_CLAUDE_CODE_VERSION, ClaudeCodeLM
+from .gemini import GeminiLM
+from .openai import OpenAILM
+from .openai_chat import OpenAIChatLM
+from .openai_codex import (
+ DEFAULT_CODEX_BASE_URL,
+ DEFAULT_CODEX_CLIENT_VERSION,
+ DEFAULT_CODEX_ORIGINATOR,
+ OpenAICodexLM,
+)
+from .xai import DEFAULT_XAI_BASE_URL, XaiLM
+
+_T = TypeVar("_T")
+
+
+class AsyncTransport(Protocol):
+ """Minimal async transport surface used by async provider LMs.
+
+ ``stream`` returns an async context manager producing an
+ :class:`AsyncTransportResponse` (StdlibAsyncTransport's shape).
+ """
+
+ def stream(self, request: TransportRequest) -> Any: ...
+
+
+def default_async_transport() -> AsyncTransport:
+ """Create the default async transport for standalone async provider LMs."""
+ return StdlibAsyncTransport()
+
+
+def _mirror_default(cls, name: str):
+ """Default value of a sync sibling's dataclass field (slots-safe)."""
+ return cls.__dataclass_fields__[name].default
+
+
+class _ForbiddenTransport:
+ """Transport for the inner sync adapter: pure mapping only, no I/O."""
+
+ def stream(self, request: TransportRequest) -> Any:
+ raise RuntimeError(
+ "inner sync adapter of an Async* provider LM must never touch the "
+ "network; all I/O goes through the async transport"
+ )
+
+
+class AsyncBaseProviderLM:
+ """Shared asynchronous provider LM implementation.
+
+ Mirrors :class:`BaseProviderLM` faithfully: build (delegated, pure) ->
+ await async transport -> parse (delegated, pure); status>=400 raises the
+ delegated normalize_error; transport errors are wrapped in
+ lm15.TransportError. Streaming applies MAP-3 via
+ :func:`lm15.result.acoalesce_stream`.
+ """
+
+ transport: AsyncTransport
+ _inner: BaseProviderLM # set by subclass __post_init__
+
+ # Mirrored metadata (subclasses override like their sync siblings).
+ provider: str = "unknown"
+ manifest: ClassVar[ProviderManifest] = ProviderManifest(provider="unknown")
+
+ @property
+ def access(self) -> ProviderManifest:
+ """The bound access policy — the inner sync adapter's."""
+ return self._inner.access
+
+ @property
+ def supports(self) -> EndpointSupport:
+ return self._inner.access.supports
+
+ @classmethod
+ def has_stored_credential(cls) -> bool:
+ from ..access import has_stored_credential
+
+ return has_stored_credential(cls.manifest)
+
+ def _mirror_binding(self) -> None:
+ """Copy what the inner adapter's access binding resolved: the
+ provider string, the credential (a per-request provider for stored
+ logins, repr-suppressed), and the base URL the policy chose."""
+ self.provider = self._inner.provider
+ self.api_key = self._inner.api_key
+ self.base_url = self._inner.base_url
+
+ async def _build(self, build: "Callable[..., _T]", *args: Any, **kwargs: Any) -> "_T":
+ """Run one of the inner adapter's request builders.
+
+ A builder invokes the credential provider (AUTH-2) inside ``_emit``.
+ A cloud-chain provider may refresh over the network, synchronously;
+ run it in a worker thread so that refresh does not block the event
+ loop (D16, 2026-09-06). A static credential needs no thread.
+ """
+ if callable(self._inner.api_key):
+ return await asyncio.to_thread(build, *args, **kwargs)
+ return build(*args, **kwargs)
+
+ async def complete(self, request: Request) -> Response:
+ req = await self._build(self._inner.build_request, request, stream=False)
+ resp = await self._send(req)
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner.parse_response(request, resp)
+
+ def stream(self, request: Request) -> AsyncIterator[StreamEvent]:
+ # MAP-3 (docs/mapping-rules.md): adapters may emit one end event per
+ # provider terminal frame; the coalescer merges them so the public
+ # stream yields exactly one final StreamEndEvent.
+ from ..result import acoalesce_stream
+
+ return acoalesce_stream(self._stream_raw(request), model=request.model)
+
+ async def _stream_raw(self, request: Request) -> AsyncIterator[StreamEvent]:
+ req = await self._build(self._inner.build_request, request, stream=True)
+ try:
+ async with self.transport.stream(req) as resp:
+ if resp.status >= 400:
+ body = await resp.read()
+ raise self._inner.normalize_error(
+ resp.status, body.decode("utf-8", errors="replace")
+ )
+ async for raw in aparse_sse(_aiter_lines(resp)):
+ for event in self._inner.parse_stream_events(request, raw):
+ if event is not None:
+ yield event
+ except NetworkTransportError as exc:
+ raise LM15TransportError(str(exc)) from exc
+
+ async def _send(self, request: TransportRequest) -> HttpResponse:
+ try:
+ async with self.transport.stream(request) as resp:
+ body = await resp.read()
+ return HttpResponse(
+ status=resp.status,
+ reason=resp.reason,
+ headers=resp.headers,
+ body=body,
+ http_version=resp.http_version,
+ )
+ except NetworkTransportError as exc:
+ raise LM15TransportError(str(exc)) from exc
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ return self._inner.normalize_error(status, body)
+
+ async def list_models(self):
+ """Async mirror of BaseProviderLM.list_models (canonical ModelInfo)."""
+ resp = await self._send(await self._build(self._inner._models_request))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._models_from_body(resp.text())
+
+ # ── Batch: async drivers over the sync adapter's pure hooks ──────
+
+ async def batch_submit(self, request: "BatchRequest"):
+ upload_body = None
+ upload_req = await self._build(self._inner._batch_upload_request, request)
+ if upload_req is not None:
+ resp = await self._send(upload_req)
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ upload_body = resp.json()
+ resp = await self._send(await self._build(self._inner._batch_submit_request, request, upload_body))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._batch_job_from_body(resp.text())
+
+ async def batch_status(self, batch_id: str):
+ resp = await self._send(await self._build(self._inner._batch_status_request, batch_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._batch_job_from_body(resp.text())
+
+ async def batch_results(self, batch_id: str):
+ from ..types import BATCH_TERMINAL_STATUSES
+
+ resp = await self._send(await self._build(self._inner._batch_status_request, batch_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ job = self._inner._batch_job_from_body(resp.text())
+ if job.status not in BATCH_TERMINAL_STATUSES:
+ raise ValueError(
+ f"batch {batch_id} is not finished (status={job.status!r}); "
+ f"await wait() or poll batch_status() until done"
+ )
+ status_body = resp.json()
+ texts = []
+ for fetch in await self._build(self._inner._batch_result_fetches, status_body):
+ fetched = await self._send(fetch)
+ if fetched.status >= 400:
+ raise self._inner.normalize_error(fetched.status, fetched.text())
+ texts.append(fetched.text())
+ return self._inner._batch_entries(status_body, tuple(texts))
+
+ async def batch_cancel(self, batch_id: str):
+ resp = await self._send(await self._build(self._inner._batch_cancel_request, batch_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._batch_job_from_body(resp.text())
+
+ async def batch_list(self, limit: int = 20):
+ resp = await self._send(await self._build(self._inner._batch_list_request, limit))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._batch_jobs_from_list_body(resp.text())
+
+ async def batch(self, requests, *, model: str | None = None, label: str | None = None,
+ extensions=None):
+ """Third execution mode, async twin: returns an AsyncBatchJob."""
+ from ..batch import AsyncBatchJob
+
+ if isinstance(requests, BatchRequest):
+ request = requests
+ else:
+ request = BatchRequest(model=model, requests=tuple(requests), label=label, extensions=extensions)
+ return AsyncBatchJob(self, await self.batch_submit(request))
+
+ async def batch_job(self, batch_id: str):
+ from ..batch import AsyncBatchJob
+
+ return AsyncBatchJob(self, await self.batch_status(batch_id))
+
+ async def batches(self, limit: int = 20):
+ from ..batch import AsyncBatchJob
+
+ return tuple(AsyncBatchJob(self, info) for info in await self.batch_list(limit))
+
+ # ── Cache resources: async drivers over the sync adapter's pure hooks ──
+
+ async def cache_create(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None):
+ self._inner._check_cache_prefix(prefix, ttl_seconds)
+ resp = await self._send(await self._build(self._inner._cache_create_request, prefix, ttl_seconds, label))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._cache_info_from_body(resp.text())
+
+ async def cache_get(self, cache_id: str):
+ resp = await self._send(await self._build(self._inner._cache_get_request, cache_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._cache_info_from_body(resp.text())
+
+ async def cache_list(self, limit: int = 20, cursor: str | None = None):
+ resp = await self._send(await self._build(self._inner._cache_list_request, limit, cursor))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._cache_page_from_list_body(resp.text())
+
+ async def cache_delete(self, cache_id: str) -> None:
+ resp = await self._send(await self._build(self._inner._cache_delete_request, cache_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+
+ async def cache_update(self, cache_id: str, *, ttl_seconds: int):
+ if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or ttl_seconds <= 0:
+ raise ValueError("ttl_seconds must be a positive int")
+ resp = await self._send(await self._build(self._inner._cache_update_request, cache_id, ttl_seconds))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._cache_info_from_body(resp.text())
+
+ async def cache(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None):
+ from ..types import CachedPrefix
+
+ if self.supports.caches:
+ return CachedPrefix(prefix, await self.cache_create(prefix, ttl_seconds=ttl_seconds, label=label))
+ self._inner._check_cache_prefix(prefix, ttl_seconds)
+ return CachedPrefix(prefix)
+
+ # ── Files: async drivers over the sync adapter's pure hooks ──────
+
+ async def file_upload(self, request: "FileUploadRequest"):
+ resp = await self._send(await self._build(self._inner._file_upload_request, request))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._file_info_from_body(resp.text())
+
+ async def file_get(self, file_id: str):
+ resp = await self._send(await self._build(self._inner._file_get_request, file_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._file_info_from_body(resp.text())
+
+ async def file_list(self, limit: int = 20, cursor: str | None = None):
+ resp = await self._send(await self._build(self._inner._file_list_request, limit, cursor))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._file_page_from_list_body(resp.text())
+
+ async def file_delete(self, file_id: str) -> None:
+ resp = await self._send(await self._build(self._inner._file_delete_request, file_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+
+ async def file_download(self, file_id: str) -> bytes:
+ resp = await self._send(await self._build(self._inner._file_download_request, file_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return resp.body
+
+ async def file_wait_ready(self, file_id: str, poll_every: float = 2.0, timeout: float | None = None):
+ import asyncio
+ import time as _time
+
+ deadline = None if timeout is None else _time.monotonic() + timeout
+ info = await self.file_get(file_id)
+ while info.readiness == "pending":
+ if deadline is not None and _time.monotonic() >= deadline:
+ raise TimeoutError(f"file {file_id} still pending after {timeout}s")
+ await asyncio.sleep(poll_every)
+ info = await self.file_get(file_id)
+ return info
+
+ async def aclose(self) -> None:
+ aclose = getattr(self.transport, "aclose", None)
+ if callable(aclose):
+ await aclose()
+
+ async def __aenter__(self):
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb) -> None:
+ await self.aclose()
+
+ # ── Non-chat endpoints: sync-only for now (honest surface) ──────
+
+ def _async_unsupported(self, endpoint: str) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(
+ f"{self.provider}: {endpoint}: use the sync adapter for this "
+ "endpoint (async endpoints planned)",
+ provider=self.provider,
+ )
+
+ def live(self, config: LiveConfig):
+ raise self._async_unsupported("live")
+
+ # ── Video generation: async drivers over the sync adapter's pure hooks ──
+
+ async def video_submit(self, request: "VideoGenerationRequest"):
+ resp = await self._send(await self._build(self._inner._video_submit_request, request))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._video_job_from_body(resp.text())
+
+ async def video_status(self, video_id: str):
+ resp = await self._send(await self._build(self._inner._video_status_request, video_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._video_job_from_body(resp.text(), video_id)
+
+ async def video_result(self, video_id: str):
+ from ..types import VIDEO_TERMINAL_STATUSES
+
+ resp = await self._send(await self._build(self._inner._video_status_request, video_id))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ job = self._inner._video_job_from_body(resp.text(), video_id)
+ if job.status not in VIDEO_TERMINAL_STATUSES:
+ raise ValueError(
+ f"video {video_id} is not finished (status={job.status!r}); "
+ f"wait() or poll video_status() until done"
+ )
+ status_body = resp.json()
+ fetch = await self._build(self._inner._video_result_fetch, status_body)
+ fetched = None
+ if fetch is not None:
+ fetched = await self._send(fetch)
+ if fetched.status >= 400:
+ raise self._inner.normalize_error(fetched.status, fetched.text())
+ return self._inner._video_part(status_body, fetched)
+
+ async def video_list(self, limit: int = 20, model: str | None = None):
+ resp = await self._send(await self._build(self._inner._video_list_request, limit, model))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._video_jobs_from_list_body(resp.text())
+
+ async def video_generate(self, request: "VideoGenerationRequest"):
+ from ..video_jobs import AsyncVideoJob
+
+ return AsyncVideoJob(self, await self.video_submit(request))
+
+ async def video_job(self, video_id: str):
+ from ..video_jobs import AsyncVideoJob
+
+ return AsyncVideoJob(self, await self.video_status(video_id))
+
+ async def video_jobs(self, limit: int = 20, model: str | None = None):
+ from ..video_jobs import AsyncVideoJob
+
+ return tuple(AsyncVideoJob(self, info) for info in await self.video_list(limit, model))
+
+ # ── Media generation: async drivers over the sync adapter's pure hooks ──
+
+ async def image_generate(self, request: ImageGenerationRequest):
+ resp = await self._send(await self._build(self._inner._image_generate_request, request))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._image_generation_from_response(request, resp)
+
+ async def speech_generate(self, request: SpeechGenerationRequest):
+ resp = await self._send(await self._build(self._inner._speech_generate_request, request))
+ if resp.status >= 400:
+ raise self._inner.normalize_error(resp.status, resp.text())
+ return self._inner._speech_generation_from_response(request, resp)
+
+
+async def _aiter_lines(resp: AsyncTransportResponse) -> AsyncIterator[bytes]:
+ aiter_lines = getattr(resp, "aiter_lines", None)
+ if aiter_lines is not None:
+ async for line in aiter_lines():
+ yield line
+ return
+ buf = bytearray()
+ async for chunk in resp:
+ if not chunk:
+ continue
+ buf.extend(chunk)
+ while True:
+ idx = buf.find(b"\n")
+ if idx < 0:
+ break
+ yield bytes(buf[: idx + 1])
+ del buf[: idx + 1]
+ if buf:
+ yield bytes(buf)
+
+
+# ─── Mirror classes ──────────────────────────────────────────────────
+
+
+@dataclass(slots=True)
+class AsyncOpenAILM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = "https://api.openai.com/v1"
+ profile: Any | None = None
+ compat: Any | None = field(default=None, kw_only=True)
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = field(default=None, kw_only=True)
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False, kw_only=True)
+ account_id: str | None = None
+
+ async def live(self, config: LiveConfig):
+ self._inner._require("live")
+ # Native async websocket (websockets.asyncio) — not a thread
+ # wrapper: a blocked sync recv in a worker thread cannot be
+ # cancelled from the event loop, and cancellation is the heart
+ # of realtime. Codecs are the inner adapter's pure functions.
+ import json as _json
+
+ from ..live import AsyncWebSocketLiveSession, require_websocket_async_connect
+
+ connect = require_websocket_async_connect()
+ inner = self._inner
+ ws = await connect(inner._live_url(config.model), additional_headers=inner._live_headers())
+ for frame in inner._live_setup_frames(config):
+ await ws.send(_json.dumps(frame))
+ return AsyncWebSocketLiveSession(
+ ws=ws,
+ encode_event=inner._live_encoder(config),
+ decode_event=inner._decode_live_server_event,
+ )
+
+ provider: str = field(default="openai", init=False)
+ manifest: ClassVar[ProviderManifest] = OpenAILM.manifest
+
+ _inner: OpenAILM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = OpenAILM(
+ api_key=self.api_key,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ profile=self.profile,
+ compat=self.compat,
+ access=self.access,
+ credentials_path=self.credentials_path,
+ settings=self.settings,
+ clock=self.clock,
+ account_id=self.account_id,
+ )
+ self._mirror_binding()
+ # The sync sibling resolves a preset name (and may supply that
+ # server's default base_url); mirror the resolved values.
+ self.base_url = self._inner.base_url
+
+
+@dataclass(slots=True)
+class AsyncAnthropicLM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = "https://api.anthropic.com/v1"
+ api_version: str = "2023-06-01"
+ compat: Any | None = None
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="anthropic", init=False)
+ manifest: ClassVar[ProviderManifest] = AnthropicLM.manifest
+
+ _inner: AnthropicLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = AnthropicLM(
+ api_key=self.api_key,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ api_version=self.api_version,
+ compat=self.compat,
+ access=self.access,
+ credentials_path=self.credentials_path,
+ settings=self.settings,
+ clock=self.clock,
+ )
+ self._mirror_binding()
+ # The sync sibling resolves compat presets (and that server's default
+ # base_url); mirror the resolved values, as AsyncOpenAIChatLM does.
+ self.base_url = self._inner.base_url
+ self.compat = self._inner.compat
+
+
+@dataclass(slots=True)
+class AsyncGeminiLM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = "https://generativelanguage.googleapis.com/v1beta"
+ upload_base_url: str = "https://generativelanguage.googleapis.com/upload/v1beta"
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="gemini", init=False)
+ manifest: ClassVar[ProviderManifest] = GeminiLM.manifest
+
+ _inner: GeminiLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = GeminiLM(
+ api_key=self.api_key,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ upload_base_url=self.upload_base_url,
+ access=self.access,
+ credentials_path=self.credentials_path,
+ settings=self.settings,
+ clock=self.clock,
+ )
+ self._mirror_binding()
+
+ async def live(self, config: LiveConfig):
+ self._inner._require("live")
+ # Native async twin of GeminiLM.live: same pure setup frame,
+ # encoder, and setup-status classifier; only the socket awaits.
+ import json as _json
+
+ from ..live import AsyncWebSocketLiveSession, require_websocket_async_connect
+
+ connect = require_websocket_async_connect()
+ inner = self._inner
+ ws = await connect(inner._live_url())
+ for frame in inner._live_setup_frames(config):
+ await ws.send(_json.dumps(frame))
+ while not inner._live_setup_status(await ws.recv()):
+ pass
+ return AsyncWebSocketLiveSession(
+ ws=ws,
+ encode_event=inner._live_encoder(config),
+ decode_event=inner._decode_live_server_event,
+ )
+
+
+@dataclass(slots=True)
+class AsyncOpenAIChatLM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = _mirror_default(OpenAIChatLM, "base_url")
+ compat: Any | None = None
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="openai-chat", init=False)
+ manifest: ClassVar[ProviderManifest] = OpenAIChatLM.manifest
+
+ _inner: OpenAIChatLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = OpenAIChatLM(
+ api_key=self.api_key,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ compat=self.compat,
+ access=self.access,
+ credentials_path=self.credentials_path,
+ settings=self.settings,
+ clock=self.clock,
+ )
+ self._mirror_binding()
+ # The sync sibling's __post_init__ resolves compat presets (and may
+ # supply that server's default base_url); mirror the resolved values.
+ self.base_url = self._inner.base_url
+ self.compat = self._inner.compat
+
+ def request_from_openai_chat(self, body: "Mapping[str, Any]") -> Request:
+ """Pure; the sync sibling's, under this adapter's compat (MAP-12)."""
+ return self._inner.request_from_openai_chat(body)
+
+ def response_from_openai_chat(self, body: "Mapping[str, Any]", *, model: str | None = None, choice: int | None = None) -> Response:
+ """Pure; the sync sibling's reader under this adapter's provider name."""
+ return self._inner.response_from_openai_chat(body, model=model, choice=choice)
+
+
+# ─── Subscription mirrors (Claude Code / Codex CLI OAuth) ────────────
+#
+# Same composition pattern: the inner sync adapter validates the local OAuth
+# credential at construction time (typed, re-login-guided errors), then
+# re-resolves it per request so long-lived clients stay fresh. Per-request
+# resolution is a local file read; a refresh, when the token has expired, is
+# one blocking token-endpoint call inside the sync mapping layer. Credential
+# fields are repr-suppressed so secrets never leak.
+
+
+@dataclass(slots=True)
+class AsyncClaudeCodeLM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = None
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = "https://api.anthropic.com/v1"
+ api_version: str = "2023-06-01"
+ claude_code_version: str = DEFAULT_CLAUDE_CODE_VERSION
+
+ # Not constructor params on the sync sibling either (it is not a dataclass).
+ provider: str = field(default="claude-code", init=False)
+ manifest: ClassVar[ProviderManifest] = ClaudeCodeLM.manifest
+
+ _inner: ClaudeCodeLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = ClaudeCodeLM(
+ api_key=self.api_key,
+ credentials_path=self.credentials_path,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ api_version=self.api_version,
+ claude_code_version=self.claude_code_version,
+ )
+ self.api_key = self._inner.api_key # static key or per-request credential provider (repr-suppressed)
+
+ # Files are an API-key surface; the subscription credential does not
+ # carry them. Block every inherited async driver, not just upload.
+ def file_upload(self, request: FileUploadRequest):
+ return self._inner.file_upload(request) # raises UnsupportedFeatureError
+
+ def file_get(self, file_id: str):
+ return self._inner.file_get(file_id) # raises UnsupportedFeatureError
+
+ def file_list(self, limit: int = 20, cursor: str | None = None):
+ return self._inner.file_list(limit, cursor) # raises UnsupportedFeatureError
+
+ def file_delete(self, file_id: str):
+ return self._inner.file_delete(file_id) # raises UnsupportedFeatureError
+
+ def file_download(self, file_id: str):
+ return self._inner.file_download(file_id) # raises UnsupportedFeatureError
+
+ # Batch is an API-key surface; the subscription credential does not
+ # carry it. Block every inherited async driver, not just submit.
+ def batch_submit(self, request: BatchRequest):
+ return self._inner.batch_submit(request) # raises UnsupportedFeatureError
+
+ def batch_status(self, batch_id: str):
+ return self._inner.batch_status(batch_id) # raises UnsupportedFeatureError
+
+ def batch_results(self, batch_id: str):
+ return self._inner.batch_results(batch_id) # raises UnsupportedFeatureError
+
+ def batch_cancel(self, batch_id: str):
+ return self._inner.batch_cancel(batch_id) # raises UnsupportedFeatureError
+
+ def batch_list(self, limit: int = 20):
+ return self._inner.batch_list(limit) # raises UnsupportedFeatureError
+
+ def live(self, config: LiveConfig):
+ return self._inner.live(config) # raises UnsupportedFeatureError
+
+
+@dataclass(slots=True)
+class AsyncOpenAICodexLM(AsyncBaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ account_id: str | None = None
+ auth_path: "str | os.PathLike[str] | None" = None
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = DEFAULT_CODEX_BASE_URL
+ originator: str = DEFAULT_CODEX_ORIGINATOR
+ client_version: str = DEFAULT_CODEX_CLIENT_VERSION
+
+ # Not constructor params on the sync sibling either (it is not a dataclass).
+ provider: str = field(default="openai-codex", init=False)
+ manifest: ClassVar[ProviderManifest] = OpenAICodexLM.manifest
+
+ _inner: OpenAICodexLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = OpenAICodexLM(
+ api_key=self.api_key,
+ account_id=self.account_id,
+ auth_path=self.auth_path,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ originator=self.originator,
+ client_version=self.client_version,
+ )
+ self.api_key = self._inner.api_key # static key or per-request credential provider (repr-suppressed)
+ self.account_id = self._inner.account_id
+
+ async def complete(self, request: Request) -> Response:
+ # Mirror of OpenAICodexLM.complete: the Codex subscription backend is
+ # streaming-first; materialize the (coalesced) stream.
+ from ..result import amaterialize_response
+
+ return await amaterialize_response(self.stream(request), request)
+
+ def live(self, config: LiveConfig):
+ return self._inner.live(config) # raises UnsupportedFeatureError
+
+ # Files are an API-key surface; the subscription credential does not
+ # carry them. Block every inherited async driver, not just upload.
+ def file_upload(self, request: FileUploadRequest):
+ return self._inner.file_upload(request) # raises UnsupportedFeatureError
+
+ def file_get(self, file_id: str):
+ return self._inner.file_get(file_id) # raises UnsupportedFeatureError
+
+ def file_list(self, limit: int = 20, cursor: str | None = None):
+ return self._inner.file_list(limit, cursor) # raises UnsupportedFeatureError
+
+ def file_delete(self, file_id: str):
+ return self._inner.file_delete(file_id) # raises UnsupportedFeatureError
+
+ def file_download(self, file_id: str):
+ return self._inner.file_download(file_id) # raises UnsupportedFeatureError
+
+ # Batch is an API-key surface; the subscription credential does not
+ # carry it. Block every inherited async driver, not just submit.
+ def batch_submit(self, request: BatchRequest):
+ return self._inner.batch_submit(request) # raises UnsupportedFeatureError
+
+ def batch_status(self, batch_id: str):
+ return self._inner.batch_status(batch_id) # raises UnsupportedFeatureError
+
+ def batch_results(self, batch_id: str):
+ return self._inner.batch_results(batch_id) # raises UnsupportedFeatureError
+
+ def batch_cancel(self, batch_id: str):
+ return self._inner.batch_cancel(batch_id) # raises UnsupportedFeatureError
+
+ def batch_list(self, limit: int = 20):
+ return self._inner.batch_list(limit) # raises UnsupportedFeatureError
+
+ def image_generate(self, request: ImageGenerationRequest):
+ return self._inner.image_generate(request) # raises UnsupportedFeatureError
+
+ def speech_generate(self, request: SpeechGenerationRequest):
+ return self._inner.speech_generate(request) # raises UnsupportedFeatureError
+
+
+@dataclass(slots=True)
+class AsyncXaiLM(AsyncBaseProviderLM):
+ """Async mirror of :class:`XaiLM` (subscription OAuth or bearer key)."""
+
+ api_key: Credential | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = None
+ transport: AsyncTransport = field(default_factory=default_async_transport)
+ base_url: str = DEFAULT_XAI_BASE_URL
+
+ # Not constructor params on the sync sibling either.
+ provider: str = field(default="xai", init=False)
+ manifest: ClassVar[ProviderManifest] = XaiLM.manifest
+ # Same offline probe as the sync sibling (oauth-unless-explicit policy).
+ has_stored_credential: ClassVar = XaiLM.has_stored_credential
+
+ _inner: XaiLM = field(init=False, repr=False, compare=False)
+
+ def __post_init__(self) -> None:
+ self._inner = XaiLM(
+ api_key=self.api_key,
+ credentials_path=self.credentials_path,
+ transport=_ForbiddenTransport(),
+ base_url=self.base_url,
+ )
+ self.api_key = self._inner.api_key # static key or per-request credential provider (repr-suppressed)
+
+
+__all__ = [
+ "AsyncBaseProviderLM",
+ "AsyncTransport",
+ "AsyncOpenAILM",
+ "AsyncAnthropicLM",
+ "AsyncGeminiLM",
+ "AsyncOpenAIChatLM",
+ "AsyncClaudeCodeLM",
+ "AsyncOpenAICodexLM",
+ "AsyncXaiLM",
+ "default_async_transport",
+]
diff --git a/dspy/_vendor/lm15/providers/base.py b/dspy/_vendor/lm15/providers/base.py
new file mode 100644
index 000000000..4c32b417b
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/base.py
@@ -0,0 +1,1073 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Iterator, Mapping, Protocol, Sequence
+
+if TYPE_CHECKING: # pragma: no cover - import cycle guard for annotations
+ from ..batch import BatchJob
+ from ..video_jobs import VideoJob
+
+from ..errors import (
+ AuthError,
+ NotConfiguredError,
+ ProviderError,
+ TransportError as LM15TransportError,
+ UnsupportedFeatureError,
+ map_http_error,
+ with_credential_hint,
+)
+from ..credentials import AwsCredentials, CredentialLike, CredentialValue, coerce_credential
+from ..features import EndpointSupport, ProviderManifest
+from ..models import ModelInfo
+from ..protocols import LiveSession
+from ..sse import SSEEvent, parse_sse
+from ..transports import TransportRequest
+from ..transports import TransportResponse
+from ..transports import StdlibTransport
+from ..transports import TransportError as NetworkTransportError
+from ..types import (
+ CachedPrefix,
+ CacheInfo,
+ CachePage,
+ Config,
+ VIDEO_TERMINAL_STATUSES,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ VideoPart,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ BATCH_TERMINAL_STATUSES,
+ BatchEntry,
+ BatchJobInfo,
+ BatchRequest,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ LiveConfig,
+ Request,
+ Response,
+ StreamEvent,
+)
+
+
+class SyncTransport(Protocol):
+ """Minimal sync transport surface used by provider LMs."""
+
+ def stream(self, request: TransportRequest) -> TransportResponse: ...
+
+
+def default_transport() -> SyncTransport:
+ """Create the default sync transport for standalone provider LMs."""
+ return StdlibTransport()
+
+
+# A credential is a static key string, an AUTH-2 credential value (ApiKey,
+# BearerToken, AwsCredentials — lm15.credentials), or a zero-argument
+# provider callable returning either. Providers are invoked at
+# request-build time, once per request, so rotating credentials (OAuth
+# refresh, cloud chains) stay fresh in long-lived clients. Caching and
+# refreshing belongs to the provider callable (AUTH-2); the adapter never
+# caches what it returns.
+Credential = CredentialLike
+
+
+def resolve_credential_value(credential: Credential) -> CredentialValue:
+ """Invoke a provider callable if needed and coerce to a credential value."""
+ raw = credential() if callable(credential) else credential
+ return coerce_credential(raw)
+
+
+def resolve_credential(credential: Credential) -> str:
+ """The bearer/key STRING of a credential — the pre-2026-09-03 shape the
+ dialects' header code reads. AWS credentials have no single string;
+ they travel as a SigV4 signature (``_emit``), never through here."""
+ value = resolve_credential_value(credential)
+ if isinstance(value, AwsCredentials):
+ raise NotConfiguredError("AWS credentials cannot be sent as a header value; the door must accept sigv4")
+ return value.value
+
+
+def _retry_after_seconds(value: str | None) -> float | None:
+ """Parse an HTTP Retry-After header: delta-seconds or an HTTP-date."""
+ if not value:
+ return None
+ try:
+ seconds = float(value)
+ except ValueError:
+ pass
+ else:
+ return seconds if seconds >= 0 else None
+ from datetime import datetime, timezone
+ from email.utils import parsedate_to_datetime
+
+ try:
+ when = parsedate_to_datetime(value)
+ except Exception:
+ return None
+ if when is None:
+ return None
+ if when.tzinfo is None:
+ when = when.replace(tzinfo=timezone.utc)
+ return max(0.0, (when - datetime.now(timezone.utc)).total_seconds())
+
+
+def _attach_retry_after(error: ProviderError, headers: "list[tuple[str, str]] | None") -> None:
+ """Populate error.retry_after from a Retry-After header.
+
+ A provider-body-derived value (set by the adapter's normalize_error)
+ always wins; the header only fills the gap."""
+ if getattr(error, "retry_after", None) is not None:
+ return
+ value = None
+ for key, val in headers or []:
+ if key.lower() == "retry-after":
+ value = val
+ break
+ seconds = _retry_after_seconds(value)
+ if seconds is not None:
+ error.retry_after = seconds
+
+
+@dataclass(frozen=True, slots=True)
+class HttpResponse:
+ """Buffered provider-level HTTP response.
+
+ The stdlib transport is streaming-first. LMs that implement ordinary
+ request/response endpoints buffer the body into this small value object so
+ their parsing code can stay pure and easy to test.
+ """
+
+ status: int
+ reason: str
+ headers: list[tuple[str, str]]
+ body: bytes
+ http_version: str = "HTTP/1.1"
+
+ def header(self, name: str) -> str | None:
+ lname = name.lower()
+ for key, value in self.headers:
+ if key.lower() == lname:
+ return value
+ return None
+
+ def headers_all(self, name: str) -> list[str]:
+ lname = name.lower()
+ return [value for key, value in self.headers if key.lower() == lname]
+
+ def text(self) -> str:
+ return self.body.decode("utf-8", errors="replace")
+
+ def json(self):
+ return json.loads(self.body)
+
+
+class ProviderDialect(Protocol):
+ provider: str
+ supports: EndpointSupport
+ manifest: ProviderManifest
+
+ def build_request(self, request: Request, stream: bool) -> TransportRequest: ...
+
+ def parse_response(self, request: Request, response: HttpResponse) -> Response: ...
+
+ def parse_stream_events(self, request: Request, raw_event: SSEEvent) -> Iterator[StreamEvent]: ...
+
+ def normalize_error(self, status: int, body: str) -> ProviderError: ...
+
+
+_SURFACE_WORD = {
+ "files": "files",
+ "batches": "batch",
+ "images": "image generation",
+ "speech": "speech generation",
+ "video": "video generation",
+ "live": "live",
+ "caches": "caches",
+ "models": "model listing",
+}
+
+
+class BaseProviderLM:
+ """Shared synchronous provider LM implementation.
+
+ An adapter is a dialect (the class) bound to an access policy (a value,
+ ``lm15.access``): the policy says which credential travels in which
+ header, which static headers ride along, which endpoint surfaces this
+ access path carries, and which backend variant the dialect must switch
+ on. ``manifest`` is the class's default policy; ``access`` is the bound
+ one. Dialect code reads ``self.access`` at a small set of stated points
+ and never carries a subclass per access path.
+ """
+
+ transport: SyncTransport
+ provider: str = "unknown"
+ manifest: ClassVar[ProviderManifest] = ProviderManifest(provider="unknown")
+ access: ProviderManifest
+ account_id: str | None = None
+ _credential_source: str = "explicit"
+ # Cloud-host state (AUTH-10): the resolved host settings and the clock
+ # every time-dependent byte (SigV4 date, JWT iat/exp) is read from. The
+ # harness injects a fixed clock; users never touch it.
+ host_settings: "dict[str, str]"
+ clock: "Callable[[], datetime] | None"
+ # The header an ApiKey travels under when the policy says x-api-key
+ # (Anthropic ``x-api-key``, Gemini ``x-goog-api-key``).
+ _api_key_header: ClassVar[str] = "x-api-key"
+
+ @property
+ def supports(self) -> EndpointSupport:
+ """The endpoint surfaces this bound access path carries."""
+ return self.access.supports
+
+ @classmethod
+ def has_stored_credential(cls) -> bool:
+ """Offline probe for the router's ``oauth-unless-explicit`` chain
+ (spec/auth.md AUTH-1): is a usable login stored locally?"""
+ from ..access import has_stored_credential
+
+ return has_stored_credential(cls.manifest)
+
+ def _bind_access(
+ self,
+ access: ProviderManifest | None,
+ *,
+ credentials_path: "str | os.PathLike[str] | None" = None,
+ default_base_url: str | None = None,
+ settings: "Mapping[str, str] | None" = None,
+ ) -> None:
+ """Bind the access policy and resolve the credential it calls for.
+
+ Called from each dialect's ``__post_init__``. Sets ``access``,
+ ``provider``, ``api_key`` (a callable for stored logins, re-read per
+ request so rotations and refreshes are picked up), ``account_id``
+ when the credential carries one, ``host_settings`` (explicit values
+ and defaults only — the router fills env fallbacks, like it does for
+ the key), and ``base_url``: the policy's own, or the host template
+ rendered over the settings, when the caller left the dialect's
+ default.
+ """
+ from ..access import load_credential
+ from ..cloud.hosts import render_base_url, resolve_settings
+
+ policy = access if access is not None else type(self).manifest
+ self.access = policy
+ self.provider = policy.provider
+ loaded = load_credential(policy, self.api_key, credentials_path=credentials_path)
+ self.api_key = loaded.credential
+ self._credential_source = loaded.source
+ if loaded.account_id is not None and self.account_id is None:
+ self.account_id = loaded.account_id
+ if loaded.credential is not None and not callable(loaded.credential):
+ # A static credential of the wrong kind for this door fails now,
+ # not on the first request (a provider callable is checked per call).
+ from ..access import select_scheme
+
+ select_scheme(policy, coerce_credential(loaded.credential))
+ self.host_settings = resolve_settings(policy.host, settings, None, provider=policy.provider)
+ if getattr(self, "clock", None) is None:
+ self.clock = None
+ if policy.host is not None:
+ if default_base_url is None or self.base_url == default_base_url:
+ self.base_url = render_base_url(policy.host, self.host_settings)
+ elif policy.base_url is not None and default_base_url is not None and self.base_url == default_base_url:
+ self.base_url = policy.base_url
+
+ def _registry_compat(self) -> str | None:
+ """The compat preset the bound provider names in the registry, for a
+ dialect constructed directly with a bound access policy and no
+ ``compat=``: the policy names the provider; the provider names its
+ preset (found 2026-09-03 when a direct ``OpenAIChatLM(access=
+ BEDROCK_CHAT)`` skipped the bedrock per-model refusals)."""
+ if self.access is type(self).manifest:
+ return None
+ from ..registry import lookup
+
+ definition = lookup(self.access.provider)
+ return definition.compat if definition is not None else None
+
+ def _now(self) -> "datetime":
+ from ..cloud.hosts import utc_now
+
+ return self.clock() if self.clock is not None else utc_now()
+
+ def _emit(
+ self,
+ *,
+ method: str,
+ url: str,
+ headers: "dict[str, str] | list[tuple[str, str]] | None" = None,
+ params: "dict[str, Any] | None" = None,
+ payload: Any = None,
+ body: bytes | None = None,
+ endpoint: str | None = None,
+ stream: bool = False,
+ model: str | None = None,
+ connect_timeout: float | None = None,
+ read_timeout: float | None = None,
+ write_timeout: float | None = None,
+ ) -> TransportRequest:
+ """Finish a dialect-built request through the bound host (AUTH-10)
+ and sign it. With no host this is ``make_json_request`` — every
+ dialect routes its wire requests through here so a host never needs
+ a dialect branch."""
+ from ..cloud.hosts import finish_request, sign_request
+ from .common import make_json_request
+
+ from ..access import auth_header
+
+ credential = resolve_credential_value(self.api_key) if self.api_key is not None else None
+ hdrs = dict(headers.items()) if isinstance(headers, dict) else dict(headers or [])
+ if credential is not None and not isinstance(credential, AwsCredentials):
+ pair = auth_header(self.access, credential, api_key_header=self._api_key_header)
+ if pair is not None and pair[0].lower() not in {k.lower() for k in hdrs}:
+ hdrs[pair[0]] = pair[1]
+ finished = finish_request(
+ self.access,
+ self.host_settings,
+ base_url=self.base_url,
+ url=url,
+ headers=hdrs,
+ payload=payload,
+ params=params,
+ endpoint=endpoint,
+ stream=stream,
+ model=model,
+ credential=credential,
+ )
+ req = make_json_request(
+ method=method,
+ url=finished.url,
+ headers=finished.headers,
+ params=finished.params or None,
+ payload=finished.payload,
+ body=body,
+ connect_timeout=connect_timeout,
+ read_timeout=read_timeout,
+ write_timeout=write_timeout,
+ )
+ if isinstance(credential, AwsCredentials):
+ req.headers = sign_request(
+ self.access,
+ self.host_settings,
+ method=req.method,
+ url=req.url,
+ headers=req.headers,
+ body=req.body,
+ credential=credential,
+ now=self._now(),
+ )
+ return req
+
+ def _require(self, surface: str) -> None:
+ """Raise unless the bound access path carries ``surface``.
+
+ A dialect may implement a surface its access path does not carry
+ (Anthropic files on a Claude Code login); the policy, not the class,
+ decides. Message shape: ``<provider>: <surface> not supported``.
+ """
+ if not self.access.supports.supports_endpoint(surface):
+ raise UnsupportedFeatureError(
+ f"{self.provider}: {_SURFACE_WORD.get(surface, surface)} not supported",
+ provider=self.provider,
+ )
+
+ def complete(self, request: Request) -> Response:
+ req = self.build_request(request, stream=False)
+ resp = self._send(req)
+ if resp.status >= 400:
+ error = self.normalize_error(resp.status, resp.text())
+ _attach_retry_after(error, resp.headers)
+ raise error
+ return self.parse_response(request, resp)
+
+ def stream(self, request: Request) -> Iterator[StreamEvent]:
+ # MAP-3 (docs/mapping-rules.md): adapters may emit one end event per
+ # provider terminal frame; the coalescer merges them so the public
+ # stream yields exactly one final StreamEndEvent.
+ from ..result import coalesce_stream
+
+ return coalesce_stream(self._stream_raw(request), model=request.model)
+
+ def _stream_raw(self, request: Request) -> Iterator[StreamEvent]:
+ req = self.build_request(request, stream=True)
+ self._ensure_transport_open()
+ try:
+ with self.transport.stream(req) as resp:
+ if resp.status >= 400:
+ body = resp.read()
+ error = self.normalize_error(
+ resp.status, body.decode("utf-8", errors="replace")
+ )
+ _attach_retry_after(error, resp.headers)
+ raise error
+ lines = resp.iter_lines() if hasattr(resp, "iter_lines") else _iter_lines(resp)
+ for raw in parse_sse(lines):
+ for event in self.parse_stream_events(request, raw):
+ if event is not None:
+ yield event
+ except NetworkTransportError as exc:
+ raise LM15TransportError(str(exc)) from exc
+
+ def _send(self, request: TransportRequest) -> HttpResponse:
+ self._ensure_transport_open()
+ try:
+ with self.transport.stream(request) as resp:
+ body = resp.read()
+ return HttpResponse(
+ status=resp.status,
+ reason=resp.reason,
+ headers=resp.headers,
+ body=body,
+ http_version=resp.http_version,
+ )
+ except NetworkTransportError as exc:
+ raise LM15TransportError(str(exc)) from exc
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ return self._with_login_hint(map_http_error(
+ status,
+ body.strip()[:500] or f"HTTP {status}",
+ provider=self.provider,
+ env_keys=self.access.env_keys,
+ ))
+
+ def _provider_error(
+ self,
+ cls: type[ProviderError],
+ message: str,
+ *,
+ status: int | None = None,
+ provider_code: str | None = None,
+ request_id: str | None = None,
+ retry_after: float | None = None,
+ ) -> ProviderError:
+ kwargs = {
+ "provider": self.provider,
+ "provider_code": provider_code or None,
+ "status": status,
+ "request_id": request_id or None,
+ "retry_after": retry_after,
+ }
+ kwargs = {key: value for key, value in kwargs.items() if value is not None}
+ if issubclass(cls, AuthError):
+ return self._with_login_hint(cls(message, env_keys=self.access.env_keys, **kwargs))
+ return cls(message, **kwargs)
+
+ def _with_login_hint(self, error: ProviderError) -> ProviderError:
+ """Auth errors guide the user to re-login when the credential is a
+ local login: always under an ``oauth`` policy (there is no env var),
+ and under ``oauth-unless-explicit`` only when the stored login was
+ the rung that won — an explicit key keeps the generic guidance.
+ ``with_credential_hint`` is a no-op on non-auth errors."""
+ hint = self.access.login_hint
+ if hint and (self.access.credential_policy == "oauth" or self._credential_source == "stored"):
+ return with_credential_hint(error, hint)
+ return error
+
+ def close(self) -> None:
+ close = getattr(self.transport, "close", None)
+ if callable(close):
+ close()
+
+ def _ensure_transport_open(self) -> None:
+ """Recreate the default transport if it was closed by interactive tooling.
+
+ Provider objects are often kept in notebook/REPL variables. Some
+ interactive runners eagerly close context-manager-like objects between
+ cells; when that happens, the default StdlibTransport can be safely
+ replaced before the next request.
+ """
+ if isinstance(self.transport, StdlibTransport) and getattr(self.transport, "_closed", False):
+ self.transport = default_transport()
+
+ def __enter__(self):
+ return self
+
+ def __exit__(self, exc_type, exc, tb) -> None:
+ self.close()
+
+ def live(self, config: LiveConfig) -> LiveSession:
+ self._require("live")
+ raise UnsupportedFeatureError(f"{self.provider}: live not supported", provider=self.provider)
+
+ # ─── Media generation (images / speech) ────────────────────────
+ #
+ # Same pure-hook pattern as files and batch: adapters implement the
+ # build/parse pair; the sync drivers below and the async mirrors both
+ # drive the same hooks. Parse hooks take the full HttpResponse, not
+ # just the body: OpenAI speech returns raw bytes whose media type
+ # lives in the content-type HEADER (captured 2026-09-01). Media
+ # types always come from the wire — hardcoding one is a lie on at
+ # least one provider (OpenAI png / Gemini png / xAI jpeg captured).
+
+ def _generation_unsupported(self, kind: str) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{self.provider}: {kind} generation not supported", provider=self.provider)
+
+ def _image_generate_request(self, request: ImageGenerationRequest) -> TransportRequest:
+ raise self._generation_unsupported("image")
+
+ def _image_generation_from_response(self, request: ImageGenerationRequest, resp: HttpResponse) -> ImageGenerationResponse:
+ raise self._generation_unsupported("image")
+
+ def _speech_generate_request(self, request: SpeechGenerationRequest) -> TransportRequest:
+ raise self._generation_unsupported("speech")
+
+ def _speech_generation_from_response(self, request: SpeechGenerationRequest, resp: HttpResponse) -> SpeechGenerationResponse:
+ raise self._generation_unsupported("speech")
+
+ def image_generate(self, request: ImageGenerationRequest) -> ImageGenerationResponse:
+ """Generate (or, with ``request.images``, edit) images.
+
+ Input images are ordinary ImageParts; adapters route them to the
+ provider's real edit door (OpenAI: ``/images/edits``; Gemini: the
+ same chat call; xAI: ``/images/edits``) and raise where the wire
+ has none — never silently ignore them.
+ """
+ self._require("images")
+ resp = self._send(self._image_generate_request(request))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._image_generation_from_response(request, resp)
+
+ def speech_generate(self, request: SpeechGenerationRequest) -> SpeechGenerationResponse:
+ """Text-to-speech. Omitted ``voice``/``format`` mean the server's
+ defaults, honestly reported in the returned part's media_type —
+ lm15 injects no defaults of its own."""
+ self._require("speech")
+ resp = self._send(self._speech_generate_request(request))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._speech_generation_from_response(request, resp)
+
+ # ─── Video generation (job-shaped on every wire: Sora / Veo / grok) ─────
+ #
+ # Same pure-hook pattern as batch: submit returns a ticket, status
+ # polls it, result turns the terminal snapshot into a VideoPart —
+ # with an optional fetch step (Sora delivers bytes from a content
+ # endpoint; Veo and xAI put a URL in the terminal body). The
+ # VideoJob handle in lm15.video adds the wait/re-attach ergonomics.
+
+ def _video_unsupported(self) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{self.provider}: video generation not supported", provider=self.provider)
+
+ def _video_submit_request(self, request: VideoGenerationRequest) -> TransportRequest:
+ raise self._video_unsupported()
+
+ def _video_job_from_body(self, body: str, video_id: "str | None" = None) -> VideoJobInfo:
+ """Parse a submit or status body; ``video_id`` is the known ticket
+ id for wires whose status bodies do not echo it (xAI)."""
+ raise self._video_unsupported()
+
+ def _video_status_request(self, video_id: str) -> TransportRequest:
+ raise self._video_unsupported()
+
+ def _video_result_fetch(self, status_body: "dict[str, Any]") -> TransportRequest | None:
+ """Optional download step; None = the terminal body carries the URL."""
+ raise self._video_unsupported()
+
+ def _video_part(self, status_body: "dict[str, Any]", fetched: "HttpResponse | None") -> VideoPart:
+ raise self._video_unsupported()
+
+ def _video_list_request(self, limit: int, model: str | None) -> TransportRequest:
+ raise self._video_unsupported()
+
+ def _video_jobs_from_list_body(self, body: str) -> "tuple[VideoJobInfo, ...]":
+ raise self._video_unsupported()
+
+ def video_submit(self, request: VideoGenerationRequest) -> VideoJobInfo:
+ """Submit a video job; returns the ticket snapshot."""
+ self._require("video")
+ resp = self._send(self._video_submit_request(request))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._video_job_from_body(resp.text())
+
+ def video_status(self, video_id: str) -> VideoJobInfo:
+ self._require("video")
+ resp = self._send(self._video_status_request(video_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._video_job_from_body(resp.text(), video_id)
+
+ def video_result(self, video_id: str) -> VideoPart:
+ """The finished video as a VideoPart, in the provider's own
+ delivery mode (URL or bytes) — no silent re-hosting, no silent
+ gigabyte download; ``part.bytes`` fetches URL results on demand.
+ Raises ValueError while the job runs."""
+ self._require("video")
+ resp = self._send(self._video_status_request(video_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ job = self._video_job_from_body(resp.text(), video_id)
+ if job.status not in VIDEO_TERMINAL_STATUSES:
+ raise ValueError(
+ f"video {video_id} is not finished (status={job.status!r}); "
+ f"wait() or poll video_status() until done"
+ )
+ status_body = resp.json()
+ fetch = self._video_result_fetch(status_body)
+ fetched = None
+ if fetch is not None:
+ fetched = self._send(fetch)
+ if fetched.status >= 400:
+ raise self.normalize_error(fetched.status, fetched.text())
+ return self._video_part(status_body, fetched)
+
+ def video_list(self, limit: int = 20, model: str | None = None) -> "tuple[VideoJobInfo, ...]":
+ """One page of this credential's video jobs. ``model`` is required
+ on Gemini (operations list per model), ignored on OpenAI; xAI has
+ no list endpoint at all and raises."""
+ self._require("video")
+ resp = self._send(self._video_list_request(limit, model))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._video_jobs_from_list_body(resp.text())
+
+ # Ergonomic verbs (ticket handles) ---------------------------------------
+
+ def video_generate(self, request: VideoGenerationRequest) -> "VideoJob":
+ """Submit and wrap the ticket in a VideoJob handle."""
+ from ..video_jobs import VideoJob
+
+ return VideoJob(self, self.video_submit(request))
+
+ def video_job(self, video_id: str) -> "VideoJob":
+ """Re-attach to an existing job by id alone."""
+ from ..video_jobs import VideoJob
+
+ return VideoJob(self, self.video_status(video_id))
+
+ def video_jobs(self, limit: int = 20, model: str | None = None) -> "tuple[VideoJob, ...]":
+ """Enumerate this credential's video jobs, where the wire lists
+ them (OpenAI: account-wide; Gemini: per model, pass ``model``).
+ xAI has no list endpoint and raises: the ticket you stored is
+ the only copy."""
+ from ..video_jobs import VideoJob
+
+ return tuple(VideoJob(self, info) for info in self.video_list(limit, model))
+
+ # ─── Live model listing (provisional endpoint) ──────────────────────────
+ #
+ # Adapters that support their provider's list-models endpoint override the
+ # two hooks; list_models() itself is shared. Each canonical ModelInfo
+ # carries the usable Request.model string as `id` and the verbatim wire
+ # entry under `origin.provider_data` (opaque, never cleaned). Listing is
+ # ADVISORY metadata per docs/model-hydration.md: it never changes what
+ # build_request produces.
+
+ def _models_request(self) -> TransportRequest:
+ raise UnsupportedFeatureError(f"{self.provider}: model listing not supported", provider=self.provider)
+
+ def _models_from_body(self, body: str) -> "tuple[ModelInfo, ...]":
+ raise UnsupportedFeatureError(f"{self.provider}: model listing not supported", provider=self.provider)
+
+ def list_models(self) -> "tuple[ModelInfo, ...]":
+ """Fetch the models this credential can use, as canonical ModelInfo."""
+ self._require("models")
+ resp = self._send(self._models_request())
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._models_from_body(resp.text())
+
+ # ─── Batch jobs (third execution mode: complete / stream / batch) ───────
+ #
+ # Adapters override the pure hooks; the five drivers (batch_submit,
+ # batch_status, batch_results, batch_cancel, batch_list) are shared, as
+ # are the ergonomic verbs (batch, batch_job, batches) returning BatchJob
+ # handles. Hooks are pure build/parse so the async twins and the future
+ # harness direction drive the same code. There is NO local fan-out
+ # fallback: batch() means a provider-side queue or an honest error.
+
+ def _batch_unsupported(self) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{self.provider}: batch not supported", provider=self.provider)
+
+ def _batch_upload_request(self, request: BatchRequest) -> TransportRequest | None:
+ """Optional pre-submit upload step (OpenAI's JSONL file); None = single-step."""
+ return None
+
+ def _batch_submit_request(self, request: BatchRequest, upload_body: "dict[str, Any] | None") -> TransportRequest:
+ raise self._batch_unsupported()
+
+ def _batch_job_from_body(self, body: str) -> BatchJobInfo:
+ raise self._batch_unsupported()
+
+ def _batch_status_request(self, batch_id: str) -> TransportRequest:
+ raise self._batch_unsupported()
+
+ def _batch_cancel_request(self, batch_id: str) -> TransportRequest:
+ raise self._batch_unsupported()
+
+ def _batch_result_fetches(self, status_body: "dict[str, Any]") -> "tuple[TransportRequest, ...]":
+ raise self._batch_unsupported()
+
+ def _batch_entries(self, status_body: "dict[str, Any]", fetched: "tuple[str, ...]") -> "tuple[BatchEntry, ...]":
+ raise self._batch_unsupported()
+
+ def _batch_list_request(self, limit: int) -> TransportRequest:
+ raise self._batch_unsupported()
+
+ def _batch_jobs_from_list_body(self, body: str) -> "tuple[BatchJobInfo, ...]":
+ raise self._batch_unsupported()
+
+ def batch_submit(self, request: BatchRequest) -> BatchJobInfo:
+ """Submit to the provider's batch queue; returns the ticket snapshot."""
+ self._require("batches")
+ upload_body = None
+ upload_req = self._batch_upload_request(request)
+ if upload_req is not None:
+ resp = self._send(upload_req)
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ upload_body = resp.json()
+ resp = self._send(self._batch_submit_request(request, upload_body))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._batch_job_from_body(resp.text())
+
+ def batch_status(self, batch_id: str) -> BatchJobInfo:
+ self._require("batches")
+ resp = self._send(self._batch_status_request(batch_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._batch_job_from_body(resp.text())
+
+ def batch_results(self, batch_id: str) -> "tuple[BatchEntry, ...]":
+ """Entries in submission order; raises ValueError while the job runs."""
+ self._require("batches")
+ resp = self._send(self._batch_status_request(batch_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ job = self._batch_job_from_body(resp.text())
+ if job.status not in BATCH_TERMINAL_STATUSES:
+ raise ValueError(
+ f"batch {batch_id} is not finished (status={job.status!r}); "
+ f"wait() or poll batch_status() until done"
+ )
+ status_body = resp.json()
+ texts = []
+ for fetch in self._batch_result_fetches(status_body):
+ fetched = self._send(fetch)
+ if fetched.status >= 400:
+ raise self.normalize_error(fetched.status, fetched.text())
+ texts.append(fetched.text())
+ return self._batch_entries(status_body, tuple(texts))
+
+ def batch_cancel(self, batch_id: str) -> BatchJobInfo:
+ """Request cancellation — a request, not a guarantee."""
+ self._require("batches")
+ resp = self._send(self._batch_cancel_request(batch_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._batch_job_from_body(resp.text())
+
+ def batch_list(self, limit: int = 20) -> "tuple[BatchJobInfo, ...]":
+ """Enumerate this credential's batch jobs, newest first.
+
+ The provider is the system of record; recovery from a lost id must
+ never depend on the user having been careful.
+ """
+ self._require("batches")
+ resp = self._send(self._batch_list_request(limit))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._batch_jobs_from_list_body(resp.text())
+
+ def batch(self, requests: "BatchRequest | Sequence[Request]", *, model: str | None = None,
+ label: str | None = None, extensions: "dict[str, Any] | None" = None) -> "BatchJob":
+ """Third execution mode: many requests, later, ~half price."""
+ from ..batch import BatchJob
+
+ if isinstance(requests, BatchRequest):
+ request = requests
+ else:
+ request = BatchRequest(model=model, requests=tuple(requests), label=label, extensions=extensions)
+ return BatchJob(self, self.batch_submit(request))
+
+ def batch_job(self, batch_id: str) -> "BatchJob":
+ """Re-attach to a submitted batch from its id (one status round trip)."""
+ from ..batch import BatchJob
+
+ return BatchJob(self, self.batch_status(batch_id))
+
+ def batches(self, limit: int = 20) -> "tuple[BatchJob, ...]":
+ """Lost the ticket? The queue remembers."""
+ from ..batch import BatchJob
+
+ return tuple(BatchJob(self, info) for info in self.batch_list(limit))
+
+ # ─── Cache resources (the stored tier of MAP-6) ────────────────────
+ #
+ # Same pure-hook pattern as files. A stored cache belongs to one model
+ # on every provider that has the tier; the prefix Request supplies
+ # model, system, tools, and messages. Adapters without the tier leave
+ # the hooks raising and `cache()` returns a CachedPrefix without a
+ # resource — the marks-or-automatic path. Nothing here names a
+ # provider; id formats and TTL spellings are the adapter's.
+
+ def _caches_unsupported(self) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{self.provider}: stored caches not supported", provider=self.provider)
+
+ def _cache_create_request(self, prefix: Request, ttl_seconds: int | None, label: str | None) -> TransportRequest:
+ raise self._caches_unsupported()
+
+ def _cache_info_from_body(self, body: str) -> CacheInfo:
+ raise self._caches_unsupported()
+
+ def _cache_get_request(self, cache_id: str) -> TransportRequest:
+ raise self._caches_unsupported()
+
+ def _cache_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ raise self._caches_unsupported()
+
+ def _cache_page_from_list_body(self, body: str) -> CachePage:
+ raise self._caches_unsupported()
+
+ def _cache_delete_request(self, cache_id: str) -> TransportRequest:
+ raise self._caches_unsupported()
+
+ def _cache_update_request(self, cache_id: str, ttl_seconds: int) -> TransportRequest:
+ raise self._caches_unsupported()
+
+ @staticmethod
+ def _check_cache_prefix(prefix: Request, ttl_seconds: int | None) -> None:
+ if prefix.config != Config():
+ raise ValueError("cache_create: the prefix Request must carry a default Config (a stored cache has no generation settings)")
+ if ttl_seconds is not None and (isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or ttl_seconds <= 0):
+ raise ValueError("ttl_seconds must be a positive int")
+
+ def cache_create(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None) -> CacheInfo:
+ """Store the prefix (model, system, tools, messages) as a cache object."""
+ self._require("caches")
+ self._check_cache_prefix(prefix, ttl_seconds)
+ resp = self._send(self._cache_create_request(prefix, ttl_seconds, label))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._cache_info_from_body(resp.text())
+
+ def cache_get(self, cache_id: str) -> CacheInfo:
+ self._require("caches")
+ resp = self._send(self._cache_get_request(cache_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._cache_info_from_body(resp.text())
+
+ def cache_list(self, limit: int = 20, cursor: str | None = None) -> CachePage:
+ self._require("caches")
+ resp = self._send(self._cache_list_request(limit, cursor))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._cache_page_from_list_body(resp.text())
+
+ def cache_delete(self, cache_id: str) -> None:
+ """Returning without an exception IS the confirmation (the files precedent)."""
+ self._require("caches")
+ resp = self._send(self._cache_delete_request(cache_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+
+ def cache_update(self, cache_id: str, *, ttl_seconds: int) -> CacheInfo:
+ self._require("caches")
+ if isinstance(ttl_seconds, bool) or not isinstance(ttl_seconds, int) or ttl_seconds <= 0:
+ raise ValueError("ttl_seconds must be a positive int")
+ resp = self._send(self._cache_update_request(cache_id, ttl_seconds))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._cache_info_from_body(resp.text())
+
+ def cache(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None) -> CachedPrefix:
+ """Make a prompt beginning reusable with the best tier this provider has.
+
+ Resource tier: creates the stored object (one network call, billed
+ per hour while it lives) and returns it inside the CachedPrefix.
+ Marks and automatic tiers: pure — the CachedPrefix only records the
+ boundary; `cached + messages` places the mark or sends nothing.
+ """
+ if self.supports.caches:
+ return CachedPrefix(prefix, self.cache_create(prefix, ttl_seconds=ttl_seconds, label=label))
+ self._check_cache_prefix(prefix, ttl_seconds)
+ return CachedPrefix(prefix)
+
+ # ─── Files (account-scoped storage: upload / get / list / delete / download) ─
+ #
+ # Adapters override the pure build/parse hooks; the drivers are shared
+ # so the async twins and a future harness direction drive identical
+ # code. All five operations exist on all three first-party providers
+ # (verified live 2026-08-31); which FILES support download is per-file
+ # provider policy — lm15 forwards the provider's typed refusal instead
+ # of second-guessing it.
+
+ def _files_unsupported(self) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{self.provider}: files not supported", provider=self.provider)
+
+ def _file_upload_request(self, request: FileUploadRequest) -> TransportRequest:
+ raise self._files_unsupported()
+
+ def _file_info_from_body(self, body: str) -> FileInfo:
+ raise self._files_unsupported()
+
+ def _file_get_request(self, file_id: str) -> TransportRequest:
+ raise self._files_unsupported()
+
+ def _file_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ raise self._files_unsupported()
+
+ def _file_page_from_list_body(self, body: str) -> FilePage:
+ raise self._files_unsupported()
+
+ def _file_delete_request(self, file_id: str) -> TransportRequest:
+ raise self._files_unsupported()
+
+ def _file_download_request(self, file_id: str) -> TransportRequest:
+ raise self._files_unsupported()
+
+ def file_upload(self, request: FileUploadRequest) -> FileInfo:
+ """Store a file with the provider; returns its canonical snapshot.
+
+ ``FileInfo.id`` is the reference to place in a media Part's
+ ``file_id``. On Gemini the file may come back ``pending``
+ (processing); ``file_wait_ready`` covers that.
+ """
+ self._require("files")
+ resp = self._send(self._file_upload_request(request))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._file_info_from_body(resp.text())
+
+ def file_get(self, file_id: str) -> FileInfo:
+ self._require("files")
+ resp = self._send(self._file_get_request(file_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._file_info_from_body(resp.text())
+
+ def file_list(self, limit: int = 20, cursor: str | None = None) -> FilePage:
+ """One page of this credential's stored files.
+
+ The provider is the system of record: a lost file id is recovered
+ by listing, never by client-side bookkeeping. ``cursor`` is the
+ opaque ``next_cursor`` of the previous page.
+ """
+ self._require("files")
+ resp = self._send(self._file_list_request(limit, cursor))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return self._file_page_from_list_body(resp.text())
+
+ def file_delete(self, file_id: str) -> None:
+ """Delete a stored file. Returning without an exception IS the
+ confirmation; provider acknowledgement bodies differ and carry no
+ canonical information."""
+ self._require("files")
+ resp = self._send(self._file_delete_request(file_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+
+ def file_download(self, file_id: str) -> bytes:
+ """Download a file's content, when THIS file supports download.
+
+ Every provider restricts which files are downloadable (Anthropic:
+ tool-generated only; OpenAI: by purpose; Gemini: generated only)
+ and refuses the rest with a typed error — forwarded, not masked.
+ """
+ self._require("files")
+ resp = self._send(self._file_download_request(file_id))
+ if resp.status >= 400:
+ raise self.normalize_error(resp.status, resp.text())
+ return resp.body
+
+ def file_wait_ready(self, file_id: str, poll_every: float = 2.0, timeout: float | None = None) -> FileInfo:
+ """Poll until the file leaves ``pending``; returns the terminal
+ snapshot (``ready`` or ``failed``) — check ``readiness``, mirroring
+ BatchJob.wait's return-don't-raise convention. Gemini uploads and
+ Azure OpenAI v1 uploads can be pending; the first poll usually returns."""
+ self._require("files")
+ import time as _time
+
+ deadline = None if timeout is None else _time.monotonic() + timeout
+ info = self.file_get(file_id)
+ while info.readiness == "pending":
+ if deadline is not None and _time.monotonic() >= deadline:
+ raise TimeoutError(f"file {file_id} still pending after {timeout}s")
+ _time.sleep(poll_every)
+ info = self.file_get(file_id)
+ return info
+
+
+def batch_entry_request(model: object) -> Request:
+ """Synthetic Request for parsing a batch entry body.
+
+ Batch results outlive the submitting process (re-attach by id), so the
+ original Request is not available; parse_response only reads
+ ``request.model`` as a fallback when the body lacks one, and every
+ batch entry body carries its model.
+ """
+ from ..types import Message
+
+ name = model if isinstance(model, str) and model else "batch"
+ return Request(model=name, messages=(Message.user("-"),))
+
+
+def batch_entry_http(body: "dict[str, Any]", status: int = 200) -> HttpResponse:
+ """Wrap a decoded batch entry body for the frozen parse_response path."""
+ return HttpResponse(
+ status=status,
+ reason="OK" if status < 400 else "Error",
+ headers=[("content-type", "application/json")],
+ body=json.dumps(body).encode("utf-8"),
+ )
+
+
+class UnsupportedLiveSession:
+ def send(self, event=None, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def send_turn(self, *args, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def send_audio(self, *args, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def send_image(self, *args, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def send_text(self, *args, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def send_tool_result(self, *args, **kwargs):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def interrupt(self):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def end_audio(self):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def recv(self):
+ raise UnsupportedFeatureError("live session not supported")
+
+ def close(self) -> None:
+ return
+
+
+def _iter_lines(chunks: Iterator[bytes]) -> Iterator[bytes]:
+ """Split arbitrary byte chunks into newline-terminated lines for SSE."""
+
+ buf = bytearray()
+ for chunk in chunks:
+ if not chunk:
+ continue
+ buf.extend(chunk)
+ while True:
+ idx = buf.find(b"\n")
+ if idx < 0:
+ break
+ line = bytes(buf[: idx + 1])
+ del buf[: idx + 1]
+ yield line
+ if buf:
+ yield bytes(buf)
diff --git a/dspy/_vendor/lm15/providers/claude_code.py b/dspy/_vendor/lm15/providers/claude_code.py
new file mode 100644
index 000000000..500e02da6
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/claude_code.py
@@ -0,0 +1,66 @@
+"""
+lm15.providers.claude_code — the Anthropic dialect on a Claude Code login.
+
+``ClaudeCodeLM`` is a *name*, not a behaviour: it is ``AnthropicLM`` bound
+to ``lm15.access.CLAUDE_CODE``. Every wire difference from an API-key
+client — bearer auth, the ``anthropic-beta`` and ``x-app``/``user-agent``
+headers, the required system-prompt prefix, the re-login hint on auth
+errors, no files/batch/live — is a field of that policy, consulted by the
+dialect at stated points. A port needs the policy table and the dialect,
+not this class.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import ClassVar
+
+from ..access import CLAUDE_CODE, DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT, DEFAULT_CLAUDE_CODE_VERSION # noqa: F401
+from ..features import ProviderManifest
+from .anthropic import AnthropicLM
+from .base import Credential, SyncTransport, default_transport
+
+
+class ClaudeCodeLM(AnthropicLM):
+ """Anthropic Messages adapter authenticated with local Claude Code OAuth."""
+
+ manifest: ClassVar[ProviderManifest] = CLAUDE_CODE
+
+ def __init__(
+ self,
+ api_key: Credential | None = None,
+ *,
+ credentials_path: str | os.PathLike[str] | None = None,
+ transport: SyncTransport | None = None,
+ base_url: str = "https://api.anthropic.com/v1",
+ api_version: str = "2023-06-01",
+ claude_code_version: str = DEFAULT_CLAUDE_CODE_VERSION,
+ ) -> None:
+ self.claude_code_version = claude_code_version
+ policy = CLAUDE_CODE
+ if claude_code_version != DEFAULT_CLAUDE_CODE_VERSION:
+ policy = policy.with_headers({"user-agent": f"claude-cli/{claude_code_version}"})
+ super().__init__(
+ api_key=api_key,
+ transport=transport or default_transport(),
+ base_url=base_url,
+ api_version=api_version,
+ access=policy,
+ credentials_path=credentials_path,
+ )
+
+ @classmethod
+ def from_claude_code(
+ cls,
+ *,
+ credentials_path: str | os.PathLike[str] | None = None,
+ transport: SyncTransport | None = None,
+ base_url: str = "https://api.anthropic.com/v1",
+ claude_code_version: str = DEFAULT_CLAUDE_CODE_VERSION,
+ ) -> "ClaudeCodeLM":
+ return cls(
+ credentials_path=credentials_path,
+ transport=transport,
+ base_url=base_url,
+ claude_code_version=claude_code_version,
+ )
diff --git a/dspy/_vendor/lm15/providers/common.py b/dspy/_vendor/lm15/providers/common.py
new file mode 100644
index 000000000..c066e69da
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/common.py
@@ -0,0 +1,504 @@
+from __future__ import annotations
+
+import base64
+import json
+import urllib.parse
+from typing import Any
+
+from ..models import ModelInfo, ModelOrigin
+from ..transports import TransportRequest
+from ..types import (
+ AudioPart,
+ BinaryPart,
+ CitationPart,
+ DocumentPart,
+ ImagePart,
+ Message,
+ Part,
+ TextPart,
+ ThinkingPart,
+ FileReadiness,
+ TokenLogprob,
+ ToolResultPart,
+ TopLogprob,
+ VideoPart,
+)
+
+JsonPayload = dict[str, Any] | list[Any]
+
+
+# The FileReadiness fold for every OpenAI-shaped file object (api.openai.com,
+# Azure OpenAI v1, Meta): spec/vocabularies.md FileReadiness, ratified
+# 2026-09-06 (lm15-contract/changes/2026-09-06-decisions.md D6). Azure says `pending` after
+# a 201 upload where api.openai.com says `uploaded` (live 2026-09-04); the
+# `status` field is deprecated upstream, so absent and unknown words read as
+# ready.
+_OPENAI_FILE_READINESS: dict[str, FileReadiness] = {
+ "uploaded": "pending",
+ "pending": "pending",
+ "error": "failed",
+ "failed": "failed",
+ "processed": "ready",
+}
+
+
+def openai_file_readiness(status: object) -> FileReadiness:
+ """``uploaded | pending -> pending``, ``error | failed -> failed``,
+ ``processed | absent | unknown -> ready``."""
+ if not isinstance(status, str):
+ return "ready"
+ return _OPENAI_FILE_READINESS.get(status, "ready")
+
+
+# The part kinds that carry bytes/addresses rather than words (MAP-10: a
+# native block or a raise; never text).
+MEDIA_KINDS: frozenset[str] = frozenset({"image", "audio", "video", "document", "binary"})
+
+
+def parts_to_text(parts: tuple[Part, ...], *, provider: str | None = None,
+ where: str = "a text-only wire field") -> str:
+ """Text rendering for wire fields that take text only.
+
+ Renders text-bearing parts (text, thinking, citation). A media part
+ RAISES `UnsupportedFeatureError` before any wire (MAP-10 rule 2): the
+ field cannot carry it, and rendering a caption or a type name in its
+ place is the silent substitution the rule forbids. Callers that own a
+ slot for the part must not be here.
+ """
+ from ..errors import UnsupportedFeatureError
+
+ out: list[str] = []
+ for part in parts:
+ if part.type in MEDIA_KINDS:
+ head = f"{provider}: " if provider else ""
+ raise UnsupportedFeatureError(
+ f"{head}a {part.type} part cannot reach {where}, which takes text only; "
+ "no text rendering of a media part is made (MAP-10)",
+ provider=provider,
+ )
+ if isinstance(part, TextPart):
+ out.append(part.text)
+ elif isinstance(part, ThinkingPart) and part.text:
+ out.append(part.text)
+ elif isinstance(part, CitationPart):
+ bits = [x for x in (part.title, part.url, part.text) if x]
+ if bits:
+ out.append(" — ".join(bits))
+ return "\n".join(out)
+
+
+def message_text(msg: Message) -> str:
+ return parts_to_text(msg.parts)
+
+
+def media_base64(part: ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart) -> str:
+ """The part's bytes as base64: inline `data`, or the `path` read now.
+ A url/file_id-addressed part has no bytes here; the caller maps those."""
+ if part.data is not None:
+ return part.data
+ if part.path is not None:
+ return base64.b64encode(part.path.read_bytes()).decode("ascii")
+ raise ValueError(f"{part.type} part has no inline data or path")
+
+
+def media_data_uri(part: ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart) -> str:
+ return f"data:{part.media_type};base64,{media_base64(part)}"
+
+
+# ─── MAP-10: tool-result media policy ──────────────────────────────
+
+# Which part kinds a `tool_result_media` value admits inside a result item.
+_TOOL_RESULT_MEDIA_ADMITS: dict[str, frozenset[str]] = {
+ "native": frozenset({"image", "document"}),
+ "images": frozenset({"image"}),
+ "reject": frozenset(),
+}
+
+# The door that carries the part, named in the refusal (MAP-10 rule 3).
+_MEDIA_DOORS: dict[str, str] = {
+ "image": "the OpenAI Responses, Anthropic Messages and Gemini dialects (and the xai/moonshotai/zai chat presets)",
+ "document": "the OpenAI Responses, Anthropic Messages and Gemini dialects",
+}
+
+
+def check_tool_result_media(provider: str, part: ToolResultPart, policy: str, *, wire: str) -> None:
+ """Raise before any wire when `part.content` carries a part kind the
+ preset's `tool_result_media` policy does not admit (MAP-10 rules 1–3).
+ `wire` names the field for the message ("a tool row", "function_call_output")."""
+ from ..errors import UnsupportedFeatureError
+
+ admits = _TOOL_RESULT_MEDIA_ADMITS[policy]
+ for p in part.content:
+ if p.type in MEDIA_KINDS and p.type not in admits:
+ why = ("this server takes text-only tool results" if policy == "reject"
+ else f"this server carries images but not {p.type} parts in a tool result")
+ raise UnsupportedFeatureError(
+ f"{provider}: a {p.type} part in tool_result {part.id!r} cannot reach {wire} — {why} "
+ f"(compat tool_result_media={policy!r}, measured: lm15-contract/research/tool-result-content/). "
+ f"Carried natively by {_MEDIA_DOORS.get(p.type, 'no lm15 door yet')}; "
+ "or render the part to text yourself before building the tool result (MAP-10)",
+ provider=provider,
+ )
+
+
+def tool_result_error_text(part: ToolResultPart, text: str) -> str:
+ """MAP-10 rule 5 on wires with no error flag: the text carries it."""
+ return f"[error] {text}" if part.is_error else text
+
+
+def media_bytes(part: ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart) -> bytes:
+ return part.bytes
+
+
+def extension_config(value: dict[str, Any] | None) -> dict[str, Any]:
+ return dict(value or {})
+
+
+def json_dumps(value: Any) -> bytes:
+ return json.dumps(value, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+
+
+def path_id(value: str, *, resource_name: bool = False) -> str:
+ """A provider id placed in a URL path (docs/mapping-rules.md MAP-11).
+
+ RFC 3986 percent-encoding over UTF-8: every byte outside the unreserved
+ set becomes ``%XX``. ``resource_name`` keeps ``/`` literal for wires
+ whose ids are resource names (Gemini ``files/abc``); a flat-id wire
+ (OpenAI, Anthropic, xAI) encodes ``/`` too, since a literal slash would
+ turn one operation into another on the same route table. The id is
+ never decoded first: a pre-encoded id is double-encoded and answers 404
+ (loud), where a raw reserved byte would misroute (silent).
+ """
+ return urllib.parse.quote(value, safe="/" if resource_name else "")
+
+
+def build_url(url: str, params: dict[str, Any] | None = None) -> str:
+ if not params:
+ return url
+ clean = {k: v for k, v in params.items() if v is not None}
+ if not clean:
+ return url
+ sep = "&" if "?" in url else "?"
+ return f"{url}{sep}{urllib.parse.urlencode(clean)}"
+
+
+def make_json_request(
+ *,
+ method: str,
+ url: str,
+ headers: dict[str, str] | list[tuple[str, str]] | None = None,
+ params: dict[str, Any] | None = None,
+ payload: JsonPayload | None = None,
+ body: bytes | None = None,
+ connect_timeout: float | None = None,
+ read_timeout: float | None = None,
+ write_timeout: float | None = None,
+) -> TransportRequest:
+ hdrs = list(headers.items()) if isinstance(headers, dict) else list(headers or [])
+ if payload is not None:
+ body = json_dumps(payload)
+ if not any(k.lower() == "content-type" for k, _ in hdrs):
+ hdrs.append(("Content-Type", "application/json"))
+ return TransportRequest(
+ method=method,
+ url=build_url(url, params),
+ headers=hdrs,
+ body=body or b"",
+ connect_timeout=connect_timeout,
+ read_timeout=read_timeout,
+ write_timeout=write_timeout,
+ )
+
+
+def model_infos_from_entries(
+ entries: Any,
+ *,
+ provider: str,
+ api_family: str,
+ id_of: "callable",
+) -> tuple[ModelInfo, ...]:
+ """Map a provider's list-models entries to canonical ModelInfo.
+
+ ``id`` is the usable Request.model string (``id_of`` extracts it); the
+ verbatim wire entry is preserved under ``origin.provider_data`` (opaque,
+ never cleaned). Entries without a usable id are skipped.
+ """
+ if not isinstance(entries, list):
+ return ()
+ out: list[ModelInfo] = []
+ for entry in entries:
+ if not isinstance(entry, dict):
+ continue
+ model_id = id_of(entry)
+ if not isinstance(model_id, str) or not model_id:
+ continue
+ out.append(
+ ModelInfo(
+ id=model_id,
+ provider=provider,
+ api_family=api_family,
+ origin=ModelOrigin(type="provider", provider_data=entry),
+ )
+ )
+ return tuple(out)
+
+
+def part_to_openai_input(part: Part, *, provider: str | None = None) -> dict[str, Any]:
+ """One prompt part → one Responses input block. Every media source form
+ maps (url, file_id, inline data, a path read now); a part with no slot
+ RAISES (MAP-10) instead of becoming empty text."""
+ from ..errors import UnsupportedFeatureError
+
+ if isinstance(part, TextPart):
+ return {"type": "input_text", "text": part.text}
+
+ if isinstance(part, ImagePart):
+ if part.file_id is not None:
+ return {"type": "input_image", "file_id": part.file_id}
+ payload = {"type": "input_image", "image_url": part.url if part.url is not None else media_data_uri(part)}
+ if part.detail:
+ payload["detail"] = part.detail
+ return payload
+
+ if isinstance(part, AudioPart):
+ if part.url is not None:
+ return {"type": "input_audio", "audio_url": part.url}
+ if part.file_id is not None:
+ return {"type": "input_audio", "file_id": part.file_id}
+ media = (part.media_type or "audio/wav").split("/", 1)[-1]
+ if media in {"mpeg", "mp3"}:
+ media = "mp3"
+ return {"type": "input_audio", "audio": media_base64(part), "format": media}
+
+ if isinstance(part, (DocumentPart, BinaryPart)):
+ if part.url is not None:
+ return {"type": "input_file", "file_url": part.url}
+ if part.file_id is not None:
+ return {"type": "input_file", "file_id": part.file_id}
+ # OpenAI requires a filename alongside inline file_data (live
+ # 2026-06-11: 400 missing_required_parameter without one); derive
+ # a deterministic name from the media-type subtype.
+ ext = (part.media_type or "application/octet-stream").split("/", 1)[-1].split("+", 1)[0] or "bin"
+ return {"type": "input_file", "filename": f"file.{ext}", "file_data": media_data_uri(part)}
+
+ if isinstance(part, VideoPart):
+ if part.url is not None:
+ return {"type": "input_video", "video_url": part.url}
+ if part.file_id is not None:
+ return {"type": "input_video", "file_id": part.file_id}
+ return {"type": "input_video", "video_data": media_data_uri(part)}
+
+ if isinstance(part, (CitationPart, ThinkingPart)):
+ return {"type": "input_text", "text": parts_to_text((part,))}
+
+ head = f"{provider}: " if provider else ""
+ raise UnsupportedFeatureError(
+ f"{head}a {part.type} part has no input block on the Responses wire (MAP-10)", provider=provider,
+ )
+
+
+def tool_result_output_openai(provider: str, part: ToolResultPart, policy: str) -> str | list[dict[str, Any]]:
+ """`function_call_output.output` (MAP-10): a string when the content is
+ text-only, the documented array of input_text/input_image/input_file
+ blocks otherwise; a media part the preset does not admit raises first.
+ `is_error` rides as an `[error] ` prefix on the text (rule 5)."""
+ check_tool_result_media(provider, part, policy, wire="function_call_output")
+ if all(p.type not in MEDIA_KINDS for p in part.content):
+ return tool_result_error_text(part, parts_to_text(part.content, provider=provider, where="function_call_output"))
+ blocks: list[dict[str, Any]] = []
+ for p in part.content:
+ block = part_to_openai_input(p, provider=provider)
+ blocks.append(block)
+ if part.is_error:
+ first = next((b for b in blocks if b.get("type") == "input_text"), None)
+ if first is None:
+ blocks.insert(0, {"type": "input_text", "text": "[error]"})
+ else:
+ first["text"] = "[error] " + first["text"]
+ return blocks
+
+
+def message_to_openai_input(msg: Message) -> dict[str, Any]:
+ return {"role": msg.role, "content": [part_to_openai_input(p) for p in msg.parts]}
+
+
+def anthropic_source(part: ImagePart | DocumentPart | BinaryPart) -> dict[str, Any]:
+ if part.url is not None:
+ return {"type": "url", "url": part.url}
+ if part.file_id is not None:
+ return {"type": "file", "file_id": part.file_id}
+ if part.data is not None:
+ return {"type": "base64", "media_type": part.media_type, "data": part.data}
+ if part.path is not None:
+ data = base64.b64encode(part.path.read_bytes()).decode("ascii")
+ return {"type": "base64", "media_type": part.media_type, "data": data}
+ raise ValueError(f"{part.type} part has no usable source")
+
+
+def openai_token_logprobs(entries: Any) -> tuple[TokenLogprob, ...]:
+ """Map OpenAI-style logprob entries to canonical TokenLogprob tuples.
+
+ Both OpenAI wire dialects share the entry shape (verified live
+ 2026-09-01): ``{token, logprob, bytes, top_logprobs: [{token, logprob,
+ bytes}]}``. Non-list input and malformed entries yield ().
+ """
+ if not isinstance(entries, list):
+ return ()
+ out: list[TokenLogprob] = []
+ for entry in entries:
+ if not isinstance(entry, dict) or "token" not in entry or "logprob" not in entry:
+ continue
+ top: list[TopLogprob] = []
+ for alt in entry.get("top_logprobs") or []:
+ if not isinstance(alt, dict) or "token" not in alt or "logprob" not in alt:
+ continue
+ alt_bytes = alt.get("bytes")
+ top.append(
+ TopLogprob(
+ token=str(alt["token"]),
+ logprob=float(alt["logprob"]),
+ bytes=tuple(alt_bytes) if isinstance(alt_bytes, list) else None,
+ )
+ )
+ entry_bytes = entry.get("bytes")
+ out.append(
+ TokenLogprob(
+ token=str(entry["token"]),
+ logprob=float(entry["logprob"]),
+ bytes=tuple(entry_bytes) if isinstance(entry_bytes, list) else None,
+ top=tuple(top),
+ )
+ )
+ return tuple(out)
+
+
+def unnamed_tool_call_error(provider: str, path: str) -> "ProviderError":
+ """MAP-9 on the complete path (changes/2026-09-07-complete-tool-call-no-guess.md):
+ a tool call the provider sent without a name is not actionable, and lm15
+ never guesses which tool the model meant."""
+ from ..errors import ProviderError
+
+ return ProviderError(
+ f"{provider}: {path} is a tool call with no name; lm15 does not guess "
+ "which tool the model meant (MAP-9)",
+ provider=provider,
+ )
+
+
+def parse_json_object(value: Any) -> dict[str, Any]:
+ if isinstance(value, dict):
+ return value
+ if isinstance(value, str) and value:
+ try:
+ parsed = json.loads(value)
+ except Exception:
+ return {"partial_json": value}
+ if isinstance(parsed, dict):
+ return parsed
+ return {"value": parsed}
+ return {}
+
+
+def iso_utc(value: object) -> str | None:
+ """Normalize a provider timestamp (unix epoch or ISO-8601 string) to
+ canonical ``YYYY-MM-DDTHH:MM:SSZ``. Returns None when unparseable —
+ the raw value stays available in provider_data."""
+ import datetime
+
+ try:
+ if isinstance(value, bool) or value is None:
+ return None
+ if isinstance(value, (int, float)):
+ dt = datetime.datetime.fromtimestamp(float(value), tz=datetime.timezone.utc)
+ elif isinstance(value, str) and value:
+ text = value.strip()
+ if text.endswith("Z"):
+ text = text[:-1] + "+00:00"
+ # datetime.fromisoformat rejects >6 fractional digits (Gemini
+ # emits nanoseconds); trim the fraction to microseconds.
+ import re
+
+ text = re.sub(r"\.(\d{6})\d+", r".\1", text)
+ dt = datetime.datetime.fromisoformat(text)
+ if dt.tzinfo is None:
+ dt = dt.replace(tzinfo=datetime.timezone.utc)
+ dt = dt.astimezone(datetime.timezone.utc)
+ else:
+ return None
+ return dt.strftime("%Y-%m-%dT%H:%M:%SZ")
+ except (ValueError, OverflowError, OSError):
+ return None
+
+
+def multipart_form_body(
+ *,
+ fields: list[tuple[str, str]] | None = None,
+ files: list[tuple[str, str, str, bytes]] | None = None,
+) -> tuple[str, bytes]:
+ """Build a multipart/form-data body (OpenAI and Anthropic file uploads).
+
+ ``files`` entries are ``(field_name, filename, content_type, data)``.
+ Returns ``(content_type_header_value, body)``.
+ """
+ import uuid
+
+ boundary = f"lm15-{uuid.uuid4().hex}"
+ chunks: list[bytes] = []
+ for name, value in fields or []:
+ chunks.append(f"--{boundary}\r\n".encode("utf-8"))
+ chunks.append(f'Content-Disposition: form-data; name="{name}"\r\n\r\n'.encode("utf-8"))
+ chunks.append(f"{value}\r\n".encode("utf-8"))
+ for name, filename, content_type, data in files or []:
+ safe_filename = filename.replace('"', "%22")
+ chunks.append(f"--{boundary}\r\n".encode("utf-8"))
+ chunks.append(
+ f'Content-Disposition: form-data; name="{name}"; filename="{safe_filename}"\r\n'.encode("utf-8")
+ )
+ chunks.append(f"Content-Type: {content_type}\r\n\r\n".encode("utf-8"))
+ chunks.append(data)
+ chunks.append(b"\r\n")
+ chunks.append(f"--{boundary}--\r\n".encode("utf-8"))
+ return f"multipart/form-data; boundary={boundary}", b"".join(chunks)
+
+
+def multipart_related_body(
+ *,
+ metadata: dict[str, Any],
+ media_type: str,
+ data: bytes,
+) -> tuple[str, bytes]:
+ """Build a multipart/related body (Gemini media upload: JSON metadata
+ part followed by one media part). Returns ``(content_type, body)``."""
+ import uuid
+
+ boundary = f"lm15-{uuid.uuid4().hex}"
+ chunks: list[bytes] = [
+ f"--{boundary}\r\n".encode("utf-8"),
+ b"Content-Type: application/json; charset=UTF-8\r\n\r\n",
+ json_dumps(metadata),
+ b"\r\n",
+ f"--{boundary}\r\n".encode("utf-8"),
+ f"Content-Type: {media_type}\r\n\r\n".encode("utf-8"),
+ data,
+ b"\r\n",
+ f"--{boundary}--\r\n".encode("utf-8"),
+ ]
+ return f"multipart/related; boundary={boundary}", b"".join(chunks)
+
+
+# ─── MAP-7: the one effort→budget grading table ──────────────────────
+#
+# Budget-only model classes (Anthropic 4.5 and earlier, Gemini 2.5) have
+# no effort level on the wire; the universal dial is expressed as a
+# thinking-token budget through this single, stated table. Receipted on
+# both providers 2026-09-02 (research/reasoning). Provider floors and
+# ceilings are the provider's: Anthropic rejects < 1024, Gemini 2.5 Flash
+# rejects > 24576 — loudly.
+EFFORT_THINKING_BUDGETS: dict[str, int] = {
+ "minimal": 1024,
+ "low": 2048,
+ "medium": 8192,
+ "high": 16384,
+ "xhigh": 24576,
+ "max": 32768,
+}
diff --git a/dspy/_vendor/lm15/providers/gemini.py b/dspy/_vendor/lm15/providers/gemini.py
new file mode 100644
index 000000000..cd249a50b
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/gemini.py
@@ -0,0 +1,1957 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import base64
+import json
+import os
+import struct
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable, ClassVar, Iterator, Mapping
+
+from ..errors import (
+ AuthError,
+ BillingError,
+ ContextLengthError,
+ InvalidRequestError,
+ ProviderError,
+ RateLimitError,
+ ServerError,
+ TimeoutError,
+ UnsupportedFeatureError,
+ UnsupportedModelError,
+ canonical_error_code,
+ map_http_error,
+)
+from ..access import GEMINI_API
+from ..features import ProviderManifest
+from ..live import WebSocketLiveSession, require_websocket_sync_connect
+from ..sse import SSEEvent
+from ..transports import TransportRequest
+from ..types import (
+ CacheInfo,
+ CachePage,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ VideoPart,
+ AudioDelta,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ AudioPart,
+ BatchEntry,
+ BatchJobInfo,
+ BatchRequest,
+ ContinuationDelta,
+ ContinuationState,
+ BinaryPart,
+ BuiltinTool,
+ CitationPart,
+ Config,
+ DocumentPart,
+ ErrorDetail,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ FunctionTool,
+ ImageDelta,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ ImagePart,
+ LiveClientAudioEvent,
+ LiveClientEndAudioEvent,
+ LiveClientEvent,
+ LiveClientImageEvent,
+ LiveClientInterruptEvent,
+ LiveClientTextEvent,
+ LiveClientToolResultEvent,
+ LiveClientTurnEvent,
+ LiveConfig,
+ LiveServerAudioEvent,
+ LiveServerErrorEvent,
+ LiveServerInterruptedEvent,
+ LiveServerTextEvent,
+ LiveServerToolCallEvent,
+ LiveServerTurnEndEvent,
+ LiveServerUsageEvent,
+ Message,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ StreamEvent,
+ StreamStartEvent,
+ TextDelta,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ TokenLogprob,
+ ToolCallDelta,
+ ToolCallPart,
+ ToolResultPart,
+ TopLogprob,
+ continuation_data,
+ Usage,
+)
+from .base import (
+ BaseProviderLM,
+ Credential,
+ HttpResponse,
+ SyncTransport,
+ batch_entry_http,
+ batch_entry_request,
+ default_transport,
+ resolve_credential,
+)
+from .common import EFFORT_THINKING_BUDGETS, MEDIA_KINDS, build_url, iso_utc, model_infos_from_entries, multipart_related_body, parts_to_text, path_id, unnamed_tool_call_error
+
+# Canonical builtin tool name → Gemini tool key
+_GEMINI_BUILTIN_MAP: dict[str, str] = {
+ "web_search": "googleSearch",
+ "code_execution": "codeExecution",
+}
+
+GEMINI_PROVIDER_EXECUTED_PART_KEYS = {
+ "executableCode",
+ "codeExecutionResult",
+}
+
+def gemini_level_class(model: str) -> bool:
+ """True for the Gemini 3.x class: `thinkingLevel`, no full off (MAP-7 rule 10).
+
+ Model-name table, receipted 2026-09-02: 2.5 models reject thinkingLevel,
+ 3.x models take it; 3.7 Flash accepts thinkingBudget: 0 and still spends
+ thinking tokens. A table that rots; `extensions` overrides.
+ """
+ lowered = model.lower()
+ return lowered.startswith("models/gemini-3") or lowered.startswith("gemini-3")
+
+
+
+
+def _attach_unmapped(provider_data: dict[str, Any], unmapped: list[dict[str, str]]) -> dict[str, Any]:
+ if not unmapped:
+ return provider_data
+ out = dict(provider_data)
+ out["_lm15_unmapped"] = unmapped
+ return out
+
+
+def _record_unmapped(unmapped: list[dict[str, str]], path: str, typ: Any) -> None:
+ unmapped.append({"path": path, "type": str(typ or "<missing>")})
+
+
+def _builtin_to_gemini(tool: BuiltinTool) -> dict[str, Any]:
+ return {_GEMINI_BUILTIN_MAP.get(tool.name, tool.name): tool.config or {}}
+
+
+def _gemini_token_logprobs(logprobs_result: Any) -> tuple[TokenLogprob, ...]:
+ """Map Gemini logprobsResult to canonical TokenLogprob tuples.
+
+ Doc-based mapping (generate-content reference — LogprobsResult /
+ TopCandidates / Candidate): chosenCandidates[i] pairs with
+ topCandidates[i] per decoding step. No live capture exists because
+ every currently served model rejects responseLogprobs (2026-09-01).
+ Derived aggregates (logProbabilitySum, avgLogprobs) stay in
+ provider_data — they are computable from the per-token values.
+ """
+ if not isinstance(logprobs_result, dict):
+ return ()
+ chosen = logprobs_result.get("chosenCandidates") or []
+ top_steps = logprobs_result.get("topCandidates") or []
+ out: list[TokenLogprob] = []
+ for i, cand in enumerate(chosen):
+ if not isinstance(cand, dict):
+ continue
+ top: list[TopLogprob] = []
+ step = top_steps[i] if i < len(top_steps) and isinstance(top_steps[i], dict) else {}
+ for alt in step.get("candidates") or []:
+ if not isinstance(alt, dict):
+ continue
+ top.append(
+ TopLogprob(
+ token=str(alt.get("token") or ""),
+ logprob=float(alt.get("logProbability", 0.0) or 0.0),
+ token_id=alt.get("tokenId"),
+ )
+ )
+ out.append(
+ TokenLogprob(
+ token=str(cand.get("token") or ""),
+ logprob=float(cand.get("logProbability", 0.0) or 0.0),
+ token_id=cand.get("tokenId"),
+ top=tuple(top),
+ )
+ )
+ return tuple(out)
+
+
+def _gemini_schema_field(schema: dict[str, Any]) -> str:
+ """Pick Gemini's schema field for an lm15 JSON schema.
+
+ ``responseSchema`` is Gemini's OpenAPI-ish schema type and rejects JSON
+ Schema keywords such as ``additionalProperties``. ``responseJsonSchema``
+ accepts those keywords, so use it when the schema needs full JSON Schema.
+ """
+ return "responseJsonSchema" if _contains_key(schema, "additionalProperties") else "responseSchema"
+
+
+def _contains_key(value: Any, key: str) -> bool:
+ if isinstance(value, dict):
+ return key in value or any(_contains_key(v, key) for v in value.values())
+ if isinstance(value, list):
+ return any(_contains_key(v, key) for v in value)
+ return False
+
+
+def _gemini_number(value: float) -> float | int:
+ """Gemini wire dialect: integral float knobs are sent in integer form.
+
+ The canonical model declares temperature/top_p as float fields (Number
+ rule, docs/serde-rules.md), but Gemini's proto3-JSON wire form for
+ integral doubles is the integer digits (live capture:
+ lm15-contract/cases/gemini/temperature.json sends ``"temperature": 1``).
+ This is a provider wire-dialect mapping, not a canonical form.
+ """
+ if isinstance(value, float) and value.is_integer():
+ return int(value)
+ return value
+
+
+def _response_format_to_gemini_config(format_config: dict[str, Any]) -> dict[str, Any]:
+ """Canonical response_format (INV-050) -> Gemini generationConfig.
+
+ `responseJsonSchema` accepts JSON Schema keywords; `responseSchema` is
+ the OpenAPI subset — `_gemini_schema_field` picks by the presence of
+ `additionalProperties` (pinned by gemini.response_schema and the
+ 2026-09-02 receipts). `strict` is satisfied (always constrained);
+ `name` is a label with no slot.
+ """
+ if format_config["type"] == "json_object":
+ return {"responseMimeType": "application/json"}
+ schema = format_config["schema"]
+ return {"responseMimeType": "application/json", _gemini_schema_field(schema): schema}
+
+
+def _gemini_usage(usage_payload: Any, *, output_keys: tuple[str, ...]) -> Usage:
+ """Map a Gemini ``usageMetadata`` object to canonical Usage (INV-029).
+
+ Gemini's proto3-JSON wire omits zero-valued fields, so inside a present
+ ``usageMetadata`` an absent primary counter means "0", not "not
+ reported" (pinned: lm15-contract goldens/gemini/max_output_tokens.json,
+ where ``candidatesTokenCount`` is absent and ``totalTokenCount`` equals
+ prompt + thoughts). When ``usageMetadata`` itself is missing nothing
+ was reported and every counter stays None. Secondary counters are
+ conditional on a feature (cache, thinking) and stay verbatim: absent is
+ "not reported". ``output_keys`` lists the wire names for output tokens
+ in priority order (``candidatesTokenCount`` on generateContent,
+ ``responseTokenCount`` on Live).
+ """
+ if not isinstance(usage_payload, dict) or not usage_payload:
+ return Usage()
+ output_tokens: Any = 0
+ for key in output_keys:
+ if key in usage_payload:
+ output_tokens = usage_payload[key]
+ break
+ return Usage(
+ input_tokens=usage_payload.get("promptTokenCount", 0),
+ output_tokens=output_tokens,
+ total_tokens=usage_payload.get("totalTokenCount"),
+ cache_read_tokens=usage_payload.get("cachedContentTokenCount"),
+ reasoning_tokens=usage_payload.get("thoughtsTokenCount"),
+ # Modality breakdowns: {modality, tokenCount} entries. AUDIO has a
+ # canonical slot on both sides (OpenAI fills the same slots); IMAGE
+ # and VIDEO do not and stay in provider_data. Independent review
+ # 2026-09-02: three goldens carried audio counts nowhere.
+ input_audio_tokens=_modality_tokens(usage_payload.get("promptTokensDetails"), "AUDIO"),
+ output_audio_tokens=_modality_tokens(
+ usage_payload.get("candidatesTokensDetails") or usage_payload.get("responseTokensDetails"), "AUDIO"
+ ),
+ )
+
+
+def _modality_tokens(details: Any, modality: str) -> int | None:
+ """Sum of ``tokenCount`` over the entries for ``modality``; None when the
+ breakdown has no such entry (not reported, per INV-029)."""
+ if not isinstance(details, list):
+ return None
+ counts = [e.get("tokenCount", 0) for e in details if isinstance(e, dict) and e.get("modality") == modality]
+ return sum(counts) if counts else None
+
+
+def _thought_signature_state(part: dict[str, Any]) -> tuple[ContinuationState, ...]:
+ """The part's ``thoughtSignature`` as canonical replay state, or ()."""
+ signature = part.get("thoughtSignature")
+ if signature is None:
+ return ()
+ return (ContinuationState(provider="gemini", kind="thought_signature", data={"value": str(signature)}),)
+
+
+def _finish_reason(reason: str | None, *, has_tool_call: bool = False) -> str:
+ if has_tool_call:
+ return "tool_call"
+ r = str(reason or "").upper()
+ if r == "MAX_TOKENS":
+ return "length"
+ if r in {"SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII"}:
+ return "content_filter"
+ return "stop"
+
+
+def _gemini_batch_status(data: dict[str, Any]) -> str:
+ """Map a Gemini batch operation to the canonical BatchStatus.
+
+ States observed live 2026-08-31: BATCH_STATE_PENDING / RUNNING /
+ SUCCEEDED (wire fact — the docs' JOB_STATE_* naming is wrong for
+ this endpoint).
+ """
+ state = str((data.get("metadata") or {}).get("state") or "").upper()
+ mapping = {
+ "BATCH_STATE_PENDING": "queued",
+ "BATCH_STATE_RUNNING": "running",
+ "BATCH_STATE_CANCELLING": "cancelling",
+ "BATCH_STATE_SUCCEEDED": "completed",
+ "BATCH_STATE_FAILED": "failed",
+ "BATCH_STATE_CANCELLED": "cancelled",
+ "BATCH_STATE_EXPIRED": "expired",
+ }
+ if state in mapping:
+ return mapping[state]
+ return "completed" if data.get("done") else "queued"
+
+
+def _int_or_none(value: Any) -> int | None:
+ if isinstance(value, bool) or value is None:
+ return None
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _gemini_segment_text(segment: dict[str, Any], full_text: str) -> str | None:
+ text = segment.get("text")
+ if isinstance(text, str) and text:
+ return text
+ start = _int_or_none(segment.get("startIndex"))
+ end = _int_or_none(segment.get("endIndex"))
+ if start is not None and end is not None and 0 <= start < end <= len(full_text):
+ return full_text[start:end]
+ return None
+
+
+def _gemini_grounding_chunk(chunks: list[Any], index: Any) -> dict[str, Any]:
+ idx = _int_or_none(index)
+ if idx is None or idx < 0 or idx >= len(chunks):
+ return {}
+ chunk = chunks[idx]
+ return chunk if isinstance(chunk, dict) else {}
+
+
+def _gemini_citations(candidate: dict[str, Any], full_text: str) -> list[CitationPart]:
+ grounding = candidate.get("groundingMetadata")
+ if not isinstance(grounding, dict):
+ return []
+
+ chunks = grounding.get("groundingChunks") or []
+ if not isinstance(chunks, list):
+ chunks = []
+ supports = grounding.get("groundingSupports") or []
+ if not isinstance(supports, list):
+ return []
+
+ citations: list[CitationPart] = []
+ seen: set[tuple[str | None, str | None, str | None]] = set()
+ for support in supports:
+ if not isinstance(support, dict):
+ continue
+ segment = support.get("segment") if isinstance(support.get("segment"), dict) else {}
+ cited_text = _gemini_segment_text(segment, full_text)
+ indices = support.get("groundingChunkIndices") or []
+ if not isinstance(indices, list):
+ continue
+ for index in indices:
+ chunk = _gemini_grounding_chunk(chunks, index)
+ source = chunk.get("web") or chunk.get("retrievedContext") or chunk.get("googleSearch") or {}
+ if not isinstance(source, dict):
+ source = {}
+ url = source.get("uri") or source.get("url")
+ title = source.get("title") or source.get("name")
+ url_s = str(url) if url else None
+ title_s = str(title) if title else None
+ key = (url_s, title_s, cited_text)
+ if key in seen or (url_s is None and title_s is None and cited_text is None):
+ continue
+ seen.add(key)
+ citations.append(CitationPart(url=url_s, title=title_s, text=cited_text))
+ return citations
+
+
+_DEFAULT_BASE_URL = "https://generativelanguage.googleapis.com/v1beta"
+
+
+@dataclass(slots=True)
+class GeminiLM(BaseProviderLM):
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: SyncTransport = field(default_factory=default_transport)
+ base_url: str = _DEFAULT_BASE_URL
+ upload_base_url: str = "https://generativelanguage.googleapis.com/upload/v1beta"
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="gemini", init=False)
+ account_id: str | None = field(default=None, init=False, repr=False)
+ manifest: ClassVar[ProviderManifest] = GEMINI_API
+ _api_key_header: ClassVar[str] = "x-goog-api-key"
+
+ def __post_init__(self) -> None:
+ self._bind_access(self.access, credentials_path=self.credentials_path, default_base_url=_DEFAULT_BASE_URL, settings=self.settings)
+
+ _error_status_map: ClassVar[dict[str, type[ProviderError]]] = {
+ "INVALID_ARGUMENT": InvalidRequestError,
+ "FAILED_PRECONDITION": BillingError,
+ "PERMISSION_DENIED": AuthError,
+ "UNAUTHENTICATED": AuthError,
+ "NOT_FOUND": InvalidRequestError,
+ "RESOURCE_EXHAUSTED": RateLimitError,
+ "INTERNAL": ServerError,
+ "UNAVAILABLE": ServerError,
+ "DEADLINE_EXCEEDED": TimeoutError,
+ }
+
+ @staticmethod
+ def _is_context_length_message(msg: str) -> bool:
+ lowered = msg.lower()
+ return (
+ ("token" in lowered and ("limit" in lowered or "exceed" in lowered))
+ or "too long" in lowered
+ or "context is too long" in lowered
+ or "context length" in lowered
+ )
+
+ @staticmethod
+ def _is_model_error(message: str) -> bool:
+ lowered = message.lower()
+ return "model" in lowered and any(
+ marker in lowered
+ for marker in (
+ "not found",
+ "does not exist",
+ "not exist",
+ "not supported",
+ "unsupported",
+ "not available",
+ "unknown",
+ )
+ )
+
+ @staticmethod
+ def _is_candidate_finish_error(finish_reason: str) -> bool:
+ return finish_reason in {
+ "SAFETY",
+ "RECITATION",
+ "LANGUAGE",
+ "BLOCKLIST",
+ "PROHIBITED_CONTENT",
+ "SPII",
+ "MALFORMED_FUNCTION_CALL",
+ "IMAGE_SAFETY",
+ "IMAGE_PROHIBITED_CONTENT",
+ "IMAGE_OTHER",
+ "NO_IMAGE",
+ "IMAGE_RECITATION",
+ "UNEXPECTED_TOOL_CALL",
+ "TOO_MANY_TOOL_CALLS",
+ "MISSING_THOUGHT_SIGNATURE",
+ "MALFORMED_RESPONSE",
+ }
+
+ def _error_detail(self, provider_code: str, message: str) -> ErrorDetail:
+ cls = self._error_status_map.get(provider_code, ProviderError)
+ if self._is_context_length_message(message):
+ cls = ContextLengthError
+ elif provider_code == "NOT_FOUND" and self._is_model_error(message):
+ cls = UnsupportedModelError
+ return ErrorDetail(
+ code=canonical_error_code(cls),
+ message=message or provider_code or "provider error",
+ provider_code=provider_code or "provider",
+ )
+
+ def _inband_error(self, data: dict[str, Any]) -> ProviderError | None:
+ prompt_feedback = data.get("promptFeedback")
+ if isinstance(prompt_feedback, dict):
+ block_reason = str(prompt_feedback.get("blockReason") or "")
+ if block_reason and block_reason != "BLOCK_REASON_UNSPECIFIED":
+ return self._provider_error(
+ InvalidRequestError,
+ f"Prompt blocked: {block_reason}",
+ provider_code="promptFeedback",
+ )
+
+ candidate = (data.get("candidates") or [{}])[0]
+ if isinstance(candidate, dict):
+ finish_reason = str(candidate.get("finishReason") or "")
+ if self._is_candidate_finish_error(finish_reason):
+ finish_message = str(candidate.get("finishMessage") or "")
+ return self._provider_error(
+ InvalidRequestError,
+ finish_message or f"Candidate blocked: {finish_reason}",
+ provider_code=finish_reason or "finishReason",
+ )
+ return None
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ try:
+ data = json.loads(body)
+ err = data.get("error", {}) if isinstance(data, dict) else {}
+ msg = err.get("message", "") if isinstance(err, dict) else str(err)
+ err_status = str(err.get("status") or "") if isinstance(err, dict) else ""
+ if self._is_context_length_message(msg):
+ return self._provider_error(
+ ContextLengthError,
+ msg,
+ status=status,
+ provider_code=err_status or None,
+ )
+ if err_status == "NOT_FOUND" and self._is_model_error(msg):
+ return self._provider_error(
+ UnsupportedModelError,
+ msg,
+ status=status,
+ provider_code=err_status,
+ )
+ cls = self._error_status_map.get(err_status)
+ if cls:
+ return self._provider_error(
+ cls,
+ msg,
+ status=status,
+ provider_code=err_status or None,
+ )
+ if err_status and err_status not in msg:
+ msg = f"{msg} ({err_status})"
+ except Exception:
+ msg = body.strip()[:500] or f"HTTP {status}"
+ err_status = ""
+ return map_http_error(
+ status,
+ msg,
+ provider=self.provider,
+ env_keys=self.access.env_keys,
+ provider_code=err_status or None,
+ )
+
+ # ─── Request serialization ──────────────────────────────────────
+
+ def _model_path(self, model: str) -> str:
+ model = urllib.parse.quote(model, safe="/:@")
+ return model if model.startswith("models/") else f"models/{model}"
+
+ def _auth_headers(self, extra: dict[str, str] | None = None) -> dict[str, str]:
+ headers: dict[str, str] = {} # auth is applied once, in _emit (AUTH-2)
+ if extra:
+ headers.update(extra)
+ return headers
+
+ def _auth_params(self, extra: dict[str, Any] | None = None) -> dict[str, Any]:
+ return dict(extra or {})
+
+ def _function_response(self, part: ToolResultPart, names: dict[str, str] | None) -> dict[str, Any]:
+ """`functionResponse` (MAP-10 on this wire): text in `response.result`
+ (`response.error` when is_error), media nested under `parts[]` as
+ inlineData/fileData in the caller's order; the name resolved from the
+ transcript's matching functionCall when the caller gave none (rule 6).
+ Every model takes the shape; Gemini 2.5 answers HTTP 400 itself."""
+ text_parts = tuple(p for p in part.content if p.type not in MEDIA_KINDS)
+ media_parts = [p for p in part.content if p.type in MEDIA_KINDS]
+ for p in media_parts:
+ if p.type not in ("image", "document"):
+ raise UnsupportedFeatureError(
+ f"{self.provider}: a {p.type} part in tool_result {part.id!r} cannot reach a functionResponse — "
+ "multimodal function responses take images (png/jpeg/webp) and documents (pdf, text/plain) only (MAP-10)",
+ provider=self.provider,
+ )
+ name = part.name or (names or {}).get(part.id)
+ if not name:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: tool_result {part.id!r} needs a function name on the Gemini wire and no preceding "
+ "assistant tool_call with that id is in the transcript; set ToolResultPart.name (MAP-10 rule 6)",
+ provider=self.provider,
+ )
+ text = parts_to_text(text_parts, provider=self.provider, where="functionResponse.response")
+ if part.is_error:
+ response: dict[str, Any] = {"error": text}
+ elif media_parts and not text_parts:
+ response = {} # the media IS the result; no fabricated text (live 2026-09-07: accepted)
+ else:
+ response = {"result": text}
+ fr: dict[str, Any] = {"name": name, "response": response}
+ if part.id:
+ fr["id"] = part.id
+ if media_parts:
+ fr["parts"] = [self._part(p) for p in media_parts]
+ return {"functionResponse": fr}
+
+ def _part(self, part, names: dict[str, str] | None = None) -> dict[str, Any]:
+ if isinstance(part, TextPart):
+ out: dict[str, Any] = {"text": part.text}
+ thought = continuation_data(part, "gemini", "thought_signature")
+ if thought and thought.get("value"):
+ out["thoughtSignature"] = thought["value"]
+ return out
+ if isinstance(part, (ImagePart, AudioPart, VideoPart, DocumentPart, BinaryPart)):
+ mime = part.media_type or "application/octet-stream"
+ if part.url is not None:
+ return {"fileData": {"mimeType": mime, "fileUri": part.url}}
+ if part.file_id is not None:
+ return {"fileData": {"mimeType": mime, "fileUri": part.file_id}}
+ if part.data is not None:
+ return {"inlineData": {"mimeType": mime, "data": part.data}}
+ if part.path is not None:
+ return {"inlineData": {"mimeType": mime, "data": base64.b64encode(part.path.read_bytes()).decode("ascii")}}
+ if isinstance(part, ToolCallPart):
+ out: dict[str, Any] = {"functionCall": {"name": part.name, "args": part.input}}
+ if part.id:
+ out["functionCall"]["id"] = part.id
+ thought = continuation_data(part, "gemini", "thought_signature")
+ if thought and thought.get("value"):
+ out["thoughtSignature"] = thought["value"]
+ return out
+ if isinstance(part, ToolResultPart):
+ return self._function_response(part, names)
+ if isinstance(part, ThinkingPart):
+ out: dict[str, Any] = {"text": part.text}
+ thought = continuation_data(part, "gemini", "thought_signature")
+ if thought and thought.get("value"):
+ out["thought"] = True
+ out["thoughtSignature"] = thought["value"]
+ return out
+ return {"text": getattr(part, "text", "") or ""}
+
+ def _message(self, msg: Message, names: dict[str, str] | None = None) -> dict[str, Any]:
+ role = "model" if msg.role == "assistant" else "user"
+ if msg.role == "developer":
+ return {"role": "user", "parts": [{"text": f"[developer]\n{parts_to_text(msg.parts, provider=self.provider, where='a developer turn')}"}]}
+ return {"role": role, "parts": [self._part(part, names) for part in msg.parts]}
+
+ @staticmethod
+ def _call_names(messages) -> dict[str, str]:
+ """tool_call id → function name, over the transcript (MAP-10 rule 6)."""
+ names: dict[str, str] = {}
+ for m in messages:
+ for p in m.parts:
+ if isinstance(p, ToolCallPart) and p.id:
+ names[p.id] = p.name
+ return names
+
+ def _tool_config_payload(self, request: Request) -> dict[str, Any] | None:
+ tc = request.config.tool_choice
+ if tc is None:
+ return None
+ if tc.parallel is False:
+ # MAP-8 rule 2 (live 2026-09-02): no wire knob; two calls came back
+ # on 2.5 and 3.7 with the preference set. The outcome is not
+ # observable from usage, so the MAP-6 fallback exception does not
+ # apply — raise.
+ raise UnsupportedFeatureError(
+ "gemini: tool_choice.parallel=False is not supported — GenerateContent has no "
+ "parallel-tool-calls knob and returns several calls regardless (OpenAI and "
+ "Anthropic carry it)",
+ provider=self.provider,
+ )
+ mode = {"none": "NONE", "required": "ANY", "auto": "AUTO"}[tc.mode]
+ cfg: dict[str, Any] = {"mode": mode}
+ if tc.allowed:
+ by_name = {t.name: t for t in request.tools}
+ builtins = [name for name in tc.allowed if isinstance(by_name.get(name), BuiltinTool)]
+ if builtins:
+ raise UnsupportedFeatureError(
+ f"gemini: cannot force builtin tools {builtins} — "
+ "functionCallingConfig addresses function declarations only; "
+ "googleSearch/codeExecution have no tool_choice form "
+ "(OpenAI Responses and Anthropic carry builtin forcing)",
+ provider=self.provider,
+ )
+ cfg["allowedFunctionNames"] = list(tc.allowed)
+ if tc.mode == "auto":
+ # allowedFunctionNames is only legal with ANY or VALIDATED.
+ # VALIDATED = "function call or text, restricted to the
+ # allowlist" — exactly canonical mode=auto + allowed.
+ cfg["mode"] = "VALIDATED"
+ return {"functionCallingConfig": cfg}
+
+ def _payload(self, request: Request) -> dict[str, Any]:
+ extensions = dict(request.config.extensions or {})
+ cache_cfg = request.config.cache
+ # MAP-6 on Gemini. Automatic tier: nothing to send; prefix intents
+ # fall back to it (no cost, visible in usageMetadata). Resource
+ # tier: `cachedContent` names a stored object that already holds
+ # system, tools, and the prefix messages, so the wire carries only
+ # the suffix — the server rejects system/tools next to a cache.
+ # key / retention name mechanisms this wire does not have.
+ resource: str | None = None
+ suffix_from = 0
+ if cache_cfg is not None and cache_cfg.mode != "off":
+ if cache_cfg.key is not None:
+ raise UnsupportedFeatureError(
+ "gemini: cache.key is not supported — GenerateContent has no cache "
+ "affinity key; use cache.resource with a stored cache (lm.cache(prefix))",
+ provider=self.provider,
+ )
+ if cache_cfg.retention is not None and cache_cfg.retention != "short":
+ raise UnsupportedFeatureError(
+ "gemini: cache.retention is not supported in-request — lifetime belongs to "
+ "the stored cache (cache_create(..., ttl_seconds=...) / cache_update)",
+ provider=self.provider,
+ )
+ if cache_cfg.resource is not None:
+ resource = cache_cfg.resource
+ if cache_cfg.prefix_until_index is not None:
+ suffix_from = min(cache_cfg.prefix_until_index, len(request.messages) - 1) + 1
+ wire_messages = request.messages[suffix_from:]
+ if resource is not None and not wire_messages:
+ raise ValueError("gemini: a request against a stored cache needs at least one message after the prefix")
+
+ names = self._call_names(request.messages)
+ payload: dict[str, Any] = {"contents": [self._message(m, names) for m in wire_messages]}
+ if resource is not None:
+ payload["cachedContent"] = self._cache_resource(resource)
+ if request.system and resource is None:
+ text = request.system if isinstance(request.system, str) else parts_to_text(request.system)
+ payload["systemInstruction"] = {"parts": [{"text": text}]}
+
+ generation_config: dict[str, Any] = {}
+ if request.config.temperature is not None:
+ generation_config["temperature"] = _gemini_number(request.config.temperature)
+ if request.config.max_tokens is not None:
+ generation_config["maxOutputTokens"] = request.config.max_tokens
+ if request.config.top_p is not None:
+ generation_config["topP"] = _gemini_number(request.config.top_p)
+ if request.config.top_k is not None:
+ generation_config["topK"] = request.config.top_k
+ if request.config.stop:
+ generation_config["stopSequences"] = list(request.config.stop)
+ if request.config.logprobs is not None:
+ # Documented wire knobs (generate-content reference). Live note
+ # 2026-09-01: every currently served Gemini model rejects this
+ # with "Logprobs is not enabled" — the mapping is doc-based and
+ # the rejection surfaces as the provider's InvalidRequestError.
+ generation_config["responseLogprobs"] = True
+ if request.config.logprobs > 0:
+ generation_config["logprobs"] = request.config.logprobs
+ if request.config.response_format:
+ generation_config.update(_response_format_to_gemini_config(request.config.response_format))
+ if request.config.reasoning is not None:
+ reasoning = request.config.reasoning
+ level_class = gemini_level_class(request.model)
+ if reasoning.is_off:
+ if level_class:
+ # MAP-7 rule 4 / MAP-5: Gemini 3.x cannot fully disable
+ # thinking; 3.7 Flash accepts thinkingBudget 0 and still
+ # spent 58 tokens (live 2026-09-02) — a silent paid no-op.
+ raise UnsupportedFeatureError(
+ f"gemini: reasoning cannot be disabled on {request.model} — the Gemini 3 "
+ "class has no full off switch (thinkingBudget 0 is accepted but not honoured); "
+ "use effort='low' or a 2.5 model",
+ provider=self.provider,
+ )
+ generation_config["thinkingConfig"] = {"thinkingBudget": 0}
+ else:
+ if reasoning.summary in ("concise", "detailed"):
+ raise UnsupportedFeatureError(
+ f"gemini: reasoning.summary={reasoning.summary!r} is an OpenAI detail level; "
+ "GenerateContent has includeThoughts only (use 'auto')",
+ provider=self.provider,
+ )
+ thinking: dict[str, Any] = {}
+ if reasoning.summary is not None:
+ thinking["includeThoughts"] = True # MAP-7 rule 7: only when asked
+ if reasoning.thinking_budget is not None:
+ thinking["thinkingBudget"] = reasoning.thinking_budget # 3.x: accepted, docs warn
+ elif level_class:
+ if reasoning.effort in ("xhigh", "max"):
+ raise UnsupportedFeatureError(
+ f"gemini: reasoning.effort={reasoning.effort!r} has no thinkingLevel on the "
+ "Gemini 3 class (minimal|low|medium|high); 'high' is the ceiling",
+ provider=self.provider,
+ )
+ thinking["thinkingLevel"] = reasoning.effort
+ else:
+ thinking["thinkingBudget"] = EFFORT_THINKING_BUDGETS[reasoning.effort]
+ generation_config["thinkingConfig"] = thinking
+ if generation_config:
+ payload["generationConfig"] = generation_config
+
+ if request.tools and resource is None:
+ function_declarations = [
+ {"name": t.name, "description": t.description, "parameters": t.parameters}
+ for t in request.tools
+ if isinstance(t, FunctionTool)
+ ]
+ tools_wire: list[dict[str, Any]] = []
+ if function_declarations:
+ tools_wire.append({"functionDeclarations": function_declarations})
+ for tool in request.tools:
+ if isinstance(tool, BuiltinTool):
+ tools_wire.append(_builtin_to_gemini(tool))
+ payload["tools"] = tools_wire
+
+ tool_config = self._tool_config_payload(request) if resource is None else None
+ if tool_config is not None:
+ payload["toolConfig"] = tool_config
+
+ output = extensions.get("output")
+ if output == "image":
+ payload.setdefault("generationConfig", {})["responseModalities"] = ["IMAGE"]
+ elif output == "audio":
+ payload.setdefault("generationConfig", {})["responseModalities"] = ["AUDIO"]
+
+ # Promoted cross-provider knobs (changes/2026-09-01-extensions-burn-down):
+ # store maps verbatim (same wire key as OpenAI, verified live).
+ # service_tier maps to the top-level `serviceTier` enum
+ # (unspecified|standard|flex|priority) — added to GenerateContent
+ # between the April and September 2026 doc snapshots and verified
+ # live 2026-09-01 (accepted + echoed in usageMetadata.serviceTier;
+ # an unknown value is rejected with HTTP 400 INVALID_ARGUMENT, so
+ # the server validates the field). user_id has no Gemini wire
+ # field — raise, never silently drop.
+ if request.config.store is not None:
+ payload["store"] = request.config.store
+ if request.config.service_tier is not None:
+ payload["serviceTier"] = request.config.service_tier
+ if request.config.user_id is not None:
+ raise UnsupportedFeatureError(
+ "gemini: config.user_id is not supported — GenerateContent has no "
+ "end-user attribution field (OpenAI and Anthropic carry it)",
+ provider=self.provider,
+ )
+
+ if extensions:
+ passthrough = {k: v for k, v in extensions.items() if k not in {"prompt_caching", "output"}}
+ payload.update(passthrough)
+ return payload
+
+ def build_request(self, request: Request, stream: bool) -> TransportRequest:
+ endpoint = "streamGenerateContent" if stream else "generateContent"
+ params = self._auth_params({"alt": "sse"} if stream else None)
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/{self._model_path(request.model)}:{endpoint}",
+ endpoint="generateContent",
+ stream=stream,
+ model=request.model,
+ headers=self._auth_headers({"Content-Type": "application/json"}),
+ params=params,
+ payload=self._payload(request),
+ read_timeout=120.0 if stream else 60.0,
+ )
+
+ # ─── Response parsing ───────────────────────────────────────────
+
+ def _parse_candidate_parts(
+ self,
+ parts_payload: list[dict[str, Any]],
+ *,
+ unmapped: list[dict[str, str]] | None = None,
+ path_prefix: str = "parts",
+ ) -> list[Any]:
+ parts: list[Any] = []
+ for part_index, part in enumerate(parts_payload):
+ if not isinstance(part, dict):
+ if unmapped is not None:
+ _record_unmapped(unmapped, f"{path_prefix}[{part_index}]", type(part).__name__)
+ continue
+ if part.get("thought") and "text" in part:
+ # A thought part is classified by its flag, not by non-empty
+ # text: 3.x can send {thought: true, text: "", thoughtSignature}
+ # and the signature is the replay state (MAP-7 rule 8).
+ parts.append(ThinkingPart(text=str(part.get("text") or ""), continuation=_thought_signature_state(part)))
+ elif "text" in part:
+ # On Gemini 3.x the final answer text carries the turn's
+ # thoughtSignature (independent review 2026-09-02: dropped
+ # silently before). It is replay state exactly as on a
+ # thought or functionCall part, and goes back on the wire.
+ parts.append(TextPart(text=str(part.get("text") or ""), continuation=_thought_signature_state(part)))
+ elif "functionCall" in part and isinstance(part["functionCall"], dict):
+ fc = part["functionCall"]
+ continuation: tuple[ContinuationState, ...] = ()
+ thought_signature = part.get("thoughtSignature") or fc.get("thoughtSignature")
+ if thought_signature is not None:
+ continuation = (
+ ContinuationState(
+ provider="gemini",
+ kind="thought_signature",
+ data={"value": str(thought_signature)},
+ ),
+ )
+ if not fc.get("name"):
+ raise unnamed_tool_call_error(self.provider, f"{path_prefix}[{part_index}]")
+ parts.append(ToolCallPart(
+ # MAP-9: a missing call id is the lm15 correlator tool_call_<index>,
+ # the same one the stream assembler mints (INV-051 parity).
+ id=str(fc.get("id") or f"tool_call_{len(parts)}"),
+ name=str(fc["name"]),
+ input=fc.get("args") if isinstance(fc.get("args"), dict) else {},
+ continuation=continuation,
+ ))
+ elif "inlineData" in part and isinstance(part["inlineData"], dict):
+ inline = part["inlineData"]
+ mime = str(inline.get("mimeType") or "application/octet-stream")
+ data = str(inline.get("data") or "")
+ if not data:
+ continue
+ if mime.startswith("image/"):
+ parts.append(ImagePart(media_type=mime, data=data))
+ elif mime.startswith("audio/"):
+ parts.append(AudioPart(media_type=mime, data=data))
+ else:
+ parts.append(DocumentPart(media_type=mime, data=data))
+ elif "fileData" in part and isinstance(part["fileData"], dict):
+ fd = part["fileData"]
+ uri = str(fd.get("fileUri") or "")
+ mime = str(fd.get("mimeType") or "application/octet-stream")
+ if not uri:
+ continue
+ if mime.startswith("image/"):
+ parts.append(ImagePart(media_type=mime, url=uri))
+ elif mime.startswith("audio/"):
+ parts.append(AudioPart(media_type=mime, url=uri))
+ else:
+ parts.append(DocumentPart(media_type=mime, url=uri))
+ elif any(key in part for key in GEMINI_PROVIDER_EXECUTED_PART_KEYS):
+ continue
+ elif unmapped is not None:
+ _record_unmapped(unmapped, f"{path_prefix}[{part_index}]", "+".join(sorted(part)) or "<empty>")
+ return parts
+
+ def parse_response(self, request: Request, response: HttpResponse) -> Response:
+ data = response.json()
+ inband = self._inband_error(data)
+ if inband is not None:
+ raise inband
+ candidate = (data.get("candidates") or [{}])[0]
+ candidate = candidate if isinstance(candidate, dict) else {}
+ content = candidate.get("content", {}) if isinstance(candidate.get("content"), dict) else {}
+ unmapped: list[dict[str, str]] = []
+ parts = self._parse_candidate_parts(
+ content.get("parts", []) or [],
+ unmapped=unmapped,
+ path_prefix="candidates[0].content.parts",
+ )
+ full_text = "".join(part.text for part in parts if isinstance(part, TextPart))
+ parts.extend(_gemini_citations(candidate, full_text))
+ if not parts:
+ parts = [TextPart(text="")]
+ usage = _gemini_usage(data.get("usageMetadata"), output_keys=("candidatesTokenCount", "responseTokenCount"))
+ has_tool = any(isinstance(part, ToolCallPart) for part in parts)
+ # D8 (2026-09-06): Response.id carries responseId; no message-level
+ # continuation state is minted for it.
+ logprob_seq = _gemini_token_logprobs(candidate.get("logprobsResult"))
+ return Response(
+ id=str(data.get("responseId")) if data.get("responseId") else None,
+ model=request.model,
+ message=Message(role="assistant", parts=tuple(parts)),
+ finish_reason=_finish_reason(candidate.get("finishReason"), has_tool_call=has_tool),
+ usage=usage,
+ logprobs=logprob_seq or None,
+ provider_data=_attach_unmapped(data, unmapped),
+ )
+
+ def parse_stream_events(self, request: Request, raw_event: SSEEvent) -> Iterator[StreamEvent]:
+ if not raw_event.data:
+ return
+ payload = json.loads(raw_event.data)
+ if not isinstance(payload, dict):
+ return
+ if "error" in payload:
+ err = payload["error"]
+ provider_code = str(err.get("status") or err.get("code") or "provider") if isinstance(err, dict) else "provider"
+ message = str(err.get("message") or "") if isinstance(err, dict) else ""
+ yield StreamErrorEvent(error=self._error_detail(provider_code, message))
+ return
+
+ inband = self._inband_error(payload)
+ if inband is not None:
+ yield StreamErrorEvent(error=ErrorDetail(code=canonical_error_code(inband), provider_code="inband_finish_reason", message=str(inband)))
+ return
+
+ candidates = payload.get("candidates") or []
+ candidate = candidates[0] if candidates and isinstance(candidates[0], dict) else None
+ yielded_delta = False
+ saw_tool = False
+ finish = None
+ if candidate is not None:
+ content = candidate.get("content", {}) if isinstance(candidate.get("content"), dict) else {}
+ # Chunk-level decoding telemetry rides the chunk's first text
+ # delta (doc-based; no model currently serves logprobs live).
+ chunk_logprobs = _gemini_token_logprobs(candidate.get("logprobsResult"))
+ for idx, part in enumerate(content.get("parts", []) or []):
+ if not isinstance(part, dict):
+ continue
+ if part.get("thought") and "text" in part:
+ yielded_delta = True
+ yield StreamDeltaEvent(delta=ThinkingDelta(text=str(part.get("text") or ""), part_index=idx))
+ if part.get("thoughtSignature") is not None:
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider="gemini",
+ kind="thought_signature",
+ data={"value": str(part.get("thoughtSignature"))},
+ part_index=idx,
+ )
+ )
+ elif "text" in part:
+ yielded_delta = True
+ yield StreamDeltaEvent(delta=TextDelta(text=str(part.get("text") or ""), part_index=idx, logprobs=chunk_logprobs))
+ chunk_logprobs = ()
+ if part.get("thoughtSignature") is not None:
+ # Same replay state on an answer-text part (3.x).
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider="gemini",
+ kind="thought_signature",
+ data={"value": str(part.get("thoughtSignature"))},
+ part_index=idx,
+ )
+ )
+ elif "functionCall" in part and isinstance(part["functionCall"], dict):
+ fc = part["functionCall"]
+ saw_tool = True
+ yielded_delta = True
+ yield StreamDeltaEvent(delta=ToolCallDelta(
+ input=json.dumps(fc.get("args", {}), separators=(",", ":")),
+ part_index=idx,
+ id=str(fc.get("id") or "") or None,
+ name=str(fc.get("name") or "") or None,
+ ))
+ thought_signature = part.get("thoughtSignature") or fc.get("thoughtSignature")
+ if thought_signature is not None:
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider="gemini",
+ kind="thought_signature",
+ data={"value": str(thought_signature)},
+ part_index=idx,
+ )
+ )
+ elif "inlineData" in part and isinstance(part["inlineData"], dict):
+ inline = part["inlineData"]
+ mime = str(inline.get("mimeType") or "application/octet-stream")
+ data = str(inline.get("data") or "")
+ if mime.startswith("audio/"):
+ yielded_delta = True
+ yield StreamDeltaEvent(delta=AudioDelta(data=data, part_index=idx, media_type=mime))
+ elif mime.startswith("image/"):
+ yielded_delta = True
+ yield StreamDeltaEvent(delta=ImageDelta(data=data, part_index=idx, media_type=mime))
+ finish = candidate.get("finishReason")
+
+ if finish:
+ yield StreamEndEvent(finish_reason=_finish_reason(finish, has_tool_call=saw_tool), usage=self._usage_from_payload(payload), provider_data=payload)
+ elif not yielded_delta and "usageMetadata" in payload:
+ yield StreamEndEvent(finish_reason="stop", usage=self._usage_from_payload(payload), provider_data=payload)
+
+ def _usage_from_payload(self, payload: dict[str, Any]) -> Usage:
+ return _gemini_usage(payload.get("usageMetadata"), output_keys=("candidatesTokenCount", "responseTokenCount"))
+
+ # ─── Streaming via Gemini Live for live models ──────────────────
+
+ def stream(self, request: Request) -> Iterator[StreamEvent]:
+ if self._should_use_live_completion(request):
+ yield from self._stream_via_live_completion(request)
+ return
+ yield from BaseProviderLM.stream(self, request)
+
+ def _should_use_live_completion(self, request: Request) -> bool:
+ extensions = request.config.extensions or {}
+ transport_mode = str(extensions.get("transport") or "").lower()
+ if transport_mode in {"live", "websocket", "ws"}:
+ return True
+ model_name = request.model.lower()
+ return "-live" in model_name or model_name.endswith("live")
+
+ @staticmethod
+ def _is_audio_native_live_model(model: str) -> bool:
+ lowered = model.lower()
+ return "live-preview" in lowered or "native-audio" in lowered
+
+ @staticmethod
+ def _wav_to_pcm(data: bytes) -> tuple[bytes, int]:
+ if len(data) >= 44 and data[:4] == b"RIFF" and data[8:12] == b"WAVE":
+ sample_rate = struct.unpack_from("<I", data, 24)[0]
+ pos = 12
+ while pos + 8 <= len(data):
+ chunk_id = data[pos : pos + 4]
+ chunk_size = struct.unpack_from("<I", data, pos + 4)[0]
+ if chunk_id == b"data":
+ return data[pos + 8 : pos + 8 + chunk_size], sample_rate
+ pos += 8 + chunk_size
+ return data[44:], sample_rate
+ return data, 16000
+
+ def _stream_via_live_completion(self, request: Request) -> Iterator[StreamEvent]:
+ ws = self._live_connect(self._live_url())
+ saw_tool_call = False
+ audio_native = self._is_audio_native_live_model(request.model)
+ acc_usage = Usage()
+ try:
+ setup_payload = self._live_setup_payload_from_request(request)
+ setup_inner = setup_payload.setdefault("setup", {})
+ if not audio_native:
+ setup_inner.setdefault("generationConfig", {}).setdefault("responseModalities", ["TEXT"])
+ ws.send(json.dumps(setup_payload))
+ self._wait_for_setup_complete(ws)
+ for msg in self._live_client_content_payload_from_request(request):
+ ws.send(json.dumps(msg))
+
+ yield StreamStartEvent(model=request.model)
+ while True:
+ raw = ws.recv()
+ events, turn_complete, usage = self._decode_live_completion_stream_events(raw)
+ acc_usage = Usage(
+ input_tokens=max(acc_usage.input_tokens, usage.input_tokens),
+ output_tokens=max(acc_usage.output_tokens, usage.output_tokens),
+ total_tokens=max(acc_usage.total_tokens or 0, usage.total_tokens or 0),
+ )
+ for event in events:
+ if event.type == "delta" and isinstance(event.delta, ToolCallDelta):
+ saw_tool_call = True
+ if event.type == "error":
+ yield event
+ return
+ yield event
+ if turn_complete:
+ yield StreamEndEvent(finish_reason="tool_call" if saw_tool_call else "stop", usage=acc_usage)
+ return
+ finally:
+ try:
+ ws.close()
+ except Exception:
+ pass
+
+ def _live_setup_payload_from_request(self, request: Request) -> dict[str, Any]:
+ extensions = dict(request.config.extensions or {})
+ extensions.pop("transport", None)
+ extensions.pop("prompt_caching", None)
+ extensions.pop("output", None)
+ config = LiveConfig(model=request.model, system=request.system, tools=request.tools, extensions=extensions or None)
+ payload = self._live_setup_payload(config)
+ output = (request.config.extensions or {}).get("output")
+ audio_native = self._is_audio_native_live_model(request.model)
+ if output == "audio" or audio_native:
+ setup = payload.setdefault("setup", {})
+ setup.setdefault("generationConfig", {})["responseModalities"] = ["AUDIO"]
+ if output != "audio":
+ setup["outputAudioTranscription"] = {}
+ has_media = any(isinstance(p, (AudioPart, VideoPart)) for m in request.messages for p in m.parts)
+ if has_media:
+ setup.setdefault("realtimeInputConfig", {}).setdefault("automaticActivityDetection", {})["disabled"] = True
+ elif output == "image":
+ payload.setdefault("setup", {}).setdefault("generationConfig", {})["responseModalities"] = ["IMAGE"]
+ return payload
+
+ def _live_client_content_payload_from_request(self, request: Request) -> list[dict[str, Any]]:
+ if self._is_audio_native_live_model(request.model):
+ return self._build_realtime_input_payloads(request)
+ if len(request.messages) == 1 and request.messages[0].role == "user" and all(isinstance(p, TextPart) for p in request.messages[0].parts):
+ return [{"realtimeInput": {"text": parts_to_text(request.messages[0].parts)}}]
+ names = self._call_names(request.messages)
+ return [{"clientContent": {"turns": [self._message(m, names) for m in request.messages], "turnComplete": True}}]
+
+ def _build_realtime_input_payloads(self, request: Request) -> list[dict[str, Any]]:
+ text_payloads: list[dict[str, Any]] = []
+ media_payloads: list[dict[str, Any]] = []
+ content_parts: list[dict[str, Any]] = []
+ sent_audio_or_video = False
+ for msg in request.messages:
+ for part in msg.parts:
+ if isinstance(part, TextPart) and part.text:
+ text_payloads.append({"realtimeInput": {"text": part.text}})
+ elif isinstance(part, AudioPart):
+ if part.data is not None or part.path is not None:
+ mime = part.media_type or "audio/pcm"
+ raw = part.bytes
+ if "wav" in mime or "wave" in mime:
+ pcm, rate = self._wav_to_pcm(raw)
+ data = base64.b64encode(pcm).decode("ascii")
+ media_payloads.append({"realtimeInput": {"audio": {"mimeType": f"audio/pcm;rate={rate}", "data": data}}})
+ else:
+ data = part.data or base64.b64encode(raw).decode("ascii")
+ media_payloads.append({"realtimeInput": {"audio": {"mimeType": mime, "data": data}}})
+ sent_audio_or_video = True
+ elif isinstance(part, VideoPart):
+ if part.data is not None or part.path is not None:
+ data = part.data or base64.b64encode(part.path.read_bytes()).decode("ascii")
+ media_payloads.append({"realtimeInput": {"video": {"mimeType": part.media_type or "video/mp4", "data": data}}})
+ sent_audio_or_video = True
+ elif isinstance(part, (ImagePart, DocumentPart, BinaryPart)):
+ content_parts.append(self._part(part))
+ payloads: list[dict[str, Any]] = []
+ if content_parts:
+ payloads.append({"clientContent": {"turns": [{"role": "user", "parts": content_parts}], "turnComplete": False}})
+ payloads.extend(text_payloads + media_payloads)
+ if sent_audio_or_video:
+ payloads.insert(0, {"realtimeInput": {"activityStart": {}}})
+ payloads.append({"realtimeInput": {"activityEnd": {}}})
+ if not payloads:
+ payloads.append({"realtimeInput": {"text": ""}})
+ return payloads
+
+ def _decode_live_completion_stream_events(self, raw: str | bytes) -> tuple[list[StreamEvent], bool, Usage]:
+ try:
+ payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+ except Exception:
+ return [], False, Usage()
+ if not isinstance(payload, dict):
+ return [], False, Usage()
+ if "error" in payload:
+ err = payload["error"]
+ provider_code = str(err.get("status") or err.get("code") or "provider") if isinstance(err, dict) else "provider"
+ message = str(err.get("message") or "") if isinstance(err, dict) else ""
+ return [StreamErrorEvent(error=self._error_detail(provider_code, message))], False, Usage()
+ events: list[StreamEvent] = []
+ tool_call = payload.get("toolCall")
+ if isinstance(tool_call, dict):
+ for idx, fc in enumerate(tool_call.get("functionCalls") or []):
+ if isinstance(fc, dict):
+ events.append(StreamDeltaEvent(delta=ToolCallDelta(input=json.dumps(fc.get("args", {})), part_index=idx, id=str(fc.get("id") or f"fc_{idx}"), name=str(fc.get("name") or "tool"))))
+ server = payload.get("serverContent")
+ if not isinstance(server, dict):
+ return events, False, self._live_usage(payload, None)
+ model_turn = server.get("modelTurn", {})
+ if isinstance(model_turn, dict):
+ for idx, part in enumerate(model_turn.get("parts", []) or []):
+ if "text" in part:
+ events.append(StreamDeltaEvent(delta=TextDelta(text=str(part.get("text") or ""), part_index=idx)))
+ elif "functionCall" in part and isinstance(part["functionCall"], dict):
+ fc = part["functionCall"]
+ events.append(StreamDeltaEvent(delta=ToolCallDelta(input=json.dumps(fc.get("args", {})), part_index=idx, id=str(fc.get("id") or "fc_0"), name=str(fc.get("name") or "tool"))))
+ elif "inlineData" in part and isinstance(part["inlineData"], dict):
+ inline = part["inlineData"]
+ mime = str(inline.get("mimeType") or "")
+ data = str(inline.get("data") or "")
+ if mime.startswith("audio/"):
+ events.append(StreamDeltaEvent(delta=AudioDelta(data=data, part_index=idx, media_type=mime)))
+ elif mime.startswith("image/"):
+ events.append(StreamDeltaEvent(delta=ImageDelta(data=data, part_index=idx, media_type=mime)))
+ out_tx = server.get("outputTranscription")
+ if isinstance(out_tx, dict) and out_tx.get("text"):
+ events.append(StreamDeltaEvent(delta=TextDelta(text=str(out_tx["text"]))))
+ return events, bool(server.get("turnComplete")), self._live_usage(payload, server)
+
+ # ─── Live sessions ──────────────────────────────────────────────
+
+ def live(self, config: LiveConfig):
+ self._require("live")
+ ws = self._live_connect(self._live_url())
+ for frame in self._live_setup_frames(config):
+ ws.send(json.dumps(frame))
+ self._wait_for_setup_complete(ws)
+ return WebSocketLiveSession(
+ ws=ws,
+ encode_event=self._live_encoder(config),
+ decode_event=self._decode_live_server_event,
+ )
+
+ def _live_connect(self, url: str):
+ connect = require_websocket_sync_connect()
+ return connect(url)
+
+ # Pure pieces shared by the sync session, the native async twin, and
+ # the vet shim's replay_live op (uniform hook: _live_setup_frames).
+
+ def _live_setup_frames(self, config: LiveConfig) -> list[dict[str, Any]]:
+ return [self._live_setup_frame(config)]
+
+ def _live_setup_frame(self, config: LiveConfig) -> dict[str, Any]:
+ payload = self._live_setup_payload(config)
+ if self._is_audio_native_live_model(config.model):
+ payload.setdefault("setup", {})["outputAudioTranscription"] = {}
+ return payload
+
+ def _live_encoder(self, config: LiveConfig):
+ audio_native = self._is_audio_native_live_model(config.model)
+
+ def encode_event(event: LiveClientEvent) -> list[dict[str, Any]]:
+ if audio_native and isinstance(event, LiveClientTextEvent):
+ return [{"realtimeInput": {"text": event.text}}]
+ return self._encode_live_client_event(event)
+
+ return encode_event
+
+ def _live_setup_status(self, raw: str | bytes) -> bool:
+ """True = setupComplete, False = keep waiting; raises typed on error."""
+ try:
+ payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+ except Exception:
+ return False
+ if isinstance(payload, dict) and "setupComplete" in payload:
+ return True
+ if isinstance(payload, dict) and "error" in payload:
+ err = payload["error"]
+ msg = err.get("message", "") if isinstance(err, dict) else str(err)
+ provider_code = str(err.get("status") or "live_setup") if isinstance(err, dict) else "live_setup"
+ raise self._provider_error(
+ InvalidRequestError,
+ f"Live setup failed: {msg}",
+ provider_code=provider_code,
+ )
+ return False
+
+ def _wait_for_setup_complete(self, ws: Any) -> None:
+ while not self._live_setup_status(ws.recv()):
+ pass
+
+ def _live_url(self) -> str:
+ parsed = urllib.parse.urlparse(self.base_url)
+ scheme = "wss" if parsed.scheme == "https" else "ws"
+ path = "/ws/google.ai.generativelanguage.v1beta.GenerativeService.BidiGenerateContent"
+ query = urllib.parse.urlencode({"key": resolve_credential(self.api_key)})
+ return urllib.parse.urlunparse((scheme, parsed.netloc, path, "", query, ""))
+
+ def _live_setup_payload(self, config: LiveConfig) -> dict[str, Any]:
+ setup: dict[str, Any] = {"model": self._model_path(config.model)}
+ if config.system:
+ setup["systemInstruction"] = {"parts": [{"text": config.system if isinstance(config.system, str) else parts_to_text(config.system)}]}
+ function_tools = [
+ {"name": t.name, "description": t.description, "parameters": t.parameters}
+ for t in config.tools
+ if isinstance(t, FunctionTool)
+ ]
+ if function_tools:
+ setup["tools"] = [{"functionDeclarations": function_tools}]
+ generation_config: dict[str, Any] = {}
+ if config.output_format is not None:
+ generation_config["responseModalities"] = ["AUDIO"]
+ elif self._is_audio_native_live_model(config.model):
+ generation_config["responseModalities"] = ["AUDIO"]
+ if config.voice:
+ generation_config.setdefault("speechConfig", {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": config.voice}}})
+ if generation_config:
+ setup["generationConfig"] = generation_config
+ if config.extensions:
+ setup.update(config.extensions)
+ return {"setup": setup}
+
+ def _live_usage(self, payload: dict[str, Any], server: dict[str, Any] | None) -> Usage:
+ usage_payload = payload.get("usageMetadata")
+ if not isinstance(usage_payload, dict) and isinstance(server, dict):
+ usage_payload = server.get("usageMetadata")
+ return _gemini_usage(usage_payload, output_keys=("responseTokenCount", "candidatesTokenCount"))
+
+ def _encode_live_client_event(self, event: LiveClientEvent) -> list[dict[str, Any]]:
+ if isinstance(event, LiveClientTurnEvent):
+ return [{"clientContent": {"turns": [{"role": "user", "parts": [self._part(part) for part in event.parts]}], "turnComplete": event.turn_complete}}]
+ if isinstance(event, LiveClientAudioEvent):
+ return [{"realtimeInput": {"audio": {"mimeType": event.media_type, "data": event.data}}}]
+ if isinstance(event, LiveClientImageEvent):
+ return [{"realtimeInput": {"video": {"mimeType": event.media_type, "data": event.data}}}]
+ if isinstance(event, LiveClientInterruptEvent):
+ return [{"clientContent": {"turnComplete": True}}]
+ if isinstance(event, LiveClientEndAudioEvent):
+ return [{"realtimeInput": {"audioStreamEnd": True}}]
+ if isinstance(event, LiveClientTextEvent):
+ return [{"clientContent": {"turns": [{"role": "user", "parts": [{"text": event.text}]}], "turnComplete": True}}]
+ if isinstance(event, LiveClientToolResultEvent):
+ response_parts = [{"text": parts_to_text(event.content)}]
+ return [{"toolResponse": {"functionResponses": [{"id": event.id, "response": {"output": response_parts}}]}}]
+ return []
+
+ def _decode_live_server_event(self, raw: str | bytes):
+ try:
+ payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+ except Exception:
+ return []
+ if not isinstance(payload, dict):
+ return []
+ if "error" in payload:
+ err = payload.get("error")
+ provider_code = str(err.get("status") or err.get("code") or "provider") if isinstance(err, dict) else "provider"
+ message = str(err.get("message") or "") if isinstance(err, dict) else ""
+ return [LiveServerErrorEvent(error=self._error_detail(provider_code, message))]
+ events: list[Any] = []
+ tool_call = payload.get("toolCall")
+ if isinstance(tool_call, dict):
+ for fc in tool_call.get("functionCalls") or []:
+ if isinstance(fc, dict):
+ events.append(LiveServerToolCallEvent(id=str(fc.get("id") or "fc_0"), name=str(fc.get("name") or "tool"), input=fc.get("args") if isinstance(fc.get("args"), dict) else {}))
+ server = payload.get("serverContent")
+ if not isinstance(server, dict):
+ return events
+ model_turn = server.get("modelTurn", {})
+ if isinstance(model_turn, dict):
+ for part in model_turn.get("parts", []) or []:
+ if "text" in part:
+ events.append(LiveServerTextEvent(text=str(part.get("text") or "")))
+ elif "inlineData" in part and isinstance(part["inlineData"], dict):
+ inline = part["inlineData"]
+ mime = str(inline.get("mimeType") or "")
+ if mime.startswith("audio/"):
+ events.append(LiveServerAudioEvent(data=str(inline.get("data") or ""), media_type=mime or None))
+ elif "functionCall" in part and isinstance(part["functionCall"], dict):
+ fc = part["functionCall"]
+ events.append(LiveServerToolCallEvent(id=str(fc.get("id") or "fc_0"), name=str(fc.get("name") or "tool"), input=fc.get("args") if isinstance(fc.get("args"), dict) else {}))
+ out_tx = server.get("outputTranscription")
+ if isinstance(out_tx, dict) and out_tx.get("text"):
+ events.append(LiveServerTextEvent(text=str(out_tx["text"])))
+ has_usage = isinstance(payload.get("usageMetadata"), dict) or isinstance(server.get("usageMetadata"), dict)
+ if has_usage and not server.get("turnComplete"):
+ # Usage reported on a frame that does not end the turn (an
+ # interrupted or tool-call frame) rides a usage event; the
+ # pinned Gemini transcripts report usage only on turnComplete,
+ # so this is the rule, not a receipt.
+ events.append(LiveServerUsageEvent(usage=self._live_usage(payload, server)))
+ if server.get("interrupted"):
+ events.append(LiveServerInterruptedEvent())
+ if server.get("turnComplete"):
+ events.append(LiveServerTurnEndEvent(usage=self._live_usage(payload, server)))
+ return events
+
+ # ─── Other endpoints ────────────────────────────────────────────
+
+ # ─── Live model listing (provisional endpoint) ──────────────────────
+
+ def _models_request(self):
+ # pageSize=1000 covers the catalog in one page (53 models observed
+ # live 2026-08-31, no nextPageToken).
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/models",
+ params={"pageSize": 1000},
+ headers=self._auth_headers(),
+ read_timeout=30.0,
+ )
+
+ def _models_from_body(self, body: str):
+ data = json.loads(body)
+ entries = data.get("models") if isinstance(data, dict) else None
+
+ def id_of(entry: dict) -> str | None:
+ # The wire name is "models/<id>"; the usable Request.model string
+ # is the bare id (build_request re-prefixes via _model_path).
+ name = entry.get("name")
+ if isinstance(name, str) and name.startswith("models/"):
+ return name[len("models/"):]
+ return name if isinstance(name, str) else None
+
+ return model_infos_from_entries(
+ entries,
+ provider=self.provider,
+ api_family="gemini_generate_content",
+ id_of=id_of,
+ )
+
+ # ─── File hooks (Files API) ─────────────────────────────────
+ #
+ # Wire shapes verified live 2026-08-31 (curl-fixtures/files-2026-08-31/):
+ # multipart/related upload (metadata display_name + media) so the
+ # filename survives the round trip; upload wraps the object in
+ # {"file": {...}} while get/list return it bare; list paginates with
+ # pageToken; download (`:download?alt=media`) EXISTS but the server
+ # refuses non-generated files (400, forwarded typed).
+ #
+ # FileInfo.id is the file's `uri` VERBATIM — Gemini model requests
+ # address files by URI (the frozen chat mapping places Part.file_id
+ # into fileData.fileUri), while the REST resource lives at the
+ # `files/<id>` name; _file_resource() derives one from the other.
+
+ @staticmethod
+ def _file_resource(file_id: str) -> str:
+ """`files/<id>` resource path from a canonical id (URI or name)."""
+ if "://" in file_id:
+ tail = file_id.rstrip("/").rsplit("/files/", 1)
+ if len(tail) == 2 and tail[1]:
+ return f"files/{tail[1]}"
+ if file_id.startswith("files/"):
+ return file_id
+ return f"files/{file_id}"
+
+ def _file_upload_request(self, request: FileUploadRequest) -> TransportRequest:
+ url = build_url(f"{self.upload_base_url.rstrip('/')}/files", request.extensions)
+ content_type, body = multipart_related_body(
+ metadata={"file": {"display_name": request.filename}},
+ media_type=request.media_type,
+ data=request.bytes,
+ )
+ return self._emit(
+ method="POST",
+ url=url,
+ headers=list(self._auth_headers({
+ "X-Goog-Upload-Protocol": "multipart",
+ "Content-Type": content_type,
+ }).items()),
+ body=body,
+ read_timeout=300.0,
+ )
+
+ def _file_info_from_body(self, body: str) -> FileInfo:
+ data = json.loads(body)
+ if isinstance(data.get("file"), dict): # upload wraps; get/list do not
+ return self._file_info(data["file"])
+ return self._file_info(data)
+
+ def _file_info(self, data: dict[str, Any]) -> FileInfo:
+ uri = data.get("uri")
+ name = data.get("name")
+ file_id = uri if isinstance(uri, str) and uri else name
+ if not isinstance(file_id, str) or not file_id:
+ raise ProviderError("gemini: file object carries no uri or name", provider=self.provider)
+ state = str(data.get("state") or "")
+ if state.endswith("PROCESSING"):
+ readiness = "pending"
+ elif state.endswith("FAILED"):
+ readiness = "failed"
+ else: # ACTIVE, absent, or unknown
+ readiness = "ready"
+ if isinstance(data.get("downloadUri"), str) and data.get("downloadUri"):
+ downloadable: bool | None = True
+ elif data.get("source") == "UPLOADED":
+ downloadable = False # the server's stated rule: only GENERATED files download
+ else:
+ downloadable = None
+ display_name = data.get("displayName")
+ mime = data.get("mimeType")
+ size_raw = data.get("sizeBytes") # the wire carries int64 as a string
+ try:
+ size_bytes = int(size_raw) if isinstance(size_raw, (str, int)) and not isinstance(size_raw, bool) else None
+ except ValueError:
+ size_bytes = None
+ return FileInfo(
+ id=file_id,
+ filename=display_name if isinstance(display_name, str) and display_name else None,
+ media_type=mime if isinstance(mime, str) and mime else None,
+ size_bytes=size_bytes,
+ created_at=iso_utc(data.get("createTime")),
+ expires_at=iso_utc(data.get("expirationTime")),
+ readiness=readiness,
+ downloadable=downloadable,
+ provider_data=data,
+ )
+
+ def _file_get_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/{path_id(self._file_resource(file_id), resource_name=True)}",
+ headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _file_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ params: dict[str, Any] = {"pageSize": limit}
+ if cursor is not None:
+ params["pageToken"] = cursor
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files",
+ params=params, headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _file_page_from_list_body(self, body: str) -> FilePage:
+ data = json.loads(body)
+ entries = data.get("files") if isinstance(data.get("files"), list) else []
+ items = tuple(self._file_info(entry) for entry in entries if isinstance(entry, dict))
+ cursor = data.get("nextPageToken")
+ return FilePage(items=items, next_cursor=cursor if isinstance(cursor, str) and cursor else None)
+
+ def _file_delete_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="DELETE", url=f"{self.base_url.rstrip('/')}/{path_id(self._file_resource(file_id), resource_name=True)}",
+ headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _file_download_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/{path_id(self._file_resource(file_id), resource_name=True)}:download?alt=media",
+ headers=self._auth_headers(), read_timeout=300.0,
+ )
+
+ # ─── Cache resource hooks (cachedContents; the stored tier of MAP-6) ──
+ #
+ # Wire shapes verified live 2026-09-01 (research/caching/receipts/
+ # gemini__explicit-resource__*): POST /cachedContents {model, contents,
+ # systemInstruction?, tools?, toolConfig?, ttl "Ns", displayName?} ->
+ # the object with name, model, createTime, expireTime,
+ # usageMetadata.totalTokenCount; GET/PATCH(ttl)/DELETE by name; list
+ # -> {cachedContents: [...], nextPageToken}. The object pins its
+ # model and owns system/tools: a request may not repeat them.
+ # CacheInfo.id is the resource name verbatim ("cachedContents/<id>").
+
+ @staticmethod
+ def _cache_resource(cache_id: str) -> str:
+ return cache_id if cache_id.startswith("cachedContents/") else f"cachedContents/{cache_id}"
+
+ def _cache_create_request(self, prefix: Request, ttl_seconds: int | None, label: str | None) -> TransportRequest:
+ body: dict[str, Any] = {
+ "model": self._model_path(prefix.model),
+ "contents": [self._message(m, self._call_names(prefix.messages)) for m in prefix.messages],
+ }
+ if prefix.system:
+ text = prefix.system if isinstance(prefix.system, str) else parts_to_text(prefix.system)
+ body["systemInstruction"] = {"parts": [{"text": text}]}
+ if prefix.tools:
+ declarations = [
+ {"name": t.name, "description": t.description, "parameters": t.parameters}
+ for t in prefix.tools if isinstance(t, FunctionTool)
+ ]
+ tools_wire: list[dict[str, Any]] = []
+ if declarations:
+ tools_wire.append({"functionDeclarations": declarations})
+ tools_wire += [_builtin_to_gemini(t) for t in prefix.tools if isinstance(t, BuiltinTool)]
+ body["tools"] = tools_wire
+ if ttl_seconds is not None:
+ body["ttl"] = f"{ttl_seconds}s"
+ if label is not None:
+ body["displayName"] = label
+ return self._emit(
+ method="POST", url=f"{self.base_url.rstrip('/')}/cachedContents",
+ headers=self._auth_headers({"Content-Type": "application/json"}), payload=body, read_timeout=120.0,
+ )
+
+ def _cache_info_from_body(self, body: str) -> CacheInfo:
+ return self._cache_info(json.loads(body))
+
+ def _cache_info(self, data: dict[str, Any]) -> CacheInfo:
+ name = data.get("name")
+ if not isinstance(name, str) or not name:
+ raise ProviderError("gemini: cache object carries no name", provider=self.provider)
+ model = str(data.get("model") or "")
+ model = model[len("models/"):] if model.startswith("models/") else model
+ if not model:
+ raise ProviderError("gemini: cache object carries no model", provider=self.provider)
+ usage = data.get("usageMetadata") if isinstance(data.get("usageMetadata"), dict) else {}
+ tokens = usage.get("totalTokenCount")
+ label = data.get("displayName")
+ return CacheInfo(
+ id=name,
+ model=model,
+ tokens=int(tokens) if isinstance(tokens, (int, str)) and str(tokens).isdigit() else None,
+ created_at=iso_utc(data.get("createTime")),
+ expires_at=iso_utc(data.get("expireTime")),
+ label=label if isinstance(label, str) and label else None,
+ provider_data=data,
+ )
+
+ def _cache_get_request(self, cache_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/{path_id(self._cache_resource(cache_id), resource_name=True)}",
+ headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _cache_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ params: dict[str, Any] = {"pageSize": int(limit)}
+ if cursor is not None:
+ params["pageToken"] = cursor
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/cachedContents",
+ params=params, headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _cache_page_from_list_body(self, body: str) -> CachePage:
+ data = json.loads(body)
+ entries = data.get("cachedContents") if isinstance(data.get("cachedContents"), list) else []
+ items = tuple(self._cache_info(e) for e in entries if isinstance(e, dict))
+ cursor = data.get("nextPageToken")
+ return CachePage(items=items, next_cursor=cursor if isinstance(cursor, str) and cursor else None)
+
+ def _cache_delete_request(self, cache_id: str) -> TransportRequest:
+ return self._emit(
+ method="DELETE", url=f"{self.base_url.rstrip('/')}/{path_id(self._cache_resource(cache_id), resource_name=True)}",
+ headers=self._auth_headers(), read_timeout=60.0,
+ )
+
+ def _cache_update_request(self, cache_id: str, ttl_seconds: int) -> TransportRequest:
+ return self._emit(
+ method="PATCH", url=f"{self.base_url.rstrip('/')}/{path_id(self._cache_resource(cache_id), resource_name=True)}",
+ headers=self._auth_headers({"Content-Type": "application/json"}),
+ payload={"ttl": f"{ttl_seconds}s"}, read_timeout=60.0,
+ )
+
+ # ─── Batch hooks (Batch Mode, inline requests) ───────────────────
+ #
+ # Wire shapes verified live 2026-08-31: submit → POST
+ # {model}:batchGenerateContent, job id = operation "name"
+ # ("batches/<id>"), inline results under
+ # response.inlinedResponses.inlinedResponses[] with metadata.key
+ # correlation, list → GET /batches?pageSize=N → {"operations": [...]}.
+
+ def _batch_submit_request(self, request: BatchRequest, upload_body: dict[str, Any] | None) -> TransportRequest:
+ model = request.model or request.requests[0].model
+ batch: dict[str, Any] = {
+ "inputConfig": {
+ "requests": {
+ "requests": [
+ {"request": self._payload(nested), "metadata": {"key": str(i)}}
+ for i, nested in enumerate(request.requests)
+ ]
+ }
+ },
+ }
+ if request.label is not None:
+ batch["displayName"] = request.label
+ payload = {"batch": batch, **(request.extensions or {})}
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/{self._model_path(model)}:batchGenerateContent",
+ headers=self._auth_headers({"Content-Type": "application/json"}),
+ payload=payload,
+ read_timeout=120.0,
+ )
+
+ def _batch_job_from_body(self, body: str) -> BatchJobInfo:
+ return self._batch_job_info(json.loads(body))
+
+ def _batch_job_info(self, data: dict[str, Any]) -> BatchJobInfo:
+ name = data.get("name")
+ if not isinstance(name, str) or not name:
+ raise ProviderError("gemini: batch operation carries no name", provider=self.provider)
+ metadata = data.get("metadata") if isinstance(data.get("metadata"), dict) else {}
+ label = metadata.get("displayName")
+ return BatchJobInfo(
+ id=name,
+ status=_gemini_batch_status(data),
+ label=label if isinstance(label, str) and label else None,
+ created_at=iso_utc(metadata.get("createTime")),
+ provider_data=data,
+ )
+
+ def _batch_status_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/{path_id(batch_id, resource_name=True)}",
+ headers=self._auth_headers(),
+ read_timeout=60.0,
+ )
+
+ def _batch_cancel_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/{path_id(batch_id, resource_name=True)}:cancel",
+ headers=self._auth_headers({"Content-Type": "application/json"}),
+ payload={},
+ read_timeout=60.0,
+ )
+
+ def _batch_result_fetches(self, status_body: dict[str, Any]) -> tuple[TransportRequest, ...]:
+ # Inline submissions carry their results in the operation body.
+ return ()
+
+ def _batch_entries(self, status_body: dict[str, Any], fetched: tuple[str, ...]) -> tuple[BatchEntry, ...]:
+ response_obj = status_body.get("response") if isinstance(status_body.get("response"), dict) else {}
+ inlined = response_obj.get("inlinedResponses")
+ if isinstance(inlined, dict):
+ inlined = inlined.get("inlinedResponses")
+ entries: list[BatchEntry] = []
+ for position, item in enumerate(inlined or []):
+ if not isinstance(item, dict):
+ continue
+ metadata = item.get("metadata") if isinstance(item.get("metadata"), dict) else {}
+ try:
+ index = int(str(metadata.get("key")))
+ except (TypeError, ValueError):
+ index = position
+ if isinstance(item.get("response"), dict):
+ body_obj = item["response"]
+ response = self.parse_response(
+ batch_entry_request(body_obj.get("modelVersion")), batch_entry_http(body_obj)
+ )
+ entries.append(BatchEntry(index=index, outcome="succeeded", response=response))
+ else:
+ # Per-entry failures arrive as a google.rpc.Status, not the
+ # HTTP error envelope; map directly.
+ err = item.get("error") if isinstance(item.get("error"), dict) else {}
+ provider_code = err.get("status") or err.get("code")
+ entries.append(BatchEntry(
+ index=index,
+ outcome="errored",
+ error=ErrorDetail(
+ code="provider",
+ message=str(err.get("message") or "batch entry errored"),
+ provider_code=str(provider_code) if provider_code is not None else None,
+ ),
+ ))
+ return tuple(sorted(entries, key=lambda e: e.index))
+
+ def _batch_list_request(self, limit: int) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/batches",
+ params={"pageSize": int(limit)},
+ headers=self._auth_headers(),
+ read_timeout=60.0,
+ )
+
+ def _batch_jobs_from_list_body(self, body: str) -> tuple[BatchJobInfo, ...]:
+ data = json.loads(body)
+ items = data.get("operations") if isinstance(data, dict) else None
+ return tuple(self._batch_job_info(item) for item in (items or []) if isinstance(item, dict))
+
+ # ─── Video generation (Veo; captured live 2026-09-01) ───────────────
+ #
+ # predictLongRunning returns an operation name (the ticket); polling
+ # the operation yields done + response.generateVideoResponse with a
+ # file URI that is KEY-BOUND (403 without the header, verified), so
+ # the result step fetches the bytes — a URL the user cannot open is
+ # not an honest VideoPart. Listing is per model.
+
+ def _video_submit_request(self, request: VideoGenerationRequest) -> TransportRequest:
+ if request.images:
+ # Veo's image input (instances[].image) is documented but not yet
+ # live-receipted; the generations-ignores-input trap on xAI made
+ # unverified media-input mappings a named hazard. Raise for now.
+ raise UnsupportedFeatureError(
+ "gemini: video input images are not mapped yet; "
+ "use extensions until the mapping is live-receipted",
+ provider=self.provider,
+ )
+ instance: dict[str, Any] = {"prompt": request.prompt}
+ parameters: dict[str, Any] = {}
+ if request.seconds is not None:
+ parameters["durationSeconds"] = request.seconds
+ payload: dict[str, Any] = {"instances": [instance], **(request.extensions or {})}
+ if parameters:
+ payload.setdefault("parameters", parameters)
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/{self._model_path(request.model)}:predictLongRunning",
+ headers=self._auth_headers({"Content-Type": "application/json"}),
+ payload=payload,
+ read_timeout=120.0,
+ )
+
+ def _video_job_from_body(self, body: str, video_id: "str | None" = None) -> VideoJobInfo:
+ return self._video_job_info(json.loads(body))
+
+ def _video_job_info(self, data: dict[str, Any]) -> VideoJobInfo:
+ name = data.get("name")
+ if not isinstance(name, str) or not name:
+ raise ProviderError("gemini: video operation carries no name", provider=self.provider)
+ if data.get("done") is True:
+ status = "failed" if isinstance(data.get("error"), dict) else "completed"
+ else:
+ # Operations expose no queued/running distinction before done.
+ status = "running"
+ return VideoJobInfo(id=name, status=status, provider_data=data)
+
+ def _video_status_request(self, video_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/{path_id(video_id, resource_name=True)}",
+ headers=self._auth_headers({}),
+ read_timeout=60.0,
+ )
+
+ def _video_result_uri(self, status_body: dict[str, Any]) -> str:
+ response = status_body.get("response") if isinstance(status_body.get("response"), dict) else {}
+ gvr = response.get("generateVideoResponse") if isinstance(response.get("generateVideoResponse"), dict) else {}
+ samples = gvr.get("generatedSamples")
+ if isinstance(samples, list) and samples:
+ video = samples[0].get("video") if isinstance(samples[0], dict) else None
+ uri = video.get("uri") if isinstance(video, dict) else None
+ if isinstance(uri, str) and uri:
+ return uri
+ raise ProviderError("gemini: terminal video operation carries no video uri", provider=self.provider)
+
+ def _video_result_fetch(self, status_body: dict[str, Any]) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=self._video_result_uri(status_body),
+ headers=self._auth_headers({}),
+ read_timeout=600.0,
+ )
+
+ def _video_part(self, status_body: dict[str, Any], fetched: "HttpResponse | None") -> VideoPart:
+ if fetched is None:
+ raise ProviderError("gemini: video content fetch is required", provider=self.provider)
+ content_type = (fetched.header("content-type") or "").split(";", 1)[0].strip()
+ if not content_type:
+ raise ProviderError("gemini: video download carries no content-type", provider=self.provider)
+ return VideoPart(media_type=content_type, data=base64.b64encode(fetched.body).decode("ascii"))
+
+ def _video_list_request(self, limit: int, model: str | None) -> TransportRequest:
+ if not model:
+ raise UnsupportedFeatureError(
+ "gemini: video jobs list per model — pass model= (operations live under models/<model>/operations)",
+ provider=self.provider,
+ )
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/{self._model_path(model)}/operations",
+ params={"pageSize": int(limit)},
+ headers=self._auth_headers({}),
+ read_timeout=60.0,
+ )
+
+ def _video_jobs_from_list_body(self, body: str) -> tuple[VideoJobInfo, ...]:
+ data = json.loads(body)
+ ops = data.get("operations") if isinstance(data, dict) else None
+ return tuple(self._video_job_info(op) for op in (ops or []) if isinstance(op, dict))
+
+ # ─── Media generation (captured live 2026-09-01) ────────────────────
+ #
+ # Gemini has no dedicated generation endpoints: image models and TTS
+ # models answer the ordinary generateContent call. The hooks compose
+ # the frozen chat mapping (build_request / parse_response), so the
+ # shared sync drivers and the async mirrors both work unchanged.
+ # Input images (edits) are ordinary parts in the same call — verified
+ # honored by pixel check. Image responses routinely carry narration
+ # text next to the image; it lands in ImageGenerationResponse.text.
+
+ def _image_generation_lm_request(self, request: ImageGenerationRequest) -> Request:
+ extensions = dict(request.extensions or {})
+ if request.size is not None:
+ generation_config = dict(extensions.get("generationConfig") or {})
+ image_config = dict(generation_config.get("imageConfig") or {})
+ image_config.setdefault("aspectRatio", request.size)
+ generation_config["imageConfig"] = image_config
+ extensions["generationConfig"] = generation_config
+ parts = (TextPart(text=request.prompt), *request.images)
+ return Request(
+ model=request.model,
+ messages=(Message(role="user", parts=parts),),
+ config=Config(extensions=extensions) if extensions else Config(),
+ )
+
+ def _image_generate_request(self, request: ImageGenerationRequest) -> TransportRequest:
+ return self.build_request(self._image_generation_lm_request(request), stream=False)
+
+ def _image_generation_from_response(self, request: ImageGenerationRequest, resp: HttpResponse) -> ImageGenerationResponse:
+ chat = self.parse_response(self._image_generation_lm_request(request), resp)
+ images = tuple(part for part in chat.message.parts if isinstance(part, ImagePart))
+ if not images:
+ raise ProviderError("gemini: model returned no image parts", provider=self.provider)
+ texts = [part.text for part in chat.message.parts if isinstance(part, TextPart) and part.text]
+ return ImageGenerationResponse(
+ images=images,
+ text="".join(texts) or None,
+ id=chat.id,
+ model=chat.model,
+ usage=chat.usage,
+ provider_data=chat.provider_data,
+ )
+
+ def _speech_generation_lm_request(self, request: SpeechGenerationRequest) -> Request:
+ if request.format is not None:
+ # No wire slot: Gemini TTS always answers PCM (captured
+ # audio/L16;codec=pcm;rate=24000). Raising beats dropping.
+ raise UnsupportedFeatureError(
+ "gemini: speech format cannot be chosen; the wire always returns PCM",
+ provider=self.provider,
+ )
+ generation_config: dict[str, Any] = {"responseModalities": ["AUDIO"]}
+ if request.voice is not None:
+ generation_config["speechConfig"] = {"voiceConfig": {"prebuiltVoiceConfig": {"voiceName": request.voice}}}
+ extensions = {"generationConfig": generation_config, **(request.extensions or {})}
+ return Request(model=request.model, messages=(Message.user(request.prompt),), config=Config(extensions=extensions))
+
+ def _speech_generate_request(self, request: SpeechGenerationRequest) -> TransportRequest:
+ return self.build_request(self._speech_generation_lm_request(request), stream=False)
+
+ def _speech_generation_from_response(self, request: SpeechGenerationRequest, resp: HttpResponse) -> SpeechGenerationResponse:
+ chat = self.parse_response(self._speech_generation_lm_request(request), resp)
+ audio = chat.message.first(AudioPart)
+ if audio is None:
+ raise ProviderError("gemini: model returned no audio part", provider=self.provider)
+ return SpeechGenerationResponse(audio=audio, id=chat.id, model=chat.model, usage=chat.usage, provider_data=chat.provider_data)
diff --git a/dspy/_vendor/lm15/providers/openai.py b/dspy/_vendor/lm15/providers/openai.py
new file mode 100644
index 000000000..80ba427be
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/openai.py
@@ -0,0 +1,2054 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+import base64
+import json
+import os
+import re
+import urllib.parse
+from dataclasses import dataclass, field
+from typing import Any, Callable, ClassVar, Iterator, Mapping
+
+from ..errors import (
+ AuthError,
+ BillingError,
+ ContextLengthError,
+ InvalidRequestError,
+ NotConfiguredError,
+ ProviderError,
+ RateLimitError,
+ ServerError,
+ TimeoutError,
+ UnsupportedFeatureError,
+ UnsupportedModelError,
+ canonical_error_code,
+ map_http_error,
+)
+from ..access import OPENAI_API, auth_header
+from ..auth import extract_chatgpt_account_id
+from ..compat import OPENAI_RESPONSES_PRESET_BASE_URLS, OpenAIResponsesCompat, _preset_key
+from ..features import ProviderManifest
+from ..result import materialize_response
+from ..live import WebSocketLiveSession, require_websocket_sync_connect
+from ..profiles import ProviderProfile, ResolvedOpenAIResponsesCompat, resolve_openai_responses_compat
+from ..sse import SSEEvent
+from ..transports import TransportRequest
+from ..types import (
+ continuation_data,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ VideoPart,
+ AudioDelta,
+ AudioFormat,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ AudioPart,
+ BatchEntry,
+ BatchJobInfo,
+ BatchRequest,
+ BuiltinTool,
+ CitationDelta,
+ ContinuationDelta,
+ ContinuationState,
+ CitationPart,
+ ErrorDetail,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ FunctionTool,
+ ImageDelta,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ ImagePart,
+ LiveClientAudioEvent,
+ LiveClientEndAudioEvent,
+ LiveClientEvent,
+ LiveClientImageEvent,
+ LiveClientInterruptEvent,
+ LiveClientTextEvent,
+ LiveClientToolResultEvent,
+ LiveClientTurnEvent,
+ LiveConfig,
+ LiveServerAudioEvent,
+ LiveServerErrorEvent,
+ LiveServerInterruptedEvent,
+ LiveServerTextEvent,
+ LiveServerToolCallDeltaEvent,
+ LiveServerToolCallEvent,
+ LiveServerTurnEndEvent,
+ LiveServerUsageEvent,
+ Message,
+ RefusalPart,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ StreamEvent,
+ StreamStartEvent,
+ TextDelta,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ ToolCallDelta,
+ ToolCallPart,
+ ToolResultPart,
+ Usage,
+)
+from .base import (
+ BaseProviderLM,
+ Credential,
+ HttpResponse,
+ SyncTransport,
+ batch_entry_http,
+ batch_entry_request,
+ default_transport,
+ resolve_credential_value,
+)
+from .common import (
+ tool_result_error_text,
+ tool_result_output_openai,
+ iso_utc,
+ model_infos_from_entries,
+ multipart_form_body,
+ openai_file_readiness,
+ openai_token_logprobs,
+ parse_json_object,
+ part_to_openai_input,
+ path_id,
+ unnamed_tool_call_error,
+ parts_to_text,
+)
+
+# Canonical builtin tool name → OpenAI Responses API tool type
+_OPENAI_BUILTIN_MAP: dict[str, str] = {
+ "web_search": "web_search_preview",
+ "code_execution": "code_interpreter",
+ "file_search": "file_search",
+ "computer_use": "computer_use_preview",
+}
+
+# Per compat `builtin_tools` value: canonical name → server tool type. A
+# name absent from the table goes out verbatim and the server answers for
+# itself (Meta and Moonshot: HTTP 400, live 2026-09-03 — loud, so no
+# pre-wire refusal). "verbatim" is the empty table: the canonical name is
+# the wire type (`web_search` on both servers' schemas).
+_BUILTIN_MAPS: dict[str, dict[str, str]] = {
+ "openai": _OPENAI_BUILTIN_MAP,
+ "verbatim": {},
+}
+
+
+def _builtin_type(tool: BuiltinTool, compat: "ResolvedOpenAIResponsesCompat") -> str:
+ return _BUILTIN_MAPS[compat.builtin_tools].get(tool.name, tool.name)
+
+OPENAI_PROVIDER_EXECUTED_ITEMS = {
+ "web_search_call",
+ "file_search_call",
+ "code_interpreter_call",
+ "computer_call",
+ "computer_use_call",
+}
+
+
+def _attach_unmapped(provider_data: dict[str, Any], unmapped: list[dict[str, str]]) -> dict[str, Any]:
+ if not unmapped:
+ return provider_data
+ out = dict(provider_data)
+ out["_lm15_unmapped"] = unmapped
+ return out
+
+
+_GPT_VERSION_RE = re.compile(r"^gpt-(\d+)\.(\d+)")
+
+
+def openai_model_has_cache_options(model: str) -> bool:
+ """True for the GPT-5.6-and-later model class (MAP-6, mode="off").
+
+ The off switch for cache WRITES is ``prompt_cache_options`` and only
+ that class accepts it (older models reject it with HTTP 400, and their
+ writes are free anyway). Deciding client-side needs a model check —
+ a table that rots. Stated trade-off: a future family whose name does
+ not match ``gpt-<major>.<minor>`` keeps the provider's implicit writes
+ on ``mode="off"``; ``extensions={"prompt_cache_options": ...}`` is the
+ override.
+ """
+ m = _GPT_VERSION_RE.match(model.lower())
+ return bool(m) and (int(m.group(1)), int(m.group(2))) >= (5, 6)
+
+
+def _cache_breakpoint_index(request: Request, cache_control: str) -> int | None:
+ """Message index that carries the explicit prompt-cache breakpoint.
+
+ ``CacheConfig.prefix_until_index`` marks the end of the reusable prefix.
+ Both OpenAI dialects place ``prompt_cache_breakpoint`` on a text
+ content block (gpt-5.6+); the mapping is active only when the compat
+ policy names OpenAI's cache control (compat servers that declare
+ ``cache_control="none"`` get nothing, as for prompt_cache_key). The
+ index is clamped to the last message, the Anthropic adapter's
+ precedent. ``prefix="history"`` sends nothing: OpenAI's implicit
+ trailing breakpoint already marks the latest message (MAP-6 A2).
+ ``prefix="stable"`` is handled by the system-message rendering, not
+ here.
+ """
+ cache_cfg = request.config.cache
+ if cache_cfg is None or cache_cfg.mode == "off" or cache_cfg.prefix_until_index is None:
+ return None
+ if cache_control != "openai":
+ return None
+ return min(cache_cfg.prefix_until_index, len(request.messages) - 1)
+
+
+def _has_explicit_breakpoint(request: Request, cache_control: str) -> bool:
+ """True when this request places a prompt_cache_breakpoint (prefix="stable"
+ or prefix_until_index) — the cases where explicit mode belongs with it."""
+ # prefix="stable" places its mark on the system prompt; with no system
+ # there is no mark, and explicit mode with no mark would cache nothing.
+ return _cache_breakpoint_index(request, cache_control) is not None or (
+ _cache_stable_prefix(request, cache_control) and bool(request.system)
+ )
+
+
+def _cache_stable_prefix(request: Request, cache_control: str) -> bool:
+ """``prefix="stable"``: mark the end of system + tools (MAP-6 A2)."""
+ cache_cfg = request.config.cache
+ return (
+ cache_cfg is not None and cache_cfg.mode != "off" and cache_cfg.prefix == "stable"
+ and cache_control == "openai"
+ )
+
+
+def _cache_common_payload(request: Request, payload: dict, cache_control: str, provider: str) -> None:
+ """Shared MAP-6 fields for both OpenAI dialects: off switch, key, retention.
+
+ ``cache_control="openai_implicit"`` forwards the key and the retention
+ hint and nothing else: no off switch (the server has none; MAP-6 A2
+ treats an explicit CacheConfig on an implicit-only server as accepted,
+ not an error) and no breakpoint mark (an undocumented field the server
+ swallows silently — Meta, live 2026-09-03).
+ """
+ cache_cfg = request.config.cache
+ if cache_cfg is None or cache_control not in ("openai", "openai_implicit"):
+ return
+ if cache_control == "openai_implicit":
+ if cache_cfg.mode != "off":
+ if cache_cfg.key:
+ payload["prompt_cache_key"] = cache_cfg.key
+ if cache_cfg.retention == "long":
+ payload["prompt_cache_retention"] = "24h"
+ if cache_cfg.resource is not None:
+ raise UnsupportedFeatureError(
+ f"{provider}: cache.resource is not supported — this provider has no stored-cache "
+ "tier; it caches every prompt prefix automatically",
+ provider=provider,
+ )
+ return
+ if cache_cfg.mode == "off":
+ # Option 2 (ratified 2026-09-01): the real off switch where the
+ # model class has one; nothing where writes are free anyway.
+ if openai_model_has_cache_options(request.model):
+ payload["prompt_cache_options"] = {"mode": "explicit"}
+ return
+ if cache_cfg.key:
+ payload["prompt_cache_key"] = cache_cfg.key
+ if cache_cfg.retention == "long":
+ # Every OpenAI model class takes prompt_cache_retention="24h". The
+ # gpt-5.6 class used to RAISE here on a doc line about
+ # prompt_cache_options.ttl (30m only) — a different field. Live
+ # 2026-09-02 (review probe 2): gpt-5.6-sol answers 200 and echoes
+ # prompt_cache_retention: "24h"; every pinned 5.6 body already
+ # echoes 24h as its default. Sending it is honest and harmless.
+ payload["prompt_cache_retention"] = "24h"
+ if openai_model_has_cache_options(request.model) and _has_explicit_breakpoint(request, cache_control):
+ # A placed breakpoint means "cache up to here". Without explicit
+ # mode the 5.6 class also writes the volatile suffix at 1.25x on
+ # every warm call (pinned: openai.prompt_cache_breakpoint wrote 18
+ # after reading 3066). With mode=explicit the warm call writes 0
+ # (review probe 3, 2026-09-02). The mark and the mode go together.
+ payload["prompt_cache_options"] = {"mode": "explicit"}
+ if cache_cfg.resource is not None:
+ raise UnsupportedFeatureError(
+ f"{provider}: cache.resource is not supported — this provider has no stored-cache "
+ "tier; it caches by marks on blocks (prefix / prefix_until_index) and automatically",
+ provider=provider,
+ )
+
+
+def _breakpoint_unsupported(provider: str, index: int, role: str) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(
+ f"{provider}: cache.prefix_until_index={index} points at a {role} message "
+ "whose last block is not text — the wire carries prompt_cache_breakpoint "
+ "on text input blocks only. Point the prefix at a user/developer message "
+ "that ends with text, or omit prefix_until_index (implicit caching still "
+ "applies).",
+ provider=provider,
+ )
+
+
+def _record_unmapped(unmapped: list[dict[str, str]], path: str, typ: Any) -> None:
+ unmapped.append({"path": path, "type": str(typ or "<missing>")})
+
+
+def _builtin_to_openai(tool: BuiltinTool, compat: "ResolvedOpenAIResponsesCompat") -> dict[str, Any]:
+ out: dict[str, Any] = {"type": _builtin_type(tool, compat)}
+ if tool.config:
+ out.update(tool.config)
+ return out
+
+
+def _response_format_to_openai_text(format_config: dict[str, Any]) -> dict[str, Any]:
+ """Canonical response_format (INV-050) -> OpenAI Responses `text` config."""
+ if format_config["type"] == "json_object":
+ return {"format": {"type": "json_object"}}
+ fmt: dict[str, Any] = {"type": "json_schema", "name": format_config.get("name") or "response", "schema": format_config["schema"]}
+ if "strict" in format_config:
+ fmt["strict"] = format_config["strict"]
+ return {"format": fmt}
+
+
+def _finish_from_status(data: dict[str, Any], *, has_tool_call: bool = False) -> str:
+ if has_tool_call:
+ return "tool_call"
+ status = str(data.get("status") or "").lower()
+ incomplete = data.get("incomplete_details") or {}
+ reason = str(incomplete.get("reason") or "").lower() if isinstance(incomplete, dict) else ""
+ if status == "incomplete" and "token" in reason:
+ return "length"
+ if "content_filter" in reason or "safety" in reason:
+ return "content_filter"
+ return "stop"
+
+
+def _openai_batch_status(status: str) -> str:
+ """Map an OpenAI Batch status to the canonical BatchStatus."""
+ status = status.lower()
+ if status in {"completed", "failed", "cancelled", "expired"}:
+ return status
+ if status in {"cancelling", "canceling"}:
+ return "cancelling"
+ if status in {"in_progress", "finalizing"}:
+ return "running"
+ return "queued" # validating / queued / anything pre-run
+
+
+def _str_or_none(value: Any) -> str | None:
+ if value is None or value == "":
+ return None
+ return str(value)
+
+
+def _int_or_none(value: Any) -> int | None:
+ if isinstance(value, bool) or value is None:
+ return None
+ try:
+ return int(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _annotation_text(annotation: dict[str, Any], source_text: str | None) -> str | None:
+ for key in ("text", "snippet", "cited_text", "quote"):
+ text = _str_or_none(annotation.get(key))
+ if text is not None:
+ return text
+
+ start = _int_or_none(annotation.get("start_index"))
+ end = _int_or_none(annotation.get("end_index"))
+ if source_text is not None and start is not None and end is not None:
+ if 0 <= start < end <= len(source_text):
+ return source_text[start:end]
+ return None
+
+
+def _citation_from_openai_annotation(annotation: dict[str, Any], source_text: str | None) -> CitationPart | None:
+ url = _str_or_none(annotation.get("url") or annotation.get("uri"))
+ title = _str_or_none(
+ annotation.get("title")
+ or annotation.get("filename")
+ or annotation.get("file_id")
+ )
+ text = _annotation_text(annotation, source_text)
+ if url is None and title is None and text is None:
+ return None
+ return CitationPart(url=url, title=title, text=text)
+
+
+def _citation_delta_from_openai_annotation(
+ annotation: dict[str, Any],
+ *,
+ part_index: int,
+ source_text: str | None = None,
+) -> CitationDelta | None:
+ citation = _citation_from_openai_annotation(annotation, source_text)
+ if citation is None:
+ return None
+ return CitationDelta(
+ text=citation.text,
+ url=citation.url,
+ title=citation.title,
+ part_index=part_index,
+ )
+
+
+_DEFAULT_BASE_URL = "https://api.openai.com/v1"
+CODEX_BACKEND = "chatgpt-codex"
+
+
+def _is_codex(lm: BaseProviderLM) -> bool:
+ # A function, not a method: OpenAIChatLM borrows normalize_error.
+ return lm.access.backend == CODEX_BACKEND
+MODEL_LIST_HINT = "List the models your subscription accepts: call .list_models() on this client."
+
+
+def _live_usage_from_response(response: dict[str, Any]) -> Usage | None:
+ """Usage from a Realtime ``response.done`` payload, or None when absent."""
+ usage_data = response.get("usage") if isinstance(response, dict) else None
+ if not isinstance(usage_data, dict):
+ return None
+ u_in = usage_data.get("input_token_details") or usage_data.get("input_tokens_details") or {}
+ u_out = usage_data.get("output_token_details") or usage_data.get("output_tokens_details") or {}
+ return Usage(
+ input_tokens=usage_data.get("input_tokens"),
+ output_tokens=usage_data.get("output_tokens"),
+ total_tokens=usage_data.get("total_tokens"),
+ reasoning_tokens=u_out.get("reasoning_tokens"),
+ cache_read_tokens=u_in.get("cached_tokens"),
+ cache_write_tokens=u_in.get("cache_write_tokens"),
+ input_audio_tokens=u_in.get("audio_tokens"),
+ output_audio_tokens=u_out.get("audio_tokens"),
+ )
+
+
+@dataclass(slots=True)
+class OpenAILM(BaseProviderLM):
+ """OpenAI Responses dialect, bound to an access policy.
+
+ ``access`` defaults to the API-key policy (``lm15.access.OPENAI_API``);
+ ``lm15.access.OPENAI_CODEX`` binds the same dialect to the ChatGPT Codex
+ backend on a local Codex CLI login (``OpenAICodexLM`` is that binding
+ under a name). Policy consult points: the auth header and static
+ headers, the ``chatgpt-account-id`` header when the credential carries
+ an account, the login hint on errors, the endpoint surfaces, and the
+ ``backend`` switch at four stated places — payload defaults
+ (instructions prefix, ``store: false``, streaming-only, no max-token
+ knob), streaming-first ``complete``, the ``{"detail": ...}`` error
+ envelope, and the ``/models`` endpoint shape.
+ """
+
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: SyncTransport = field(default_factory=default_transport)
+ base_url: str = _DEFAULT_BASE_URL
+ profile: ProviderProfile | None = None
+ # An OpenAIResponsesCompat, a preset name (``"openai"``, ``"meta"``,
+ # ``"openrouter"``, …) or None. Same contract as the chat and
+ # Anthropic dialects: a preset name also supplies that server's default
+ # base_url; an explicit non-default base_url argument always wins. A
+ # profile and request extensions still layer on top (lm15.profiles).
+ compat: OpenAIResponsesCompat | str | None = field(default=None, kw_only=True)
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = field(default=None, kw_only=True)
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False, kw_only=True)
+ account_id: str | None = None
+
+ provider: str = field(default="openai", init=False)
+ manifest: ClassVar[ProviderManifest] = OPENAI_API
+ _compat_base: OpenAIResponsesCompat | None = field(init=False, repr=False, default=None)
+
+ def __post_init__(self) -> None:
+ self._bind_access(self.access, credentials_path=self.credentials_path, default_base_url=_DEFAULT_BASE_URL, settings=self.settings)
+ compat = self.compat if self.compat is not None else self._registry_compat()
+ if isinstance(compat, str):
+ self._compat_base = OpenAIResponsesCompat.preset(compat)
+ if self.base_url == _DEFAULT_BASE_URL:
+ self.base_url = OPENAI_RESPONSES_PRESET_BASE_URLS.get(_preset_key(compat), _DEFAULT_BASE_URL)
+ elif isinstance(compat, OpenAIResponsesCompat):
+ self._compat_base = compat
+ elif compat is not None:
+ raise TypeError("OpenAILM.compat must be an OpenAIResponsesCompat, a preset name, or None")
+ if self.access.backend == CODEX_BACKEND:
+ if not self.account_id and isinstance(self.api_key, str):
+ self.account_id = extract_chatgpt_account_id(self.api_key)
+ if not self.account_id:
+ raise NotConfiguredError(
+ "No ChatGPT account id found in the Codex OAuth token.",
+ provider=self.provider,
+ credential_hint=self.access.login_hint,
+ )
+
+ @property
+ def _codex(self) -> bool:
+ return _is_codex(self)
+
+ _response_error_code_map: ClassVar[dict[str, type[ProviderError]]] = {
+ "server_error": ServerError,
+ "rate_limit_exceeded": RateLimitError,
+ "invalid_prompt": InvalidRequestError,
+ "vector_store_timeout": TimeoutError,
+ "invalid_image": InvalidRequestError,
+ "invalid_image_format": InvalidRequestError,
+ "invalid_base64_image": InvalidRequestError,
+ "invalid_image_url": InvalidRequestError,
+ "image_too_large": InvalidRequestError,
+ "image_too_small": InvalidRequestError,
+ "image_parse_error": InvalidRequestError,
+ "image_content_policy_violation": InvalidRequestError,
+ "invalid_image_mode": InvalidRequestError,
+ "image_file_too_large": InvalidRequestError,
+ "unsupported_image_media_type": InvalidRequestError,
+ "empty_image_file": InvalidRequestError,
+ "failed_to_download_image": InvalidRequestError,
+ "image_file_not_found": InvalidRequestError,
+ "model_not_found": UnsupportedModelError,
+ "model_not_available": UnsupportedModelError,
+ "unsupported_model": UnsupportedModelError,
+ # Azure OpenAI: the model string IS the deployment name, so an unknown
+ # deployment is an unknown model (HTTP 404, "The API deployment for
+ # this resource does not exist"; live 2026-09-04,
+ # lm15-contract/errors/cases/azure.json).
+ "DeploymentNotFound": UnsupportedModelError,
+ }
+
+ _model_error_codes: ClassVar[frozenset[str]] = frozenset(
+ {"model_not_found", "model_not_available", "unsupported_model", "DeploymentNotFound"}
+ )
+
+ _stream_error_code_map: ClassVar[dict[str, type[ProviderError]]] = {
+ **_response_error_code_map,
+ "context_length_exceeded": ContextLengthError,
+ "invalid_api_key": AuthError,
+ "insufficient_quota": BillingError,
+ "1113": BillingError, # Z.AI insufficient balance (docs.z.ai api-code.md)
+ "exceeded_current_quota_error": BillingError, # Moonshot: balance/quota, rides HTTP 429 (platform.kimi.ai errors.md)
+ "authentication_error": AuthError,
+ "rate_limit_error": RateLimitError,
+ }
+
+ @classmethod
+ def from_profile(
+ cls,
+ *,
+ api_key: Credential,
+ profile: ProviderProfile,
+ transport: SyncTransport | None = None,
+ ) -> "OpenAILM":
+ endpoint = profile.endpoint("inference")
+ base_url = endpoint.base_url if endpoint and endpoint.base_url else "https://api.openai.com/v1"
+ return cls(
+ api_key=api_key,
+ transport=transport or default_transport(),
+ base_url=base_url,
+ profile=profile,
+ )
+
+ def _headers(self, content_type: str = "application/json") -> dict[str, str]:
+ headers: dict[str, str] = {} # auth is applied once, in _emit (AUTH-2)
+ headers["Content-Type"] = content_type
+ if self._codex and self.account_id:
+ headers["chatgpt-account-id"] = self.account_id
+ for key, static in self.access.headers:
+ headers[key] = static
+ return headers
+
+ @staticmethod
+ def _is_model_error(message: str, *codes: str) -> bool:
+ lowered = " ".join(value for value in (message, *codes) if value).lower()
+ return "model" in lowered and any(
+ marker in lowered
+ for marker in (
+ "not found",
+ "does not exist",
+ "not exist",
+ "not supported",
+ "unsupported",
+ "not available",
+ "unknown",
+ )
+ )
+
+ def _response_error(self, code: str, message: str) -> ProviderError:
+ cls = self._response_error_code_map.get(code, ServerError)
+ msg = message or code or "provider error"
+ return self._provider_error(cls, msg, provider_code=code or None)
+
+ def _error_detail(self, provider_code: str, message: str) -> ErrorDetail:
+ cls = self._stream_error_code_map.get(provider_code, ProviderError)
+ return ErrorDetail(
+ code=canonical_error_code(cls),
+ message=message or provider_code or "provider error",
+ provider_code=provider_code or "provider",
+ )
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ """Extract message from OpenAI error shape."""
+ if _is_codex(self):
+ # The ChatGPT Codex backend does not always use the OpenAI error
+ # envelope ({"error": {...}}); rejections arrive as
+ # {"detail": "..."} (e.g. an unknown model slug -> HTTP 400 with
+ # a plain-text reason). Recover and classify that first.
+ detail_error = self._normalize_detail_error(status, body)
+ if detail_error is not None:
+ return detail_error
+ try:
+ data = json.loads(body)
+ err = data.get("error", {}) if isinstance(data, dict) else {}
+ msg = err.get("message", "") if isinstance(err, dict) else str(err)
+ code = str(err.get("code") or "") if isinstance(err, dict) else ""
+ err_type = str(err.get("type") or "") if isinstance(err, dict) else ""
+
+ provider_code = code or err_type or None
+
+ if code == "context_length_exceeded":
+ return self._provider_error(
+ ContextLengthError,
+ msg,
+ status=status,
+ provider_code=provider_code,
+ )
+ if code in self._model_error_codes or (
+ status == 404 and self._is_model_error(msg, code, err_type)
+ ):
+ return self._provider_error(
+ UnsupportedModelError,
+ msg,
+ status=status,
+ provider_code=provider_code,
+ )
+ # Billing before rate-limit: both can ride HTTP 429, and only one
+ # is retryable. "insufficient_quota" is OpenAI's spelling; "1113"
+ # is Z.AI's ("Insufficient balance or no resource package",
+ # docs.z.ai api-code.md; observed live 2026-09-03 as 429);
+ # "exceeded_current_quota_error" is Moonshot's type for an
+ # insufficient balance or a disabled account, also HTTP 429
+ # (platform.kimi.ai errors.md — documentation-evidenced: a funded
+ # account cannot trigger it on purpose).
+ if code in {"insufficient_quota", "1113"} or err_type in {"insufficient_quota", "exceeded_current_quota_error"}:
+ return self._provider_error(
+ BillingError,
+ msg,
+ status=status,
+ provider_code=provider_code,
+ )
+ if code == "invalid_api_key" or err_type == "authentication_error":
+ return self._provider_error(
+ AuthError,
+ msg,
+ status=status,
+ provider_code=provider_code,
+ )
+ if code == "rate_limit_exceeded" or err_type == "rate_limit_error":
+ return self._provider_error(
+ RateLimitError,
+ msg,
+ status=status,
+ provider_code=provider_code,
+ )
+ if code and code not in msg:
+ msg = f"{msg} ({code})"
+ except Exception:
+ msg = body.strip()[:500] or f"HTTP {status}"
+ provider_code = None
+ return self._with_login_hint(map_http_error(
+ status,
+ msg,
+ provider=self.provider,
+ env_keys=self.access.env_keys,
+ provider_code=provider_code,
+ ))
+
+ def _normalize_detail_error(self, status: int, body: str) -> ProviderError | None:
+ try:
+ data = json.loads(body)
+ except ValueError:
+ return None
+ if not isinstance(data, dict):
+ return None
+ detail = data.get("detail")
+ if not isinstance(detail, str) or not detail.strip():
+ return None
+ detail = detail.strip()
+ if self._is_model_error(detail):
+ return self._provider_error(UnsupportedModelError, f"{detail}\n{MODEL_LIST_HINT}", status=status)
+ return self._with_login_hint(map_http_error(status, detail, provider=self.provider))
+
+ # ─── Request serialization ──────────────────────────────────────
+
+ def _compat(self, request: Request) -> ResolvedOpenAIResponsesCompat:
+ return resolve_openai_responses_compat(
+ base_url=self.base_url,
+ model=request.model,
+ profile=self.profile,
+ request_extensions=request.config.extensions,
+ base=self._compat_base,
+ )
+
+ def _build_input(
+ self,
+ messages: tuple[Message, ...],
+ compat: ResolvedOpenAIResponsesCompat,
+ *,
+ breakpoint_index: int | None = None,
+ ) -> list[dict[str, Any]]:
+ items: list[dict[str, Any]] = []
+ for msg_index, msg in enumerate(messages):
+ if msg_index == breakpoint_index and msg.role in ("assistant", "tool"):
+ raise _breakpoint_unsupported(self.provider, msg_index, msg.role)
+ if msg.role == "tool":
+ for part in msg.parts:
+ if isinstance(part, ToolResultPart):
+ # MAP-10: text-only → string; media → the documented
+ # input_text/input_image/input_file array; a part
+ # the preset does not admit raised before this line.
+ item = {
+ "type": "function_call_output",
+ "call_id": part.id,
+ "output": tool_result_output_openai(self.provider, part, compat.tool_result_media),
+ }
+ if compat.tool_result_name == "include" and part.name:
+ item["name"] = part.name
+ items.append(item)
+ continue
+
+ if msg.role == "assistant":
+ content_parts = []
+ for part in msg.parts:
+ if isinstance(part, TextPart):
+ content_parts.append({"type": "output_text", "text": part.text})
+ elif isinstance(part, RefusalPart):
+ content_parts.append({"type": "refusal", "refusal": part.text})
+ elif isinstance(part, ThinkingPart):
+ state = continuation_data(part, "openai", "reasoning_item")
+ if state:
+ # Native replay (MAP-7 rule 8): the reasoning item
+ # goes back as its own input item, before the
+ # message it preceded.
+ item = {"type": "reasoning", **{k: v for k, v in state.items() if k in ("id", "encrypted_content")}}
+ # `summary` is required on a replayed item, even
+ # empty (HTTP 400 "Missing required parameter:
+ # input[1].summary", live 2026-09-02).
+ item["summary"] = [{"type": "summary_text", "text": part.text}] if part.text else []
+ items.append(item)
+ elif part.text:
+ # No native state: replay as assistant text
+ # (decision G, 2026-09-01) rather than drop it.
+ content_parts.append({"type": "output_text", "text": part.text})
+ else:
+ content_parts = [
+ part_to_openai_input(part, provider=self.provider)
+ for part in msg.parts
+ if not isinstance(part, (ToolCallPart, ToolResultPart))
+ ]
+ if msg_index == breakpoint_index:
+ # CacheConfig.prefix_until_index -> an explicit prompt-cache
+ # breakpoint on the last text block of that message (the
+ # Anthropic cache_control precedent). The Responses wire
+ # carries prompt_cache_breakpoint on input_text blocks only
+ # (gpt-5.6+, verified live 2026-09-01: cache_write_tokens on
+ # the first call, cached_tokens on the next; pre-5.6 models
+ # reject with HTTP 400 — that loud failure is the contract).
+ if not content_parts or content_parts[-1].get("type") != "input_text":
+ raise _breakpoint_unsupported(self.provider, msg_index, msg.role)
+ content_parts[-1]["prompt_cache_breakpoint"] = {"mode": "explicit"}
+ if content_parts:
+ role = msg.role
+ if role == "developer":
+ role = compat.developer_role
+ item = {"role": role, "content": content_parts}
+ if (
+ compat.commentary_phase == "tag"
+ and msg.role == "assistant"
+ and any(isinstance(p, ToolCallPart) for p in msg.parts)
+ ):
+ # Assistant text that precedes a function_call in the same
+ # turn is "commentary" on this server (Meta,
+ # protocols--responses.md § Message phase); the server
+ # stamped it on the way out and asks for it back.
+ item["phase"] = "commentary"
+ items.append(item)
+
+ for part in msg.parts:
+ if isinstance(part, ToolCallPart):
+ items.append(
+ {
+ "type": "function_call",
+ "call_id": part.id,
+ "name": part.name,
+ "arguments": json.dumps(part.input, separators=(",", ":")),
+ }
+ )
+ return items
+
+ def _tool_choice_payload(self, request: Request, compat: "ResolvedOpenAIResponsesCompat") -> Any:
+ tc = request.config.tool_choice
+ if tc is None:
+ return None
+ if tc.mode == "none":
+ return "none"
+ if tc.allowed:
+ # Resolve names against Request.tools (INV-031 guarantees
+ # presence) and emit the kind-correct wire form. Verified live
+ # 2026-09-01: {"type": "web_search_preview"} forcing and mixed
+ # allowed_tools both accepted.
+ by_name = {t.name: t for t in request.tools}
+ entries = [by_name[name] for name in tc.allowed]
+ if len(entries) == 1 and tc.mode == "required":
+ tool = entries[0]
+ if isinstance(tool, BuiltinTool):
+ return {"type": _builtin_type(tool, compat)}
+ return {"type": "function", "name": tool.name}
+ # mode="auto" restriction or multi-tool subset: allowed_tools
+ # keeps auto semantics honest — the old single-name mapping
+ # forced a call even when the caller said mode="auto".
+ wire_tools: list[dict[str, Any]] = []
+ for tool in entries:
+ if isinstance(tool, BuiltinTool):
+ wire_tools.append({"type": _builtin_type(tool, compat)})
+ else:
+ wire_tools.append({"type": "function", "name": tool.name})
+ return {"type": "allowed_tools", "mode": tc.mode, "tools": wire_tools}
+ if tc.mode == "required":
+ return "required"
+ return "auto"
+
+ def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ compat = self._compat(request)
+ payload: dict[str, Any] = {
+ "model": request.model,
+ "input": self._build_input(
+ request.messages,
+ compat,
+ breakpoint_index=_cache_breakpoint_index(request, compat.cache_control),
+ ),
+ "stream": stream,
+ }
+ if request.system:
+ system_text = request.system if isinstance(request.system, str) else parts_to_text(request.system)
+ if _cache_stable_prefix(request, compat.cache_control):
+ # Top-level `instructions` cannot carry a breakpoint
+ # (prompt-caching guide: "place them in an input_text block
+ # inside a developer message"). The stable-prefix intent
+ # therefore renders the system prompt as the first input
+ # item with the mark on it.
+ payload["input"].insert(0, {
+ "role": compat.developer_role,
+ "content": [{"type": "input_text", "text": system_text, "prompt_cache_breakpoint": {"mode": "explicit"}}],
+ })
+ else:
+ payload["instructions"] = system_text
+ if request.config.max_tokens is not None:
+ payload[compat.max_output_tokens_field] = request.config.max_tokens
+ if request.config.temperature is not None:
+ payload["temperature"] = request.config.temperature
+ if request.config.top_p is not None:
+ payload["top_p"] = request.config.top_p
+ if request.config.stop:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.stop has no field on the Responses wire (the Chat Completions "
+ "dialect carries `stop`); a silent omission would run the model past the sequence",
+ provider=self.provider,
+ )
+ if request.config.top_k is not None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.top_k has no field on the Responses wire (Anthropic and Gemini carry it)",
+ provider=self.provider,
+ )
+ if request.config.logprobs is not None:
+ # Verified live 2026-09-01: include triggers per-token logprobs;
+ # top_logprobs (0–20) controls the alternatives count.
+ payload["top_logprobs"] = request.config.logprobs
+ payload["include"] = ["message.output_text.logprobs"]
+ if request.tools:
+ tools_wire: list[dict[str, Any]] = []
+ for tool in request.tools:
+ if isinstance(tool, FunctionTool):
+ tool_payload = {
+ "type": "function",
+ "name": tool.name,
+ "description": tool.description,
+ "parameters": tool.parameters,
+ }
+ if compat.strict_tools == "include":
+ tool_payload["strict"] = False
+ tools_wire.append(tool_payload)
+ elif isinstance(tool, BuiltinTool):
+ tools_wire.append(_builtin_to_openai(tool, compat))
+ payload["tools"] = tools_wire
+ tool_choice = self._tool_choice_payload(request, compat)
+ if tool_choice is not None:
+ payload["tool_choice"] = tool_choice
+ if request.config.tool_choice and request.config.tool_choice.parallel is not None:
+ payload["parallel_tool_calls"] = request.config.tool_choice.parallel
+ if request.config.response_format:
+ payload["text"] = _response_format_to_openai_text(request.config.response_format)
+ if request.config.reasoning:
+ reasoning = request.config.reasoning
+ if not reasoning.is_off:
+ # MAP-7: the word goes verbatim; models reject unsupported
+ # levels with a 400 that lists the supported set (live
+ # 2026-09-02: gpt-5.6-sol rejects minimal, gpt-5.4-mini
+ # rejects max). No budget exists on this wire.
+ if reasoning.thinking_budget is not None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.thinking_budget is not supported — this wire "
+ "has no thinking token budget; use effort (Anthropic's manual class and "
+ "Gemini take a budget)",
+ provider=self.provider,
+ )
+ effort = reasoning.effort
+ if reasoning.summary in ("concise", "detailed") and compat.reasoning_format != "responses_reasoning":
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.summary={reasoning.summary!r} is an OpenAI Responses "
+ "detail level; this wire has no summary levels (use 'auto')",
+ provider=self.provider,
+ )
+ if compat.reasoning_format == "responses_reasoning":
+ reasoning_payload: dict[str, Any] = {"effort": effort}
+ if reasoning.summary is not None:
+ reasoning_payload["summary"] = reasoning.summary
+ payload["reasoning"] = reasoning_payload
+ elif compat.reasoning_format == "reasoning_effort":
+ payload["reasoning_effort"] = effort
+ elif compat.reasoning_format == "openrouter":
+ payload["reasoning"] = {"effort": effort}
+ elif compat.reasoning_format == "deepseek":
+ payload["thinking"] = {"type": "enabled"}
+ payload["reasoning_effort"] = effort
+ elif compat.reasoning_format in {"qwen", "zai"}:
+ payload["enable_thinking"] = True
+ elif compat.reasoning_format == "qwen_chat_template":
+ payload["chat_template_kwargs"] = {
+ "enable_thinking": True,
+ "preserve_thinking": True,
+ }
+ else:
+ # Explicit off must reach the wire. Sending nothing lets
+ # reasoning-by-default models (gpt-5 family, o-series) burn
+ # hidden reasoning tokens the caller asked to disable —
+ # verified live 2026-09-01: gpt-5-mini spent 64 reasoning
+ # tokens on a request with effort="off" when the field was
+ # omitted. Models whose floor is "minimal" reject
+ # "none" with a clear 400; that loud failure is deliberate
+ # (a silent default-effort run spends money on hidden
+ # reasoning tokens the caller asked to disable).
+ if compat.reasoning_format == "responses_reasoning":
+ payload["reasoning"] = {"effort": "none"}
+ elif compat.reasoning_format == "reasoning_effort":
+ payload["reasoning_effort"] = "none"
+ elif compat.reasoning_format == "openrouter":
+ payload["reasoning"] = {"enabled": False}
+ elif compat.reasoning_format == "deepseek":
+ payload["thinking"] = {"type": "disabled"}
+ elif compat.reasoning_format in {"qwen", "zai"}:
+ payload["enable_thinking"] = False
+ elif compat.reasoning_format == "qwen_chat_template":
+ payload["chat_template_kwargs"] = {"enable_thinking": False}
+
+ # Prompt caching (MAP-6): off switch, key, retention, resource.
+ _cache_common_payload(request, payload, compat.cache_control, self.provider)
+
+ if compat.routing is not None:
+ payload["provider"] = compat.routing
+
+ # Promoted cross-provider knobs (changes/2026-09-01-extensions-burn-down):
+ # canonical spelling in, provider spelling out. user_id maps to
+ # safety_identifier — OpenAI's current end-user attribution field
+ # (`user` is the deprecated legacy spelling; still available verbatim
+ # through extensions).
+ if request.config.service_tier is not None:
+ payload["service_tier"] = request.config.service_tier
+ if request.config.user_id is not None:
+ payload["safety_identifier"] = request.config.user_id
+ if request.config.store is not None:
+ payload["store"] = request.config.store
+
+ if request.config.extensions:
+ reserved = {
+ "prompt_caching",
+ "cache",
+ "compat",
+ "openai_compat",
+ "openai_responses_compat",
+ }
+ passthrough = {k: v for k, v in request.config.extensions.items() if k not in reserved}
+ payload.update(passthrough)
+ if self._codex:
+ # Backend facts (live 2026-08-31): the Codex backend is
+ # streaming-only, rejects store=true and every max-token knob,
+ # and expects instructions to be present.
+ if self.access.system_prefix:
+ payload.setdefault("instructions", self.access.system_prefix)
+ payload["store"] = False
+ payload["stream"] = True
+ payload.pop("max_output_tokens", None)
+ payload.pop("max_completion_tokens", None)
+ payload.pop("max_tokens", None)
+ return payload
+
+ def build_request(self, request: Request, stream: bool) -> TransportRequest:
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/responses",
+ endpoint="responses",
+ stream=stream,
+ model=request.model,
+ headers=self._headers(),
+ payload=self._payload(request, stream=stream),
+ read_timeout=120.0 if stream else 60.0,
+ )
+
+ # ─── Response parsing ───────────────────────────────────────────
+
+ def parse_response(self, request: Request, response: HttpResponse) -> Response:
+ data = response.json()
+
+ resp_error = data.get("error") if isinstance(data, dict) else None
+ if isinstance(resp_error, dict):
+ raise self._response_error(
+ str(resp_error.get("code") or ""),
+ str(resp_error.get("message") or resp_error),
+ )
+
+ parts: list[Any] = []
+ unmapped: list[dict[str, str]] = []
+ logprob_seq: list[Any] = []
+ for item_index, item in enumerate(data.get("output", []) or []):
+ if not isinstance(item, dict):
+ _record_unmapped(unmapped, f"output[{item_index}]", type(item).__name__)
+ continue
+ item_type = item.get("type")
+ if item_type == "message":
+ for content_index, content in enumerate(item.get("content", []) or []):
+ if not isinstance(content, dict):
+ _record_unmapped(unmapped, f"output[{item_index}].content[{content_index}]", type(content).__name__)
+ continue
+ ctype = content.get("type")
+ if ctype in ("output_text", "text"):
+ text = str(content.get("text") or "")
+ parts.append(TextPart(text=text))
+ # Per-block wire lists concatenate in document order
+ # into the message-level canonical sequence.
+ logprob_seq.extend(openai_token_logprobs(content.get("logprobs")))
+ for annotation in content.get("annotations", []) or []:
+ if not isinstance(annotation, dict):
+ continue
+ citation = _citation_from_openai_annotation(annotation, text)
+ if citation is not None:
+ parts.append(citation)
+ elif ctype == "refusal":
+ text = str(content.get("refusal") or content.get("text") or "")
+ parts.append(RefusalPart(text=text) if text else TextPart(text=""))
+ elif ctype == "output_image":
+ b64 = content.get("b64_json") or content.get("image_base64") or ""
+ if b64:
+ parts.append(ImagePart(media_type="image/png", data=str(b64)))
+ elif ctype == "output_audio":
+ audio_payload = content.get("audio") if isinstance(content.get("audio"), dict) else {}
+ b64 = audio_payload.get("data") or content.get("b64_json") or ""
+ if b64:
+ parts.append(AudioPart(media_type="audio/wav", data=str(b64)))
+ else:
+ _record_unmapped(unmapped, f"output[{item_index}].content[{content_index}]", ctype)
+ elif item_type == "function_call":
+ if not item.get("name"):
+ raise unnamed_tool_call_error(self.provider, f"output[{item_index}]")
+ parts.append(
+ ToolCallPart(
+ id=str(item.get("call_id") or item.get("id") or f"call_{len(parts)}"),
+ name=str(item["name"]),
+ input=parse_json_object(item.get("arguments")),
+ )
+ )
+ elif item_type == "reasoning":
+ # MAP-7 rule 8: the reasoning item is replay state. Its
+ # summary (when requested) is the visible text; its id and
+ # encrypted_content ride as continuation so the next turn
+ # can send the item back verbatim (live 2026-09-02:
+ # encrypted_content is present on every reasoning item).
+ summary = item.get("summary")
+ if isinstance(summary, list):
+ text = "\n".join(str(x.get("text") if isinstance(x, dict) else x) for x in summary)
+ else:
+ text = str(summary or item.get("text") or "")
+ state: dict[str, Any] = {}
+ if item.get("id"):
+ state["id"] = str(item["id"])
+ if item.get("encrypted_content"):
+ state["encrypted_content"] = str(item["encrypted_content"])
+ continuation = (ContinuationState(provider="openai", kind="reasoning_item", data=state),) if state else ()
+ if text or continuation:
+ parts.append(ThinkingPart(text=text, continuation=continuation))
+ elif item_type in OPENAI_PROVIDER_EXECUTED_ITEMS:
+ continue
+ else:
+ _record_unmapped(unmapped, f"output[{item_index}]", item_type)
+
+ if not parts:
+ parts = [TextPart(text=str(data.get("output_text") or ""))]
+
+ usage_data = data.get("usage", {}) or {}
+ input_details = usage_data.get("input_tokens_details") or {}
+ output_details = usage_data.get("output_tokens_details") or {}
+ usage = Usage(
+ input_tokens=usage_data.get("input_tokens"),
+ output_tokens=usage_data.get("output_tokens"),
+ total_tokens=usage_data.get("total_tokens"),
+ reasoning_tokens=output_details.get("reasoning_tokens"),
+ cache_read_tokens=input_details.get("cached_tokens"),
+ cache_write_tokens=input_details.get("cache_write_tokens"),
+ input_audio_tokens=input_details.get("audio_tokens"),
+ output_audio_tokens=output_details.get("audio_tokens"),
+ )
+
+ has_tool = any(isinstance(part, ToolCallPart) for part in parts)
+ # D8 (2026-09-06): Response.id carries the response id; no
+ # message-level continuation state is minted for it.
+ return Response(
+ id=str(data.get("id")) if data.get("id") else None,
+ model=str(data.get("model") or request.model),
+ message=Message(role="assistant", parts=tuple(parts)),
+ finish_reason=_finish_from_status(data, has_tool_call=has_tool),
+ usage=usage,
+ logprobs=tuple(logprob_seq) if logprob_seq else None,
+ provider_data=_attach_unmapped(data, unmapped),
+ )
+
+ def parse_stream_events(self, request: Request, raw_event: SSEEvent) -> Iterator[StreamEvent]:
+ payload = json.loads(raw_event.data) if raw_event.data and raw_event.data != "[DONE]" else None
+ if isinstance(payload, dict) and payload.get("type") in {"response.output_item.added", "response.output_item.done"}:
+ item = payload.get("item")
+ if isinstance(item, dict) and item.get("type") == "reasoning":
+ index = int(payload.get("output_index", 0) or 0)
+ if payload["type"] == "response.output_item.added":
+ # MAP-7.9: even an item with no visible summary is thinking.
+ yield StreamDeltaEvent(delta=ThinkingDelta(text="", part_index=index))
+ else:
+ # Final replay state can arrive after all summary fragments.
+ # Do not repeat those fragments from the completed snapshot.
+ state = {key: item[key] for key in ("id", "encrypted_content") if item.get(key)}
+ if state:
+ yield StreamDeltaEvent(delta=ContinuationDelta(
+ provider="openai", kind="reasoning_item", data=state, part_index=index,
+ ))
+ return
+ event = self._parse_single_stream_event(request, raw_event, payload=payload)
+ if event is not None:
+ yield event
+
+ def _parse_single_stream_event(self, request: Request, raw_event: SSEEvent, *, payload: JsonObject | None = None) -> StreamEvent | None:
+ if not raw_event.data:
+ return None
+ if raw_event.data == "[DONE]":
+ # A bare terminator: it carries no finish reason and no usage.
+ # response.completed already said how the turn ended; claiming
+ # "stop" here would overwrite "tool_call" in the coalesced end.
+ return StreamEndEvent()
+ if payload is None:
+ payload = json.loads(raw_event.data)
+ et = str(payload.get("type") or "")
+
+ if et == "response.created":
+ response = payload.get("response", {}) if isinstance(payload.get("response"), dict) else {}
+ return StreamStartEvent(
+ id=str(response.get("id")) if response.get("id") else None,
+ model=str(response.get("model") or request.model),
+ )
+
+ if et in {"response.output_text.delta", "response.refusal.delta"}:
+ return StreamDeltaEvent(
+ delta=TextDelta(
+ text=str(payload.get("delta") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ # Verified live 2026-09-01: each output_text.delta event
+ # carries the logprobs for exactly its own tokens.
+ logprobs=openai_token_logprobs(payload.get("logprobs")),
+ )
+ )
+
+ if et in {"response.reasoning_summary_text.delta", "response.reasoning_text.delta"}:
+ return StreamDeltaEvent(
+ delta=ThinkingDelta(
+ text=str(payload.get("delta") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ )
+ )
+
+ if et == "response.output_text.annotation.added":
+ annotation = payload.get("annotation")
+ if isinstance(annotation, dict):
+ delta = _citation_delta_from_openai_annotation(
+ annotation,
+ part_index=int(payload.get("output_index", 0) or 0),
+ )
+ if delta is not None:
+ return StreamDeltaEvent(delta=delta)
+ return None
+
+ if et == "response.output_audio.delta":
+ return StreamDeltaEvent(
+ delta=AudioDelta(
+ data=str(payload.get("delta") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ media_type="audio/wav",
+ )
+ )
+
+ if et in {"response.output_image.delta", "response.image.delta"}:
+ return StreamDeltaEvent(
+ delta=ImageDelta(
+ data=str(payload.get("delta") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ media_type="image/png",
+ )
+ )
+
+ if et == "response.output_item.added":
+ item = payload.get("item", {}) if isinstance(payload.get("item"), dict) else {}
+ if item.get("type") == "function_call":
+ return StreamDeltaEvent(
+ delta=ToolCallDelta(
+ input=str(item.get("arguments") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ id=str(item.get("call_id") or item.get("id") or "") or None,
+ name=str(item.get("name") or "") or None,
+ )
+ )
+ return None
+
+ if et == "response.function_call_arguments.delta":
+ return StreamDeltaEvent(
+ delta=ToolCallDelta(
+ input=str(payload.get("delta") or ""),
+ part_index=int(payload.get("output_index", 0) or 0),
+ id=str(payload.get("call_id") or payload.get("id") or "") or None,
+ name=str(payload.get("name") or "") or None,
+ )
+ )
+
+ if et == "response.completed":
+ response = payload.get("response", {}) if isinstance(payload.get("response"), dict) else {}
+ usage_data = response.get("usage", {}) if isinstance(response, dict) else {}
+ input_details = usage_data.get("input_tokens_details") or {}
+ output_details = usage_data.get("output_tokens_details") or {}
+ usage = Usage(
+ input_tokens=usage_data.get("input_tokens"),
+ output_tokens=usage_data.get("output_tokens"),
+ total_tokens=usage_data.get("total_tokens"),
+ reasoning_tokens=output_details.get("reasoning_tokens"),
+ cache_read_tokens=input_details.get("cached_tokens"),
+ cache_write_tokens=input_details.get("cache_write_tokens"),
+ input_audio_tokens=input_details.get("audio_tokens"),
+ output_audio_tokens=output_details.get("audio_tokens"),
+ )
+ output = response.get("output", []) if isinstance(response, dict) else []
+ has_tool = any(isinstance(item, dict) and item.get("type") == "function_call" for item in output)
+ return StreamEndEvent(
+ finish_reason="tool_call" if has_tool else "stop",
+ usage=usage,
+ provider_data=response if isinstance(response, dict) else None,
+ )
+
+ if et in {"response.error", "error"}:
+ err = payload.get("error")
+ if isinstance(err, dict):
+ provider_code = str(err.get("code") or err.get("type") or payload.get("code") or "provider")
+ message = str(err.get("message") or payload.get("message") or "")
+ else:
+ provider_code = str(payload.get("code") or payload.get("error_type") or "provider")
+ message = str(payload.get("message") or "")
+ return StreamErrorEvent(error=self._error_detail(provider_code, message))
+
+ return None
+
+ # ─── Streaming over OpenAI Realtime for live models ──────────────
+
+ def complete(self, request: Request) -> Response:
+ if self._codex:
+ # Streaming-first backend: materialize the stream so callers get
+ # the same synchronous complete() surface.
+ return materialize_response(self.stream(request), request)
+ return BaseProviderLM.complete(self, request)
+
+ def stream(self, request: Request) -> Iterator[StreamEvent]:
+ if not self._codex and self._should_use_live_completion(request):
+ yield from self._stream_via_live_completion(request)
+ return
+ # BaseProviderLM.stream applies the MAP-3 coalescer: the Codex
+ # backend sends response.completed (usage) and then [DONE], two
+ # adapter-level end frames merged into one.
+ yield from BaseProviderLM.stream(self, request)
+
+ def _should_use_live_completion(self, request: Request) -> bool:
+ extensions = request.config.extensions or {}
+ transport_mode = str(extensions.get("transport") or "").lower()
+ if transport_mode in {"live", "websocket", "ws"}:
+ return True
+ model_name = request.model.lower()
+ return "realtime" in model_name or "-live" in model_name
+
+ def _stream_via_live_completion(self, request: Request) -> Iterator[StreamEvent]:
+ ws = self._live_connect(self._live_url(request.model), self._live_headers())
+ saw_tool_call = False
+ usage = Usage()
+ try:
+ ws.send(json.dumps(self._live_session_update_from_request(request)))
+ for frame in self._live_message_frames_for_request(request):
+ ws.send(json.dumps(frame))
+
+ yield StreamStartEvent(model=request.model)
+ while True:
+ raw = ws.recv()
+ for event in self._decode_live_completion_stream_events(request, raw):
+ if event.type == "delta":
+ if isinstance(event.delta, ToolCallDelta):
+ saw_tool_call = True
+ yield event
+ elif event.type == "error":
+ yield event
+ return
+ elif event.type == "end":
+ if event.usage is not None:
+ usage = event.usage
+ yield StreamEndEvent(
+ finish_reason="tool_call" if saw_tool_call else (event.finish_reason or "stop"),
+ usage=usage,
+ )
+ return
+ finally:
+ try:
+ ws.close()
+ except Exception:
+ pass
+
+ def _live_session_update_from_request(self, request: Request) -> dict[str, Any]:
+ extensions = dict(request.config.extensions or {})
+ extensions.pop("transport", None)
+ extensions.pop("prompt_caching", None)
+ extensions.pop("output", None)
+ config = LiveConfig(
+ model=request.model,
+ system=request.system,
+ tools=request.tools,
+ extensions=extensions or None,
+ )
+ return self._live_session_update_payload(config)
+
+ def _live_message_frames_for_request(self, request: Request) -> list[dict[str, Any]]:
+ frames: list[dict[str, Any]] = []
+ for message in request.messages:
+ if message.role == "tool":
+ for part in message.parts:
+ if not isinstance(part, ToolResultPart):
+ continue
+ # Realtime's function_call_output is a string; a media part raises (MAP-10).
+ output = tool_result_error_text(part, parts_to_text(part.content, provider=self.provider, where="a Realtime function_call_output"))
+ frames.append({"type": "conversation.item.create", "item": {"type": "function_call_output", "call_id": part.id, "output": output}})
+ continue
+
+ content = [part_to_openai_input(p, provider=self.provider) for p in message.parts if not isinstance(p, (ToolCallPart, ToolResultPart))]
+ if content:
+ frames.append({"type": "conversation.item.create", "item": {"type": "message", "role": message.role, "content": content}})
+ for part in message.parts:
+ if isinstance(part, ToolCallPart):
+ frames.append({"type": "conversation.item.create", "item": {"type": "function_call", "call_id": part.id, "name": part.name, "arguments": json.dumps(part.input)}})
+
+ response_create: dict[str, Any] = {"type": "response.create"}
+ if (request.config.extensions or {}).get("output") == "audio":
+ response_create["response"] = {"output_modalities": ["audio"]} # GA name
+ frames.append(response_create)
+ return frames
+
+ def _decode_live_completion_stream_events(self, request: Request, raw: str | bytes) -> list[StreamEvent]:
+ try:
+ payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+ except Exception:
+ return []
+ if not isinstance(payload, dict):
+ return []
+ et = str(payload.get("type") or "")
+
+ if et in {"response.output_text.delta", "response.text.delta",
+ "response.output_audio_transcript.delta", "response.audio_transcript.delta"}:
+ delta = str(payload.get("delta") or payload.get("text") or "")
+ return [StreamDeltaEvent(delta=TextDelta(text=delta))] if delta else []
+ if et == "response.output_audio.delta":
+ delta = str(payload.get("delta") or "")
+ return [StreamDeltaEvent(delta=AudioDelta(data=delta, media_type="audio/wav"))] if delta else []
+ if et in {"response.output_item.added", "response.function_call_arguments.delta", "response.function_call_arguments.done", "response.output_item.done"}:
+ if et in {"response.output_item.added", "response.output_item.done"}:
+ item = payload.get("item", {}) if isinstance(payload.get("item"), dict) else {}
+ if item.get("type") != "function_call":
+ return []
+ call_id = str(item.get("call_id") or item.get("id") or "")
+ name = str(item.get("name") or "tool")
+ arguments = item.get("arguments") or ""
+ else:
+ call_id = str(payload.get("call_id") or payload.get("id") or "")
+ name = str(payload.get("name") or "tool")
+ arguments = payload.get("delta") if et.endswith("delta") else payload.get("arguments")
+ return [StreamDeltaEvent(delta=ToolCallDelta(input=arguments if isinstance(arguments, str) else json.dumps(arguments or {}), id=call_id or None, name=name))]
+ if et in {"response.done", "response.completed"}:
+ response = payload.get("response", {}) if isinstance(payload.get("response"), dict) else {}
+ usage_data = response.get("usage", {}) if isinstance(response, dict) else {}
+ u_in = usage_data.get("input_token_details") or usage_data.get("input_tokens_details") or {}
+ u_out = usage_data.get("output_token_details") or usage_data.get("output_tokens_details") or {}
+ usage = Usage(
+ input_tokens=usage_data.get("input_tokens"),
+ output_tokens=usage_data.get("output_tokens"),
+ total_tokens=usage_data.get("total_tokens"),
+ reasoning_tokens=u_out.get("reasoning_tokens"),
+ cache_read_tokens=u_in.get("cached_tokens"),
+ cache_write_tokens=u_in.get("cache_write_tokens"),
+ input_audio_tokens=u_in.get("audio_tokens"),
+ output_audio_tokens=u_out.get("audio_tokens"),
+ )
+ return [StreamEndEvent(finish_reason="stop", usage=usage, provider_data=response if isinstance(response, dict) else None)]
+ if et in {"error", "response.error"}:
+ err = payload.get("error")
+ if isinstance(err, dict):
+ provider_code = str(err.get("code") or err.get("type") or payload.get("code") or "provider")
+ message = str(err.get("message") or payload.get("message") or "")
+ else:
+ provider_code = str(payload.get("code") or payload.get("error_type") or "provider")
+ message = str(payload.get("message") or "")
+ return [StreamErrorEvent(error=self._error_detail(provider_code, message))]
+ return []
+
+ # ─── Live sessions ──────────────────────────────────────────────
+
+ def live(self, config: LiveConfig):
+ self._require("live")
+ ws = self._live_connect(self._live_url(config.model), self._live_headers())
+ for frame in self._live_setup_frames(config):
+ ws.send(json.dumps(frame))
+
+ return WebSocketLiveSession(
+ ws=ws,
+ encode_event=self._live_encoder(config),
+ decode_event=self._decode_live_server_event,
+ )
+
+ # Pure live-codec hooks (uniform across providers; the vet shim's
+ # replay_live op and the async twin drive these, never the socket).
+
+ def _live_setup_frames(self, config: LiveConfig) -> list[dict[str, Any]]:
+ return [self._live_session_update_payload(config)]
+
+ def _live_encoder(self, config: LiveConfig):
+ return self._encode_live_client_event
+
+ def _live_connect(self, url: str, headers: dict[str, str]):
+ connect = require_websocket_sync_connect()
+ return connect(url, additional_headers=headers)
+
+ def _live_url(self, model: str) -> str:
+ parsed = urllib.parse.urlparse(self.base_url)
+ scheme = "wss" if parsed.scheme == "https" else "ws"
+ base_path = parsed.path.rstrip("/")
+ path = f"{base_path}/realtime" if base_path else "/realtime"
+ query = urllib.parse.urlencode({"model": model})
+ return urllib.parse.urlunparse((scheme, parsed.netloc, path, "", query, ""))
+
+ def _live_headers(self) -> dict[str, str]:
+ # GA Realtime: the beta header now HARD-CLOSES the socket (4000
+ # `beta_api_shape_disabled`, observed live 2026-09-01). Use the
+ # access policy as ordinary HTTP does: Azure API keys travel under
+ # `api-key`; OpenAI and Entra tokens use Authorization.
+ value = resolve_credential_value(self.api_key)
+ pair = auth_header(self.access, value, api_key_header=self._api_key_header)
+ headers = dict(self.access.headers)
+ if pair is not None:
+ headers[pair[0]] = pair[1]
+ return headers
+
+ @staticmethod
+ def _live_audio_format(fmt: AudioFormat) -> dict[str, Any]:
+ # GA wire format objects: {"type": "audio/pcm", "rate": N} (pcmu/
+ # pcma carry no rate). Canonical pcm16 maps to audio/pcm.
+ if fmt.encoding == "pcm16":
+ return {"type": "audio/pcm", "rate": fmt.sample_rate}
+ return {"type": f"audio/{fmt.encoding}"}
+
+ def _live_session_update_payload(self, config: LiveConfig) -> dict[str, Any]:
+ # GA Realtime session shape (verified live 2026-09-01,
+ # curl-fixtures/live-2026-09-01/): session.type is required,
+ # `output_modalities` replaces `modalities`, and audio config
+ # nests under session.audio.{input,output}.
+ session: dict[str, Any] = {"type": "realtime"}
+ if config.system:
+ session["instructions"] = config.system if isinstance(config.system, str) else parts_to_text(config.system)
+ audio: dict[str, Any] = {}
+ if config.output_format is not None or config.voice:
+ session["output_modalities"] = ["audio"]
+ output: dict[str, Any] = {}
+ if config.output_format is not None:
+ output["format"] = self._live_audio_format(config.output_format)
+ if config.voice:
+ output["voice"] = config.voice
+ audio["output"] = output
+ else:
+ session["output_modalities"] = ["text"]
+ if config.input_format is not None:
+ # turn_detection null = server VAD OFF: a turn happens exactly
+ # when the caller sends end_audio() (commit + response.create),
+ # deterministic library behavior. Re-enable VAD through
+ # extensions when you want the server to segment speech.
+ audio["input"] = {"format": self._live_audio_format(config.input_format), "turn_detection": None}
+ if audio:
+ session["audio"] = audio
+ if config.tools:
+ session["tools"] = [
+ {"type": "function", "name": t.name, "description": t.description, "parameters": t.parameters}
+ for t in config.tools
+ if isinstance(t, FunctionTool)
+ ]
+ if config.extensions:
+ session.update(config.extensions)
+ return {"type": "session.update", "session": session}
+
+ def _encode_live_client_event(self, event: LiveClientEvent) -> list[dict[str, Any]]:
+ if isinstance(event, LiveClientAudioEvent):
+ return [{"type": "input_audio_buffer.append", "audio": event.data}]
+ if isinstance(event, LiveClientEndAudioEvent):
+ return [{"type": "input_audio_buffer.commit"}, {"type": "response.create"}]
+ if isinstance(event, LiveClientInterruptEvent):
+ return [{"type": "response.cancel"}]
+ if isinstance(event, LiveClientTextEvent):
+ return [
+ {"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_text", "text": event.text}]}},
+ {"type": "response.create"},
+ ]
+ if isinstance(event, LiveClientTurnEvent):
+ return [
+ {"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [part_to_openai_input(part) for part in event.parts]}},
+ {"type": "response.create"},
+ ] if event.turn_complete else [
+ {"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [part_to_openai_input(part) for part in event.parts]}},
+ ]
+ if isinstance(event, LiveClientImageEvent):
+ return [
+ {"type": "conversation.item.create", "item": {"type": "message", "role": "user", "content": [{"type": "input_image", "image_url": f"data:{event.media_type};base64,{event.data}"}]}},
+ {"type": "response.create"},
+ ]
+ if isinstance(event, LiveClientToolResultEvent):
+ output = parts_to_text(event.content, provider=self.provider, where="a Realtime function_call_output")
+ return [
+ {"type": "conversation.item.create", "item": {"type": "function_call_output", "call_id": event.id, "output": output}},
+ {"type": "response.create"},
+ ]
+ return []
+
+ def _decode_live_server_event(self, raw: str | bytes):
+ try:
+ payload = json.loads(raw.decode("utf-8") if isinstance(raw, bytes) else raw)
+ except Exception:
+ return []
+ if not isinstance(payload, dict):
+ return []
+ et = str(payload.get("type") or "")
+ events: list[Any] = []
+ # GA server event names verified live 2026-09-01
+ # (curl-fixtures/live-2026-09-01/); legacy beta names kept where
+ # harmless. Audio-native turns speak through
+ # `response.output_audio_transcript.delta` — mapped to text so
+ # transcripts arrive uniformly across providers.
+ if et in {"response.output_text.delta", "response.text.delta",
+ "response.output_audio_transcript.delta", "response.audio_transcript.delta"}:
+ delta = str(payload.get("delta") or payload.get("text") or "")
+ if delta:
+ events.append(LiveServerTextEvent(text=delta))
+ elif et == "response.output_audio.delta":
+ delta = str(payload.get("delta") or "")
+ if delta:
+ events.append(LiveServerAudioEvent(data=delta))
+ elif et == "response.function_call_arguments.delta":
+ delta = str(payload.get("delta") or "")
+ if delta:
+ events.append(LiveServerToolCallDeltaEvent(input_delta=delta, id=str(payload.get("call_id") or payload.get("id") or "") or None, name=str(payload.get("name") or "") or None))
+ elif et == "response.output_item.done":
+ # The ONLY tool-call emission point. `function_call_arguments.done`
+ # also carries the full call, but mapping both double-fires the
+ # event and double-sends tool results (observed live 2026-09-01:
+ # both frames arrive for one call).
+ item = payload.get("item", {}) if isinstance(payload.get("item"), dict) else {}
+ if item.get("type") == "function_call":
+ call_id = str(item.get("call_id") or item.get("id") or "")
+ if call_id:
+ events.append(LiveServerToolCallEvent(
+ id=call_id, name=str(item.get("name") or "tool"),
+ input=parse_json_object(item.get("arguments"))))
+ elif et in {"response.done", "response.completed"}:
+ response = payload.get("response", {}) if isinstance(payload.get("response"), dict) else {}
+ output = response.get("output") if isinstance(response.get("output"), list) else []
+ usage = _live_usage_from_response(response)
+ if str(response.get("status") or "") == "cancelled":
+ # GA signals barge-in via response.done status=cancelled
+ # (status_details.reason=client_cancelled); parallel to
+ # Gemini's interrupted frame. The cancelled response still
+ # consumed tokens (pinned: 143 in openai.live_interrupt); they
+ # ride a usage event before the interrupt signal, so the
+ # session's bill is the sum of usage + turn_end events.
+ if usage is not None:
+ events.append(LiveServerUsageEvent(usage=usage))
+ events.append(LiveServerInterruptedEvent())
+ elif any(isinstance(i, dict) and i.get("type") == "function_call" for i in output):
+ # A response that requests tool calls does NOT end the turn:
+ # the model is waiting for results, and the continuation
+ # arrives as a further wire response (observed live
+ # 2026-09-01). Gemini keeps the turn open here; emitting
+ # turn_end would break the shared tool-dispatch loop. Its
+ # tokens (pinned: 75 in openai.live_tools) ride a usage event.
+ if usage is not None:
+ events.append(LiveServerUsageEvent(usage=usage))
+ else:
+ events.append(LiveServerTurnEndEvent(usage=usage or Usage()))
+ elif et in {"response.cancelled", "response.canceled"}:
+ events.append(LiveServerInterruptedEvent())
+ elif et in {"error", "response.error"}:
+ err = payload.get("error")
+ if isinstance(err, dict):
+ provider_code = str(err.get("code") or err.get("type") or payload.get("code") or "provider")
+ message = str(err.get("message") or payload.get("message") or "")
+ else:
+ provider_code = str(payload.get("code") or payload.get("error_type") or "provider")
+ message = str(payload.get("message") or "")
+ if provider_code == "response_cancel_not_active":
+ # Benign barge-in race (captured live 2026-09-01): the
+ # response finished before the cancel arrived, or interrupt()
+ # was pressed twice. Gemini tolerates repeated interrupts;
+ # surfacing this as an error event breaks the parallel.
+ return events
+ events.append(LiveServerErrorEvent(error=self._error_detail(provider_code, message)))
+ return events
+
+ # ─── Other endpoints ────────────────────────────────────────────
+
+ def _models_request(self):
+ params = None
+ if self._codex:
+ # The Codex backend's /models requires a client_version query
+ # parameter (a Codex CLI release); the policy carries it.
+ params = {"client_version": self.access.backend_options.get("client_version", "")}
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/models",
+ params=params,
+ headers=self._headers(),
+ read_timeout=30.0,
+ )
+
+ def _models_from_body(self, body: str):
+ data = json.loads(body)
+ if self._codex:
+ # The Codex backend's usable model names are the `slug` values,
+ # and the list lives under "models" (not the OpenAI "data" envelope).
+ entries = data.get("models") if isinstance(data, dict) else None
+ return model_infos_from_entries(
+ entries, provider=self.provider, api_family="openai_responses", id_of=lambda entry: entry.get("slug"),
+ )
+ entries = data.get("data") if isinstance(data, dict) else None
+ return model_infos_from_entries(
+ entries,
+ provider=self.provider,
+ api_family="openai_responses",
+ id_of=lambda entry: entry.get("id"),
+ )
+
+ # ─── File hooks (Files API) ─────────────────────────────────
+ #
+ # Wire shapes verified live 2026-08-31 (curl-fixtures/files-2026-08-31/):
+ # multipart upload with a required `purpose` form field (an OpenAI
+ # storage classification, NOT part of the portable surface — lm15
+ # defaults to `user_data` per current OpenAI guidance and sets `batch`
+ # itself for batch inputs; extensions["purpose"] overrides). List
+ # pages with `after=<last id>` + `has_more`. Download is refused for
+ # some purposes (observed: 400 for user_data) — forwarded typed.
+
+ def _file_upload_request(self, request: FileUploadRequest) -> TransportRequest:
+ extensions = dict(request.extensions or {})
+ purpose = str(extensions.pop("purpose", "user_data"))
+ fields = [("purpose", purpose)] + [(k, str(v)) for k, v in extensions.items()]
+ content_type, body = multipart_form_body(
+ fields=fields,
+ files=[("file", request.filename, request.media_type, request.bytes)],
+ )
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/files",
+ headers=list(self._headers(content_type=content_type).items()),
+ body=body,
+ read_timeout=300.0,
+ )
+
+ def _file_info_from_body(self, body: str) -> FileInfo:
+ return self._file_info(json.loads(body))
+
+ def _file_info(self, data: dict[str, Any]) -> FileInfo:
+ file_id = data.get("id")
+ if not isinstance(file_id, str) or not file_id:
+ raise ProviderError("openai: file object carries no id", provider=self.provider)
+ readiness = openai_file_readiness(data.get("status")) # D6 fold table
+ filename = data.get("filename")
+ return FileInfo(
+ id=file_id,
+ filename=filename if isinstance(filename, str) and filename else None,
+ media_type=None, # OpenAI file metadata reports no MIME type
+ size_bytes=data.get("bytes") if isinstance(data.get("bytes"), int) else None,
+ created_at=iso_utc(data.get("created_at")),
+ expires_at=iso_utc(data.get("expires_at")),
+ readiness=readiness,
+ downloadable=None, # purpose-dependent policy, not reported per file
+ provider_data=data,
+ )
+
+ def _file_get_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_list_request(self, limit: int, cursor: str | None) -> TransportRequest:
+ params: dict[str, Any] = {"limit": limit}
+ if cursor is not None:
+ params["after"] = cursor
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files",
+ params=params, headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_page_from_list_body(self, body: str) -> FilePage:
+ data = json.loads(body)
+ entries = data.get("data") if isinstance(data.get("data"), list) else []
+ items = tuple(self._file_info(entry) for entry in entries if isinstance(entry, dict))
+ cursor = data.get("last_id") if data.get("has_more") and items else None
+ return FilePage(items=items, next_cursor=cursor if isinstance(cursor, str) and cursor else None)
+
+ def _file_delete_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="DELETE", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _file_download_request(self, file_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}/content",
+ headers=self._headers(), read_timeout=300.0,
+ )
+
+ # ─── Batch hooks (Batch API over /v1/responses) ──────────────────
+ #
+ # OpenAI batches are two-step: the requests travel as an uploaded JSONL
+ # file, then /batches references it. The file is wire syntax, not
+ # semantics — batch() owns the upload; the file id stays visible in
+ # provider_data. lm15 assigns positional custom_ids and re-sorts
+ # results so entry order always equals submission order.
+
+ def _batch_upload_request(self, request: BatchRequest) -> TransportRequest:
+ lines = []
+ for i, nested in enumerate(request.requests):
+ lines.append(json.dumps({
+ "custom_id": str(i),
+ "method": "POST",
+ "url": "/v1/responses",
+ "body": self._payload(nested, stream=False),
+ }, separators=(",", ":"), ensure_ascii=False))
+ data = ("\n".join(lines) + "\n").encode("utf-8")
+ content_type, body = multipart_form_body(
+ fields=[("purpose", "batch")],
+ files=[("file", "lm15-batch.jsonl", "application/jsonl", data)],
+ )
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/files",
+ headers=list(self._headers(content_type=content_type).items()),
+ body=body,
+ read_timeout=300.0,
+ )
+
+ def _batch_submit_request(self, request: BatchRequest, upload_body: dict[str, Any] | None) -> TransportRequest:
+ input_file_id = (upload_body or {}).get("id")
+ if not isinstance(input_file_id, str) or not input_file_id:
+ raise ProviderError("openai: batch input file upload returned no id", provider=self.provider)
+ extensions = dict(request.extensions or {})
+ payload: dict[str, Any] = {
+ "input_file_id": input_file_id,
+ "endpoint": extensions.pop("endpoint", "/v1/responses"),
+ "completion_window": extensions.pop("completion_window", "24h"),
+ }
+ if request.label is not None:
+ payload["metadata"] = {"label": request.label}
+ payload.update(extensions)
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/batches",
+ headers=self._headers(),
+ payload=payload,
+ read_timeout=120.0,
+ )
+
+ def _batch_job_from_body(self, body: str) -> BatchJobInfo:
+ return self._batch_job_info(json.loads(body))
+
+ def _batch_job_info(self, data: dict[str, Any]) -> BatchJobInfo:
+ batch_id = data.get("id")
+ if not isinstance(batch_id, str) or not batch_id:
+ raise ProviderError("openai: batch object carries no id", provider=self.provider)
+ metadata = data.get("metadata") if isinstance(data.get("metadata"), dict) else {}
+ label = metadata.get("label")
+ return BatchJobInfo(
+ id=batch_id,
+ status=_openai_batch_status(str(data.get("status") or "")),
+ label=label if isinstance(label, str) and label else None,
+ created_at=iso_utc(data.get("created_at")),
+ provider_data=data,
+ )
+
+ def _batch_status_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/batches/{path_id(batch_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _batch_cancel_request(self, batch_id: str) -> TransportRequest:
+ return self._emit(
+ method="POST", url=f"{self.base_url.rstrip('/')}/batches/{path_id(batch_id)}/cancel",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _batch_result_fetches(self, status_body: dict[str, Any]) -> tuple[TransportRequest, ...]:
+ fetches = []
+ for key in ("output_file_id", "error_file_id"):
+ file_id = status_body.get(key)
+ if isinstance(file_id, str) and file_id:
+ fetches.append(self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/files/{path_id(file_id)}/content",
+ headers=self._headers(), read_timeout=300.0,
+ ))
+ return tuple(fetches)
+
+ def _batch_entries(self, status_body: dict[str, Any], fetched: tuple[str, ...]) -> tuple[BatchEntry, ...]:
+ job_status = _openai_batch_status(str(status_body.get("status") or ""))
+ found: dict[int, BatchEntry] = {}
+ for text in fetched:
+ for line in text.splitlines():
+ if not line.strip():
+ continue
+ item = json.loads(line)
+ index = int(str(item.get("custom_id")))
+ response_obj = item.get("response") if isinstance(item.get("response"), dict) else {}
+ status_code = int(response_obj.get("status_code") or 0)
+ body_obj = response_obj.get("body") if isinstance(response_obj.get("body"), dict) else {}
+ if status_code == 200 and body_obj:
+ response = self.parse_response(
+ batch_entry_request(body_obj.get("model")), batch_entry_http(body_obj)
+ )
+ found[index] = BatchEntry(index=index, outcome="succeeded", response=response)
+ else:
+ err_source = body_obj or item.get("error") or {}
+ err = self.normalize_error(status_code or 400, json.dumps(err_source))
+ found[index] = BatchEntry(
+ index=index,
+ outcome="errored",
+ error=ErrorDetail(
+ code=canonical_error_code(err),
+ message=err.message or "batch entry errored",
+ provider_code=err.provider_code,
+ ),
+ )
+ # Entries the output files never mention (an expired or cancelled
+ # batch stops mid-flight): fill from the job's terminal status.
+ # Live edge (observed 2026-09-01): a batch cancelled during
+ # `validating` reports request_counts.total=0 — the provider never
+ # registered the requests — so results() is honestly EMPTY; lm15
+ # does not fabricate entries from the input file side-channel.
+ counts = status_body.get("request_counts") if isinstance(status_body.get("request_counts"), dict) else {}
+ total = int(counts.get("total") or 0) or (max(found) + 1 if found else 0)
+ fill: str = "expired" if job_status == "expired" else "cancelled" if job_status == "cancelled" else "errored"
+ entries = []
+ for index in range(total):
+ if index in found:
+ entries.append(found[index])
+ elif fill == "errored":
+ entries.append(BatchEntry(
+ index=index, outcome="errored",
+ error=ErrorDetail(code="provider", message="entry missing from batch output files"),
+ ))
+ else:
+ entries.append(BatchEntry(index=index, outcome=fill))
+ return tuple(entries)
+
+ def _batch_list_request(self, limit: int) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/batches",
+ params={"limit": int(limit)}, headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _batch_jobs_from_list_body(self, body: str) -> tuple[BatchJobInfo, ...]:
+ data = json.loads(body)
+ items = data.get("data") if isinstance(data, dict) else None
+ return tuple(self._batch_job_info(item) for item in (items or []) if isinstance(item, dict))
+
+ # ─── Video generation (Sora; captured live 2026-09-01) ──────────────
+ #
+ # Jobs at /v1/videos: submit -> {status: queued, progress}, poll ->
+ # in_progress -> completed, then /videos/{id}/content streams the MP4
+ # bytes (media type from the content-type header). The list endpoint
+ # is account-wide.
+
+ _VIDEO_STATUS_MAP: ClassVar[dict[str, str]] = {
+ "queued": "queued",
+ "in_progress": "running",
+ "completed": "completed",
+ "failed": "failed",
+ "cancelled": "cancelled",
+ }
+
+ def _video_submit_request(self, request: VideoGenerationRequest) -> TransportRequest:
+ if request.images:
+ # Sora's image input (input_reference) is a multipart upload; the
+ # mapping is unverified against the live wire, and Sora also
+ # constrains reference sizes. Raising beats shipping a guess.
+ raise UnsupportedFeatureError(
+ "openai: video input images (input_reference) are not mapped yet; "
+ "use the provider door until the mapping is live-receipted",
+ provider=self.provider,
+ )
+ payload: dict[str, Any] = {"model": request.model, "prompt": request.prompt, **(request.extensions or {})}
+ if request.seconds is not None:
+ payload["seconds"] = str(request.seconds) # the wire wants a string enum
+ return self._emit(method="POST", url=f"{self.base_url.rstrip('/')}/videos", headers=self._headers(), payload=payload, read_timeout=120.0)
+
+ def _video_job_from_body(self, body: str, video_id: "str | None" = None) -> VideoJobInfo:
+ return self._video_job_info(json.loads(body))
+
+ def _video_job_info(self, data: dict[str, Any]) -> VideoJobInfo:
+ video_id = data.get("id")
+ if not isinstance(video_id, str) or not video_id:
+ raise ProviderError("openai: video object carries no id", provider=self.provider)
+ wire_status = str(data.get("status") or "")
+ status = self._VIDEO_STATUS_MAP.get(wire_status)
+ if status is None:
+ raise ProviderError(f"openai: unknown video status {wire_status!r}", provider=self.provider)
+ progress = data.get("progress")
+ return VideoJobInfo(
+ id=video_id,
+ status=status,
+ progress=int(progress) if isinstance(progress, (int, float)) and not isinstance(progress, bool) else None,
+ created_at=iso_utc(data.get("created_at")),
+ model=data.get("model"),
+ provider_data=data,
+ )
+
+ def _video_status_request(self, video_id: str) -> TransportRequest:
+ return self._emit(method="GET", url=f"{self.base_url.rstrip('/')}/videos/{path_id(video_id)}", headers=self._headers(), read_timeout=60.0)
+
+ def _video_result_fetch(self, status_body: dict[str, Any]) -> TransportRequest:
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/videos/{path_id(str(status_body.get('id')))}/content",
+ headers=self._headers(),
+ read_timeout=600.0,
+ )
+
+ def _video_part(self, status_body: dict[str, Any], fetched: "HttpResponse | None") -> VideoPart:
+ if fetched is None:
+ raise ProviderError("openai: video content fetch is required", provider=self.provider)
+ content_type = (fetched.header("content-type") or "").split(";", 1)[0].strip()
+ if not content_type:
+ raise ProviderError("openai: video content carries no content-type", provider=self.provider)
+ return VideoPart(media_type=content_type, data=base64.b64encode(fetched.body).decode("ascii"))
+
+ def _video_list_request(self, limit: int, model: str | None) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/videos",
+ params={"limit": int(limit)}, headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _video_jobs_from_list_body(self, body: str) -> tuple[VideoJobInfo, ...]:
+ data = json.loads(body)
+ items = data.get("data") if isinstance(data, dict) else None
+ return tuple(self._video_job_info(item) for item in (items or []) if isinstance(item, dict))
+
+ # ─── Media generation (captured live 2026-09-01) ────────────────────
+ #
+ # Images: /images/generations (JSON) or, when input images are present,
+ # /images/edits (multipart) — verified honored by pixel check. The
+ # response states the format in `output_format`; the media type is read
+ # from the wire, never assumed. Usage carries real token counts.
+ # Speech: /audio/speech returns RAW BYTES; the media type lives in the
+ # content-type header (server default is audio/mpeg — lm15 injects no
+ # voice/format defaults of its own).
+
+ def _image_generate_request(self, request: ImageGenerationRequest) -> TransportRequest:
+ base = self.base_url.rstrip("/")
+ compat = resolve_openai_responses_compat(
+ base_url=self.base_url, model=request.model, profile=self.profile,
+ request_extensions=None, base=self._compat_base,
+ )
+ if not request.images:
+ payload = {"model": request.model, "prompt": request.prompt, "size": request.size, **(request.extensions or {})}
+ payload = {k: v for k, v in payload.items() if v is not None}
+ return self._emit(method="POST", url=f"{base}/images/generations", headers=self._headers(), payload=payload, read_timeout=300.0)
+ # Edits are multipart: the wire takes uploaded bytes only.
+ for part in request.images:
+ if part.data is None and part.path is None:
+ raise UnsupportedFeatureError(
+ "openai: image edits take inline data or a local path; "
+ "url/file_id-addressed input images have no wire slot",
+ provider=self.provider,
+ )
+ fields = [("model", str(request.model)), ("prompt", request.prompt)]
+ if request.size is not None:
+ fields.append(("size", request.size))
+ fields += [(k, str(v)) for k, v in (request.extensions or {}).items()]
+ # The multipart key is the server's: OpenAI takes `image[]`; Meta
+ # takes `image[0]`, `image[1]`, … (compat edit_image_field).
+ files = [
+ (f"image[{i}]" if compat.edit_image_field == "indexed" else "image[]", f"image-{i}", part.media_type, part.bytes)
+ for i, part in enumerate(request.images)
+ ]
+ content_type, body = multipart_form_body(fields=fields, files=files)
+ return self._emit(
+ method="POST",
+ url=f"{base}/images/edits",
+ headers=list(self._headers(content_type=content_type).items()),
+ body=body,
+ read_timeout=300.0,
+ )
+
+ def _image_generation_from_response(self, request: ImageGenerationRequest, resp: HttpResponse) -> ImageGenerationResponse:
+ data = resp.json()
+ output_format = data.get("output_format")
+ media_type = f"image/{output_format}" if isinstance(output_format, str) and output_format else None
+ images: list[ImagePart] = []
+ for item in data.get("data", []) or []:
+ if not isinstance(item, dict):
+ continue
+ if item.get("b64_json"):
+ images.append(ImagePart(media_type=media_type or "application/octet-stream", data=str(item["b64_json"])))
+ elif item.get("url"):
+ images.append(ImagePart(media_type=media_type or "application/octet-stream", url=str(item["url"])))
+ usage_obj = data.get("usage") if isinstance(data.get("usage"), dict) else {}
+ usage = Usage(
+ input_tokens=usage_obj.get("input_tokens"),
+ output_tokens=usage_obj.get("output_tokens"),
+ total_tokens=usage_obj.get("total_tokens"),
+ )
+ # Captured: the images response carries no id and no model echo.
+ return ImageGenerationResponse(images=tuple(images), usage=usage, provider_data=data)
+
+ def _speech_generate_request(self, request: SpeechGenerationRequest) -> TransportRequest:
+ payload: dict[str, Any] = {"model": request.model, "input": request.prompt, **(request.extensions or {})}
+ if request.voice is not None:
+ payload["voice"] = request.voice
+ if request.format is not None:
+ payload["response_format"] = request.format
+ return self._emit(method="POST", url=f"{self.base_url.rstrip('/')}/audio/speech", headers=self._headers(), payload=payload, read_timeout=300.0)
+
+ def _speech_generation_from_response(self, request: SpeechGenerationRequest, resp: HttpResponse) -> SpeechGenerationResponse:
+ content_type = (resp.header("content-type") or "").split(";", 1)[0].strip()
+ if not content_type:
+ raise ProviderError("openai: speech response carries no content-type", provider=self.provider)
+ audio = AudioPart(media_type=content_type, data=base64.b64encode(resp.body).decode("ascii"))
+ # The body is raw media: no usage, no id, no model echo exist.
+ return SpeechGenerationResponse(audio=audio, provider_data={"content_type": content_type})
diff --git a/dspy/_vendor/lm15/providers/openai_chat.py b/dspy/_vendor/lm15/providers/openai_chat.py
new file mode 100644
index 000000000..10f2b5db0
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/openai_chat.py
@@ -0,0 +1,1589 @@
+"""
+lm15.providers.openai_chat — OpenAI Chat Completions adapter.
+
+The Chat Completions dialect is the wire format spoken by OpenAI's legacy
+endpoint and by most OpenAI-compatible servers: ollama, Groq, OpenRouter,
+vLLM, SGLang, DeepSeek, and friends. Provider quirks are described by
+``OpenAIChatCompat`` policies (see lm15.compat); named presets bundle a
+policy with that server's default base URL.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+import json
+import mimetypes
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable, ClassVar, Iterator, Mapping
+
+from ..compat import (
+ OPENAI_CHAT_PRESET_BASE_URLS,
+ OpenAIChatCompat,
+ ResolvedOpenAIChatCompat,
+ resolve_openai_chat_compat,
+)
+from ..errors import ProviderError, ServerError, UnsupportedFeatureError
+from ..access import OPENAI_CHAT_API
+from ..features import ProviderManifest
+from ..sse import SSEEvent
+from ..transports import TransportRequest
+from ..types import (
+ BuiltinTool,
+ CacheConfig,
+ CitationPart,
+ Config,
+ FunctionTool,
+ ImagePart,
+ Message,
+ Part,
+ Reasoning,
+ RefusalPart,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ StreamEvent,
+ TextDelta,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ ToolCallDelta,
+ ToolCallPart,
+ ToolChoice,
+ ToolResultPart,
+ Usage,
+ audio,
+ document,
+ image,
+)
+from .base import BaseProviderLM, Credential, HttpResponse, SyncTransport, default_transport
+from .common import (
+ MEDIA_KINDS,
+ check_tool_result_media,
+ media_data_uri,
+ tool_result_error_text,
+ model_infos_from_entries,
+ openai_token_logprobs,
+ parse_json_object,
+ unnamed_tool_call_error,
+ parts_to_text,
+)
+from .openai import (
+ OpenAILM,
+ _attach_unmapped,
+ _breakpoint_unsupported,
+ _cache_breakpoint_index,
+ _cache_common_payload,
+ _cache_stable_prefix,
+ _record_unmapped,
+)
+
+_DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+# Canonical builtin tool name → Groq server-executed tool type (compat
+# builtin_tools="groq"; both verified live 2026-09-01: Groq runs them
+# server-side and reports the trace in message.executed_tools, which
+# stays in provider_data per MAP-1).
+_GROQ_BUILTIN_MAP: dict[str, str] = {
+ "web_search": "browser_search",
+ "code_execution": "code_interpreter",
+}
+
+_FINISH_REASON_MAP: dict[str, str] = {
+ "stop": "stop",
+ "length": "length",
+ "tool_calls": "tool_call",
+ "function_call": "tool_call",
+ "content_filter": "content_filter",
+}
+
+
+def _chat_image_block(part: Any, provider: str) -> dict[str, Any]:
+ """`{"type": "image_url", "image_url": {url, detail?}}`: a URL verbatim,
+ inline data or a path as a data URI. `file_id` has no slot on this wire."""
+ if part.file_id is not None:
+ raise UnsupportedFeatureError(
+ f"{provider}: an image addressed by file_id cannot be sent on the Chat Completions wire "
+ "(no file reference form); pass a URL or inline data", provider=provider,
+ )
+ payload: dict[str, Any] = {"url": part.url if part.url is not None else media_data_uri(part)}
+ if getattr(part, "detail", None):
+ payload["detail"] = part.detail
+ return {"type": "image_url", "image_url": payload}
+
+
+def _chat_content_parts(msg: Message, *, force_array: bool = False, provider: str = "openai-chat") -> str | list[dict[str, Any]]:
+ """Map non-assistant message parts to chat-completions content.
+
+ Single text part → plain string; anything multimodal → content array.
+ ``force_array`` keeps the array form for a lone text part (a cache
+ breakpoint rides on a text content block, never on a bare string).
+ A part the wire has no slot for RAISES (MAP-10); it is never rendered
+ as text or dropped.
+ """
+ parts = [p for p in msg.parts if not isinstance(p, (ToolCallPart, ToolResultPart))]
+ if len(parts) == 1 and isinstance(parts[0], TextPart) and not force_array:
+ return parts[0].text
+ out: list[dict[str, Any]] = []
+ for part in parts:
+ if isinstance(part, TextPart):
+ out.append({"type": "text", "text": part.text})
+ elif part.type == "image":
+ out.append(_chat_image_block(part, provider))
+ elif isinstance(part, ThinkingPart):
+ continue # thinking is never replayed as user content
+ elif part.type in MEDIA_KINDS:
+ raise UnsupportedFeatureError(
+ f"{provider}: a {part.type} part in a {msg.role} message has no slot on the Chat Completions wire "
+ "(text and image_url only); the OpenAI Responses, Anthropic and Gemini dialects carry it (MAP-10)",
+ provider=provider,
+ )
+ else:
+ out.append({"type": "text", "text": parts_to_text((part,), provider=provider)})
+ return out
+
+
+def _tool_row_content(provider: str, part: ToolResultPart, policy: str) -> str | list[dict[str, Any]]:
+ """A `role: tool` row's content (MAP-10): a string when text-only; on a
+ preset that proved the array form live, text and image_url blocks; a
+ media part the preset does not admit raises first. `is_error` rides
+ as an `[error] ` prefix (rule 5: the wire has no flag)."""
+ check_tool_result_media(provider, part, policy, wire="a Chat Completions tool row")
+ if all(p.type not in MEDIA_KINDS for p in part.content):
+ return tool_result_error_text(part, parts_to_text(part.content, provider=provider, where="a Chat Completions tool row"))
+ blocks: list[dict[str, Any]] = []
+ for p in part.content:
+ if p.type == "image":
+ blocks.append(_chat_image_block(p, provider))
+ else:
+ blocks.append({"type": "text", "text": parts_to_text((p,), provider=provider)})
+ if part.is_error:
+ first = next((b for b in blocks if b["type"] == "text"), None)
+ if first is None:
+ blocks.insert(0, {"type": "text", "text": "[error]"})
+ else:
+ first["text"] = "[error] " + first["text"]
+ return blocks
+
+
+def _response_format_to_chat(format_config: dict[str, Any]) -> dict[str, Any]:
+ """Canonical response_format (INV-050) -> chat-completions response_format."""
+ if format_config["type"] == "json_object":
+ return {"type": "json_object"}
+ inner: dict[str, Any] = {"name": format_config.get("name") or "response", "schema": format_config["schema"]}
+ if "strict" in format_config:
+ inner["strict"] = format_config["strict"]
+ return {"type": "json_schema", "json_schema": inner}
+
+
+# ─── Ingest: a Chat Completions request body → canonical Request (MAP-12) ──
+#
+# The decoder for the encoders above and for OpenAIChatLM._build_messages /
+# _payload below. It reads ONE preset's spellings (the same
+# ResolvedOpenAIChatCompat the builder writes with), so for every canonical
+# Request r that the builder can carry losslessly,
+# request_from_openai_chat(build(r)) == r; the lossy cells are enumerated in
+# docs/mapping-rules.md MAP-12 and pinned per case by the contract's `ingest`
+# direction. Every wire key has exactly one verdict
+# (lm15-contract/tools/openai-chat-ingest-verdicts.json): it maps to a
+# canonical field, it passes verbatim through config.extensions, it is
+# refused with UnsupportedFeatureError, or — for the four call-mode /
+# default-valued keys only — it is ignored by rule. A key with no verdict is
+# refused: lm15 never drops silently (port.md rule 4).
+#
+# Malformed input (a wrong JSON type, a missing required key, an unparsable
+# tool-call argument string) is a ValueError / TypeError, like serde.
+
+# Top-level keys forwarded verbatim into config.extensions: generation knobs
+# OpenAI documents that no canonical field expresses and that the builder
+# re-emits verbatim (payload.update(extensions)), so they round-trip.
+_INGEST_EXTENSIONS_KEYS: frozenset[str] = frozenset({
+ "seed", "logit_bias", "presence_penalty", "frequency_penalty", "metadata",
+ "verbosity", "moderation", "provider",
+})
+
+# Top-level keys refused with the reason a canonical Request cannot carry them.
+_INGEST_REFUSED_KEYS: dict[str, str] = {
+ "n": "lm15 reads one choice per response; n>1 would silently lose choices — fan out in the caller",
+ "functions": "the deprecated function-calling shape; declare tools with {type: function, function: {...}}",
+ "function_call": "the deprecated function-calling shape; use tool_choice",
+ "audio": "audio output parameters have no canonical slot on the chat surface",
+ "modalities": "output modality selection has no canonical slot on the chat surface",
+ "prediction": "predicted-output content has no canonical slot",
+ "web_search_options": "a server-executed search the chat dialect cannot map to parts (MAP-1); the Responses dialect carries web_search as a BuiltinTool",
+ "top_k": "the Chat Completions wire has no top_k (the builder raises on Config.top_k for the same reason); servers that take it do so through extensions",
+}
+
+# Call-mode keys: they say HOW the request is sent, not WHAT is asked. A
+# canonical Request has no stream flag (stream=... is an argument of
+# complete()/stream()), so these are read and dropped — the one place ingest
+# drops anything, stated in MAP-12.
+_INGEST_CALL_MODE_KEYS: frozenset[str] = frozenset({"stream", "stream_options"})
+
+# Keys the config decoder consumes itself (every other key is looked up in
+# the tables above, and an unlisted key is refused).
+_INGEST_CONFIG_KEYS: frozenset[str] = frozenset({
+ "model", "messages", "tools", "tool_choice", "parallel_tool_calls",
+ "max_completion_tokens", "max_tokens", "temperature", "top_p", "stop",
+ "logprobs", "top_logprobs", "response_format", "service_tier", "store",
+ "user", "safety_identifier", "user_id",
+ "reasoning_effort", "reasoning", "thinking", "enable_thinking", "chat_template_kwargs", "reasoning_format",
+ "prompt_cache_key", "prompt_cache_retention", "prompt_cache_options",
+})
+
+_INGEST_GROQ_BUILTIN_INVERSE: dict[str, str] = {wire: name for name, wire in _GROQ_BUILTIN_MAP.items()}
+
+_INGEST_AUDIO_MEDIA_TYPES: dict[str, str] = {"wav": "audio/wav", "mp3": "audio/mpeg"}
+
+
+def _ingest_unsupported(provider: str, what: str, why: str) -> UnsupportedFeatureError:
+ return UnsupportedFeatureError(f"{provider}: {what} cannot be carried by a canonical Request — {why}", provider=provider)
+
+
+def _ingest_str(value: Any, where: str) -> str:
+ if not isinstance(value, str):
+ raise TypeError(f"{where} must be a string, got {type(value).__name__}")
+ return value
+
+
+def _ingest_object(value: Any, where: str) -> dict[str, Any]:
+ if not isinstance(value, dict):
+ raise TypeError(f"{where} must be a JSON object, got {type(value).__name__}")
+ return value
+
+
+def _ingest_only_keys(provider: str, obj: Mapping[str, Any], allowed: frozenset[str], where: str) -> None:
+ """An unlisted key inside a block or object is a refusal, never a drop."""
+ extra = sorted(set(obj) - allowed)
+ if extra:
+ raise _ingest_unsupported(provider, f"{where} key {extra[0]!r}", "no canonical slot for it")
+
+
+def _ingest_data_uri(value: str, where: str) -> tuple[str, str]:
+ """``data:<media_type>;base64,<payload>`` → (media_type, payload). The
+ inverse of media_data_uri; anything else is malformed here."""
+ if not value.startswith("data:"):
+ raise ValueError(f"{where} must be a base64 data URI")
+ head, sep, payload = value[5:].partition(",")
+ if not sep or not head.endswith(";base64") or not payload:
+ raise ValueError(f"{where} must be a base64 data URI (data:<media-type>;base64,<payload>)")
+ media_type = head[: -len(";base64")]
+ if not media_type:
+ raise ValueError(f"{where} data URI has no media type")
+ return media_type, payload
+
+
+def _ingest_image_block(provider: str, block: Mapping[str, Any], where: str) -> ImagePart:
+ """Inverse of _chat_image_block. A data URI becomes inline data with the
+ URI's media type; any other URL stays a URL (media_type guessed from the
+ path, else the ImagePart default — the wire carries no type for a URL)."""
+ _ingest_only_keys(provider, block, frozenset({"type", "image_url", "prompt_cache_breakpoint"}), where)
+ spec = _ingest_object(block.get("image_url"), f"{where}.image_url")
+ _ingest_only_keys(provider, spec, frozenset({"url", "detail"}), f"{where}.image_url")
+ url = _ingest_str(spec.get("url"), f"{where}.image_url.url")
+ detail = spec.get("detail")
+ if url.startswith("data:"):
+ media_type, payload = _ingest_data_uri(url, f"{where}.image_url.url")
+ return image(data=payload, media_type=media_type, detail=detail)
+ guessed = mimetypes.guess_type(url)[0]
+ return image(url=url, media_type=guessed if guessed and guessed.startswith("image/") else None, detail=detail)
+
+
+def _ingest_text_block(provider: str, block: Mapping[str, Any], where: str) -> TextPart:
+ _ingest_only_keys(provider, block, frozenset({"type", "text", "prompt_cache_breakpoint"}), where)
+ return TextPart(text=_ingest_str(block.get("text"), f"{where}.text"))
+
+
+def _ingest_has_breakpoint(block: Mapping[str, Any], where: str) -> bool:
+ mark = block.get("prompt_cache_breakpoint")
+ if mark is None:
+ return False
+ mark = _ingest_object(mark, f"{where}.prompt_cache_breakpoint")
+ if mark != {"mode": "explicit"}:
+ raise ValueError(f"{where}.prompt_cache_breakpoint must be {{\"mode\": \"explicit\"}}")
+ if block.get("type") != "text":
+ # The builder places a mark on a text block only (CacheConfig table).
+ raise ValueError(f"{where}: a prompt_cache_breakpoint rides on a text block, not {block.get('type')!r}")
+ return True
+
+
+def _ingest_content_blocks(
+ provider: str, content: Any, *, role: str, where: str,
+) -> tuple[list[Part], bool]:
+ """A row's ``content`` → parts, plus whether its LAST block carries the
+ prompt-cache breakpoint. A string is one TextPart. Which block types a
+ role admits follows the wire's own schema (chat--create.md)."""
+ if isinstance(content, str):
+ return [TextPart(text=content)], False
+ if not isinstance(content, list):
+ raise TypeError(f"{where}.content must be a string or an array of content parts")
+ parts: list[Part] = []
+ breakpoint_at_end = False
+ for index, block in enumerate(content):
+ block = _ingest_object(block, f"{where}.content[{index}]")
+ block_where = f"{where}.content[{index}]"
+ kind = block.get("type")
+ marked = _ingest_has_breakpoint(block, block_where)
+ if marked and index != len(content) - 1:
+ raise ValueError(f"{block_where}: a prompt_cache_breakpoint marks the end of a message; it must be on the last block")
+ breakpoint_at_end = breakpoint_at_end or marked
+ if kind == "text":
+ parts.append(_ingest_text_block(provider, block, block_where))
+ elif kind == "image_url" and role in ("user", "tool"):
+ parts.append(_ingest_image_block(provider, block, block_where))
+ elif kind == "input_audio" and role == "user":
+ _ingest_only_keys(provider, block, frozenset({"type", "input_audio", "prompt_cache_breakpoint"}), block_where)
+ spec = _ingest_object(block.get("input_audio"), f"{block_where}.input_audio")
+ _ingest_only_keys(provider, spec, frozenset({"data", "format"}), f"{block_where}.input_audio")
+ fmt = _ingest_str(spec.get("format"), f"{block_where}.input_audio.format")
+ media_type = _INGEST_AUDIO_MEDIA_TYPES.get(fmt)
+ if media_type is None:
+ raise ValueError(f"{block_where}.input_audio.format must be one of {sorted(_INGEST_AUDIO_MEDIA_TYPES)}")
+ parts.append(audio(data=_ingest_str(spec.get("data"), f"{block_where}.input_audio.data"), media_type=media_type))
+ elif kind == "file" and role == "user":
+ _ingest_only_keys(provider, block, frozenset({"type", "file", "prompt_cache_breakpoint"}), block_where)
+ spec = _ingest_object(block.get("file"), f"{block_where}.file")
+ _ingest_only_keys(provider, spec, frozenset({"file_data", "file_id", "filename"}), f"{block_where}.file")
+ if spec.get("filename") is not None:
+ raise _ingest_unsupported(provider, f"{block_where}.file.filename", "DocumentPart has no filename slot")
+ if spec.get("file_id") is not None and spec.get("file_data") is None:
+ parts.append(document(file_id=_ingest_str(spec["file_id"], f"{block_where}.file.file_id")))
+ elif spec.get("file_data") is not None and spec.get("file_id") is None:
+ media_type, payload = _ingest_data_uri(_ingest_str(spec["file_data"], f"{block_where}.file.file_data"), f"{block_where}.file.file_data")
+ parts.append(document(data=payload, media_type=media_type))
+ else:
+ raise ValueError(f"{block_where}.file needs exactly one of file_data / file_id")
+ elif kind == "refusal" and role == "assistant":
+ _ingest_only_keys(provider, block, frozenset({"type", "refusal"}), block_where)
+ parts.append(RefusalPart(text=_ingest_str(block.get("refusal"), f"{block_where}.refusal")))
+ else:
+ raise _ingest_unsupported(
+ provider, f"{block_where} of type {kind!r} in a {role} message",
+ "no canonical part for that block on this wire (a part is not a knob: there is no extensions door for content)",
+ )
+ return parts, breakpoint_at_end
+
+
+# Assistant-row keys that are a client library's object model, not the wire
+# (litellm's ChatCompletionMessage dumped back into history). Their null or
+# empty form carries nothing and reads as absent; a non-empty one is refused.
+_INGEST_CLIENT_OBJECT_KEYS: frozenset[str] = frozenset({"provider_specific_fields", "thinking_blocks", "images"})
+
+
+def _ingest_all_empty(value: Any) -> bool:
+ """A dict whose every value is null/empty (litellm: {"refusal": null})."""
+ return isinstance(value, dict) and all(v is None or v == [] or v == {} for v in value.values())
+
+
+def _ingest_annotations(provider: str, raw: Any, content_text: str | None, where: str) -> list[CitationPart]:
+ """OpenAI's assistant ``annotations`` (url_citation entries with a span
+ into the content) → CitationParts; an empty list is nothing."""
+ if not isinstance(raw, list):
+ raise TypeError(f"{where}.annotations must be an array")
+ out: list[CitationPart] = []
+ for index, entry in enumerate(raw):
+ entry_where = f"{where}.annotations[{index}]"
+ entry = _ingest_object(entry, entry_where)
+ if entry.get("type") != "url_citation":
+ raise _ingest_unsupported(provider, f"{entry_where} of type {entry.get('type')!r}", "only url_citation annotations have a canonical part (CitationPart)")
+ _ingest_only_keys(provider, entry, frozenset({"type", "url_citation"}), entry_where)
+ spec = _ingest_object(entry.get("url_citation"), f"{entry_where}.url_citation")
+ _ingest_only_keys(provider, spec, frozenset({"url", "title", "start_index", "end_index"}), f"{entry_where}.url_citation")
+ text: str | None = None
+ start, end = spec.get("start_index"), spec.get("end_index")
+ if content_text is not None and isinstance(start, int) and isinstance(end, int) and 0 <= start <= end <= len(content_text):
+ text = content_text[start:end] or None
+ out.append(CitationPart(
+ url=_ingest_str(spec.get("url"), f"{entry_where}.url_citation.url"),
+ title=_ingest_str(spec["title"], f"{entry_where}.url_citation.title") if spec.get("title") is not None else None,
+ text=text,
+ ))
+ return out
+
+
+def _ingest_tool_calls(provider: str, calls: Any, where: str) -> list[ToolCallPart]:
+ if not isinstance(calls, list):
+ raise TypeError(f"{where}.tool_calls must be an array")
+ out: list[ToolCallPart] = []
+ for index, call in enumerate(calls):
+ call = _ingest_object(call, f"{where}.tool_calls[{index}]")
+ call_where = f"{where}.tool_calls[{index}]"
+ kind = call.get("type", "function")
+ if kind != "function":
+ raise _ingest_unsupported(provider, f"{call_where} of type {kind!r}", "only function tool calls have a canonical part")
+ _ingest_only_keys(provider, call, frozenset({"id", "type", "function"}), call_where)
+ function = _ingest_object(call.get("function"), f"{call_where}.function")
+ _ingest_only_keys(provider, function, frozenset({"name", "arguments"}), f"{call_where}.function")
+ arguments = function.get("arguments", "{}")
+ if isinstance(arguments, str):
+ # The builder writes json.dumps(input); the inverse is exact, and
+ # a caller-authored string that is not a JSON object is malformed
+ # (the lenient parse_json_object is for PROVIDER output only).
+ try:
+ parsed = json.loads(arguments) if arguments else {}
+ except ValueError as exc:
+ raise ValueError(f"{call_where}.function.arguments is not JSON: {exc}") from None
+ else:
+ parsed = arguments
+ if not isinstance(parsed, dict):
+ raise ValueError(f"{call_where}.function.arguments must encode a JSON object")
+ out.append(ToolCallPart(
+ id=_ingest_str(call.get("id"), f"{call_where}.id"),
+ name=_ingest_str(function.get("name"), f"{call_where}.function.name"),
+ input=parsed,
+ ))
+ return out
+
+
+def _ingest_messages(
+ provider: str, rows: Any, compat: ResolvedOpenAIChatCompat,
+) -> tuple[str | tuple[Part, ...] | None, list[Message], bool, int | None]:
+ """Wire rows → (system, messages, system_breakpoint, breakpoint_message_index).
+
+ Rules (MAP-12): the first row, when system/developer, is Request.system
+ (the builder renders system there under compat.instruction_role, so the
+ wire cannot tell a system prompt from a leading developer message);
+ a later system/developer row is a developer Message; consecutive tool
+ rows form one tool Message (the builder emits one row per result part);
+ a `name` on any row is refused (no canonical slot)."""
+ if not isinstance(rows, list):
+ raise TypeError("messages must be an array")
+ system: str | tuple[Part, ...] | None = None
+ system_breakpoint = False
+ breakpoint_index: int | None = None
+ messages: list[Message] = []
+ pending_results: list[ToolResultPart] = []
+
+ def flush_results() -> None:
+ if pending_results:
+ messages.append(Message(role="tool", parts=tuple(pending_results)))
+ pending_results.clear()
+
+ for index, row in enumerate(rows):
+ row = _ingest_object(row, f"messages[{index}]")
+ where = f"messages[{index}]"
+ role = row.get("role")
+ if row.get("name") is not None and role != "tool":
+ raise _ingest_unsupported(provider, f"{where}.name", "a per-message participant name has no canonical slot")
+
+ if role in ("system", "developer"):
+ flush_results()
+ _ingest_only_keys(provider, row, frozenset({"role", "content"}), where)
+ parts, marked = _ingest_content_blocks(provider, row.get("content"), role="system", where=where)
+ if index == 0:
+ if marked:
+ system_breakpoint = True
+ if len(parts) == 1 and isinstance(parts[0], TextPart):
+ system = parts[0].text
+ else:
+ system = tuple(parts)
+ else:
+ if marked:
+ breakpoint_index = len(messages)
+ messages.append(Message(role="developer", parts=tuple(parts)))
+ continue
+
+ if role == "user":
+ flush_results()
+ _ingest_only_keys(provider, row, frozenset({"role", "content", "name"}), where)
+ parts, marked = _ingest_content_blocks(provider, row.get("content"), role="user", where=where)
+ if marked:
+ if breakpoint_index is not None or system_breakpoint:
+ raise ValueError(f"{where}: a request carries at most one prompt_cache_breakpoint")
+ breakpoint_index = len(messages)
+ messages.append(Message(role="user", parts=tuple(parts)))
+ continue
+
+ if role == "assistant":
+ flush_results()
+ _ingest_only_keys(
+ provider, row,
+ frozenset({"role", "content", "tool_calls", "refusal", "reasoning_content", "name", "audio", "function_call",
+ "annotations", *_INGEST_CLIENT_OBJECT_KEYS}),
+ where,
+ )
+ if row.get("audio") is not None:
+ raise _ingest_unsupported(provider, f"{where}.audio", "an assistant audio reference has no canonical part")
+ if row.get("function_call") is not None:
+ raise _ingest_unsupported(provider, f"{where}.function_call", "the deprecated function-calling shape; use tool_calls")
+ for key in _INGEST_CLIENT_OBJECT_KEYS:
+ # A client library's object model (litellm) dumped into history:
+ # null or empty carries nothing; anything else has no mapping.
+ value = row.get(key)
+ if value is not None and value != [] and value != {} and not _ingest_all_empty(value):
+ raise _ingest_unsupported(provider, f"{where}.{key}", "a client library's own field with no canonical part; only its empty form reads as absent")
+ parts: list[Part] = []
+ reasoning_text = row.get("reasoning_content")
+ if reasoning_text is not None:
+ parts.append(ThinkingPart(text=_ingest_str(reasoning_text, f"{where}.reasoning_content")))
+ content = row.get("content")
+ if content is not None:
+ text_parts, marked = _ingest_content_blocks(provider, content, role="assistant", where=where)
+ if marked:
+ raise ValueError(f"{where}: a prompt_cache_breakpoint cannot mark an assistant message (the builder refuses the same cell)")
+ parts.extend(text_parts)
+ refusal_text = row.get("refusal")
+ if refusal_text is not None:
+ parts.append(RefusalPart(text=_ingest_str(refusal_text, f"{where}.refusal")))
+ if row.get("tool_calls") is not None:
+ parts.extend(_ingest_tool_calls(provider, row["tool_calls"], where))
+ if row.get("annotations") is not None:
+ parts.extend(_ingest_annotations(provider, row["annotations"], content if isinstance(content, str) else None, where))
+ if not parts:
+ parts.append(TextPart(text="")) # the never-empty rule (MAP-2), applied to history
+ messages.append(Message(role="assistant", parts=tuple(parts)))
+ continue
+
+ if role == "tool":
+ _ingest_only_keys(provider, row, frozenset({"role", "content", "tool_call_id", "name"}), where)
+ parts, marked = _ingest_content_blocks(provider, row.get("content"), role="tool", where=where)
+ if marked:
+ raise ValueError(f"{where}: a prompt_cache_breakpoint cannot mark a tool message (the builder refuses the same cell)")
+ name = row.get("name")
+ pending_results.append(ToolResultPart(
+ id=_ingest_str(row.get("tool_call_id"), f"{where}.tool_call_id"),
+ content=tuple(parts),
+ name=_ingest_str(name, f"{where}.name") if name is not None else None,
+ ))
+ continue
+
+ if role == "function":
+ raise _ingest_unsupported(provider, f"{where} with role 'function'", "the deprecated function-calling shape; use a tool row with tool_call_id")
+ raise ValueError(f"{where}.role must be one of system, developer, user, assistant, tool; got {role!r}")
+
+ flush_results()
+ return system, messages, system_breakpoint, breakpoint_index
+
+
+def _ingest_tools(provider: str, raw: Any, compat: ResolvedOpenAIChatCompat) -> list[FunctionTool | BuiltinTool]:
+ if raw is None:
+ return []
+ if not isinstance(raw, list):
+ raise TypeError("tools must be an array")
+ tools: list[FunctionTool | BuiltinTool] = []
+ for index, entry in enumerate(raw):
+ entry = _ingest_object(entry, f"tools[{index}]")
+ where = f"tools[{index}]"
+ kind = entry.get("type")
+ if kind == "function":
+ _ingest_only_keys(provider, entry, frozenset({"type", "function"}), where)
+ function = _ingest_object(entry.get("function"), f"{where}.function")
+ _ingest_only_keys(provider, function, frozenset({"name", "description", "parameters", "strict"}), f"{where}.function")
+ if function.get("strict") is True:
+ # A per-tool strict flag has no canonical slot; dropping it
+ # would lose an enforcement the caller asked for. `false` is
+ # the wire default and carries nothing.
+ raise _ingest_unsupported(provider, f"{where}.function.strict = true", "no per-tool strict slot (compat.strict_tools is a preset policy)")
+ kwargs: dict[str, Any] = {"name": _ingest_str(function.get("name"), f"{where}.function.name")}
+ if function.get("description") is not None:
+ kwargs["description"] = _ingest_str(function["description"], f"{where}.function.description")
+ if function.get("parameters") is not None:
+ kwargs["parameters"] = _ingest_object(function["parameters"], f"{where}.function.parameters")
+ tools.append(FunctionTool(**kwargs))
+ elif kind in _INGEST_GROQ_BUILTIN_INVERSE and compat.builtin_tools == "groq":
+ config = {k: v for k, v in entry.items() if k != "type"}
+ tools.append(BuiltinTool(name=_INGEST_GROQ_BUILTIN_INVERSE[kind], config=config or None))
+ else:
+ raise _ingest_unsupported(provider, f"{where} of type {kind!r}", "only function tools (and, on the groq preset, its server-executed tools) have a canonical form")
+ return tools
+
+
+def _ingest_tool_choice(provider: str, raw: Any, parallel: Any) -> ToolChoice | None:
+ """Inverse of OpenAIChatLM._tool_choice_payload plus parallel_tool_calls."""
+ mode: str | None = None
+ allowed: tuple[str, ...] = ()
+ if raw is not None:
+ if raw in ("none", "auto", "required"):
+ mode = str(raw)
+ elif isinstance(raw, dict):
+ kind = raw.get("type")
+ if kind == "function":
+ _ingest_only_keys(provider, raw, frozenset({"type", "function"}), "tool_choice")
+ function = _ingest_object(raw.get("function"), "tool_choice.function")
+ _ingest_only_keys(provider, function, frozenset({"name"}), "tool_choice.function")
+ mode, allowed = "required", (_ingest_str(function.get("name"), "tool_choice.function.name"),)
+ elif kind == "allowed_tools":
+ _ingest_only_keys(provider, raw, frozenset({"type", "allowed_tools"}), "tool_choice")
+ spec = _ingest_object(raw.get("allowed_tools"), "tool_choice.allowed_tools")
+ _ingest_only_keys(provider, spec, frozenset({"mode", "tools"}), "tool_choice.allowed_tools")
+ mode = _ingest_str(spec.get("mode"), "tool_choice.allowed_tools.mode")
+ entries = spec.get("tools")
+ if not isinstance(entries, list) or not entries:
+ raise ValueError("tool_choice.allowed_tools.tools must be a non-empty array")
+ names: list[str] = []
+ for index, entry in enumerate(entries):
+ entry = _ingest_object(entry, f"tool_choice.allowed_tools.tools[{index}]")
+ if entry.get("type") != "function":
+ raise _ingest_unsupported(provider, f"tool_choice.allowed_tools.tools[{index}] of type {entry.get('type')!r}", "only function tools can be allowed on this wire")
+ function = _ingest_object(entry.get("function"), f"tool_choice.allowed_tools.tools[{index}].function")
+ names.append(_ingest_str(function.get("name"), f"tool_choice.allowed_tools.tools[{index}].function.name"))
+ allowed = tuple(names)
+ elif kind == "custom":
+ raise _ingest_unsupported(provider, "tool_choice of type 'custom'", "custom tools have no canonical form")
+ else:
+ raise ValueError(f"tool_choice.type must be function or allowed_tools; got {kind!r}")
+ else:
+ raise ValueError("tool_choice must be none, auto, required, or an object")
+ if parallel is not None and not isinstance(parallel, bool):
+ raise TypeError("parallel_tool_calls must be a boolean")
+ if mode is None and parallel is None:
+ return None
+ return ToolChoice(mode=mode or "auto", allowed=allowed, parallel=parallel)
+
+
+def _ingest_response_format(provider: str, raw: Any) -> dict[str, Any] | None:
+ """Inverse of _response_format_to_chat (INV-050 shapes). ``{type: text}``
+ is the wire default and reads as absent. A ``name`` of exactly
+ "response" is the builder's default label for an unnamed schema, so it
+ reads as absent too: the wire bytes are identical either way."""
+ raw = _ingest_object(raw, "response_format")
+ kind = raw.get("type")
+ if kind == "text":
+ _ingest_only_keys(provider, raw, frozenset({"type"}), "response_format")
+ return None
+ if kind == "json_object":
+ _ingest_only_keys(provider, raw, frozenset({"type"}), "response_format")
+ return {"type": "json_object"}
+ if kind == "json_schema":
+ _ingest_only_keys(provider, raw, frozenset({"type", "json_schema"}), "response_format")
+ inner = _ingest_object(raw.get("json_schema"), "response_format.json_schema")
+ _ingest_only_keys(provider, inner, frozenset({"name", "schema", "strict", "description"}), "response_format.json_schema")
+ if inner.get("description") is not None:
+ raise _ingest_unsupported(provider, "response_format.json_schema.description", "the canonical response_format has no description slot (INV-050)")
+ out: dict[str, Any] = {"type": "json_schema", "schema": _ingest_object(inner.get("schema"), "response_format.json_schema.schema")}
+ name = inner.get("name")
+ if name is not None and name != "response":
+ out["name"] = _ingest_str(name, "response_format.json_schema.name")
+ if inner.get("strict") is not None:
+ if not isinstance(inner["strict"], bool):
+ raise TypeError("response_format.json_schema.strict must be a boolean")
+ out["strict"] = inner["strict"]
+ return out
+ raise ValueError(f"response_format.type must be text, json_object or json_schema; got {kind!r}")
+
+
+def _ingest_reasoning(provider: str, body: Mapping[str, Any], compat: ResolvedOpenAIChatCompat) -> tuple[Reasoning | None, dict[str, Any]]:
+ """Inverse of the reasoning block of _payload for THIS preset's
+ thinking_format (MAP-7 spellings). Returns the Reasoning and any
+ extensions entries the spelling implies (groq's `reasoning_format`
+ alone is the documented extensions door)."""
+ fmt = compat.thinking_format
+ present = {k for k in ("reasoning_effort", "reasoning", "thinking", "enable_thinking", "chat_template_kwargs", "reasoning_format") if k in body}
+ if not present:
+ return None, {}
+ spelled_by = {
+ "reasoning_effort": {"reasoning_effort"},
+ "openrouter": {"reasoning"},
+ "deepseek": {"thinking", "reasoning_effort"},
+ "kimi": {"thinking", "reasoning_effort"},
+ "qwen": {"enable_thinking"},
+ "qwen_chat_template": {"chat_template_kwargs"},
+ "none": set(),
+ }[fmt]
+ if compat.builtin_tools == "groq":
+ spelled_by = spelled_by | {"reasoning_format"}
+ foreign = sorted(present - spelled_by)
+ if foreign:
+ raise _ingest_unsupported(
+ provider, f"{foreign[0]!r}",
+ f"this server's reasoning dial is spelled {sorted(spelled_by) or 'nowhere (no dial)'}; another server's spelling would be sent and ignored",
+ )
+ extensions: dict[str, Any] = {}
+ effort: str | None = None
+ off = False
+
+ if "reasoning_effort" in present:
+ word = _ingest_str(body["reasoning_effort"], "reasoning_effort")
+ if word == "none":
+ off = True
+ else:
+ effort = word
+ if "thinking" in present:
+ spec = _ingest_object(body["thinking"], "thinking")
+ _ingest_only_keys(provider, spec, frozenset({"type"}), "thinking")
+ if spec.get("type") == "disabled":
+ if effort is not None:
+ raise ValueError("thinking.type=disabled next to a reasoning_effort level is contradictory")
+ off = True
+ elif spec.get("type") == "enabled":
+ if effort is None and not off:
+ raise _ingest_unsupported(provider, "thinking.type=enabled without reasoning_effort", "lm15's dial is a level (MAP-7); set config.reasoning with an effort word")
+ else:
+ raise ValueError(f"thinking.type must be enabled or disabled; got {spec.get('type')!r}")
+ if "reasoning" in present:
+ spec = _ingest_object(body["reasoning"], "reasoning")
+ _ingest_only_keys(provider, spec, frozenset({"effort", "enabled"}), "reasoning")
+ if spec.get("enabled") is False:
+ off = True
+ elif spec.get("effort") is not None:
+ effort = _ingest_str(spec["effort"], "reasoning.effort")
+ else:
+ raise ValueError("reasoning must carry effort or enabled: false")
+ if "enable_thinking" in present:
+ flag = body["enable_thinking"]
+ if flag is False:
+ off = True
+ elif flag is True:
+ raise _ingest_unsupported(provider, "enable_thinking = true", "this wire has no effort level; lm15's dial is a level (MAP-7) — set config.reasoning yourself")
+ else:
+ raise TypeError("enable_thinking must be a boolean")
+ if "chat_template_kwargs" in present:
+ spec = _ingest_object(body["chat_template_kwargs"], "chat_template_kwargs")
+ _ingest_only_keys(provider, spec, frozenset({"enable_thinking", "preserve_thinking"}), "chat_template_kwargs")
+ if spec.get("enable_thinking") is False:
+ off = True
+ elif spec.get("enable_thinking") is True:
+ raise _ingest_unsupported(provider, "chat_template_kwargs.enable_thinking = true", "this wire has no effort level; lm15's dial is a level (MAP-7) — set config.reasoning yourself")
+ else:
+ raise TypeError("chat_template_kwargs.enable_thinking must be a boolean")
+
+ summary: str | None = None
+ if "reasoning_format" in present:
+ value = body["reasoning_format"]
+ if value != "parsed":
+ raise _ingest_unsupported(provider, f"reasoning_format = {value!r}", "only 'parsed' maps (Reasoning.summary='auto', MAP-7 rule 7)")
+ if effort is None:
+ # The documented door: extensions={"reasoning_format": "parsed"}
+ # with reasoning absent (the Qwen dial has no levels).
+ extensions["reasoning_format"] = value
+ else:
+ summary = "auto"
+
+ if off:
+ return Reasoning(effort="off"), extensions
+ if effort is None:
+ return None, extensions
+ return Reasoning(effort=effort, summary=summary), extensions
+
+
+def _ingest_cache(
+ provider: str, body: Mapping[str, Any], compat: ResolvedOpenAIChatCompat,
+ *, system_breakpoint: bool, breakpoint_index: int | None,
+) -> CacheConfig | None:
+ """Inverse of _cache_common_payload and the breakpoint placement (MAP-6
+ on the OpenAI classes). Under a preset with no OpenAI cache control the
+ keys are refused: the server has no such field."""
+ keys = {k for k in ("prompt_cache_key", "prompt_cache_retention", "prompt_cache_options") if k in body}
+ marked = system_breakpoint or breakpoint_index is not None
+ if not keys and not marked:
+ return None
+ if compat.cache_control not in ("openai", "openai_implicit"):
+ what = sorted(keys)[0] if keys else "prompt_cache_breakpoint"
+ raise _ingest_unsupported(provider, f"{what!r}", "this server has no OpenAI prompt-cache control (compat.cache_control)")
+ if marked and compat.cache_control != "openai":
+ raise _ingest_unsupported(provider, "prompt_cache_breakpoint", "this server swallows an explicit breakpoint silently (compat.cache_control=openai_implicit)")
+ key = body.get("prompt_cache_key")
+ retention = None
+ if "prompt_cache_retention" in body:
+ if body["prompt_cache_retention"] != "24h":
+ raise _ingest_unsupported(provider, f"prompt_cache_retention = {body['prompt_cache_retention']!r}", "only '24h' has a canonical value (CacheConfig.retention='long')")
+ retention = "long"
+ explicit = False
+ if "prompt_cache_options" in body:
+ spec = _ingest_object(body["prompt_cache_options"], "prompt_cache_options")
+ _ingest_only_keys(provider, spec, frozenset({"mode", "ttl"}), "prompt_cache_options")
+ if spec.get("ttl") is not None:
+ raise _ingest_unsupported(provider, "prompt_cache_options.ttl", "CacheConfig.retention names 24h only")
+ if spec.get("mode") == "explicit":
+ explicit = True
+ elif spec.get("mode") == "implicit":
+ raise _ingest_unsupported(provider, "prompt_cache_options.mode = 'implicit'", "the server default; a canonical CacheConfig names auto or off")
+ else:
+ raise ValueError(f"prompt_cache_options.mode must be explicit or implicit; got {spec.get('mode')!r}")
+ if explicit and not marked:
+ # Explicit mode with no mark is the cache-WRITE off switch (MAP-6 rule 2).
+ if key is not None or retention is not None:
+ raise ValueError("prompt_cache_options.mode=explicit with no breakpoint is the off switch; it cannot carry a key or retention (INV-027)")
+ return CacheConfig(mode="off")
+ if system_breakpoint:
+ return CacheConfig(prefix="stable", key=key, retention=retention)
+ if breakpoint_index is not None:
+ return CacheConfig(prefix_until_index=breakpoint_index, key=key, retention=retention)
+ return CacheConfig(key=key, retention=retention)
+
+
+def _ingest_config(
+ provider: str, body: Mapping[str, Any], compat: ResolvedOpenAIChatCompat,
+ *, system_breakpoint: bool, breakpoint_index: int | None,
+) -> Config:
+ kwargs: dict[str, Any] = {}
+ if "max_completion_tokens" in body or "max_tokens" in body:
+ values = {k: body[k] for k in ("max_completion_tokens", "max_tokens") if k in body}
+ if len(set(map(repr, values.values()))) > 1:
+ raise ValueError(f"max_tokens and max_completion_tokens disagree: {values}")
+ kwargs["max_tokens"] = next(iter(values.values()))
+ for key in ("temperature", "top_p", "service_tier", "store"):
+ if key in body:
+ kwargs[key] = body[key]
+ if "stop" in body:
+ kwargs["stop"] = body["stop"]
+ if body.get("logprobs") is True:
+ top = body.get("top_logprobs", 0)
+ kwargs["logprobs"] = top
+ elif body.get("logprobs") not in (None, False):
+ raise TypeError("logprobs must be a boolean")
+ elif "top_logprobs" in body:
+ raise ValueError("top_logprobs requires logprobs: true")
+ if "response_format" in body:
+ kwargs["response_format"] = _ingest_response_format(provider, body["response_format"])
+ kwargs["tool_choice"] = _ingest_tool_choice(provider, body.get("tool_choice"), body.get("parallel_tool_calls"))
+
+ user_keys = [k for k in ("user", "safety_identifier", "user_id") if k in body]
+ if "user_id" in user_keys and compat.user_field != "user_id":
+ raise _ingest_unsupported(provider, "'user_id'", f"this server spells the end-user field {compat.user_field!r}")
+ if len(user_keys) > 1:
+ raise ValueError(f"one end-user identifier only; got {user_keys}")
+ if user_keys:
+ kwargs["user_id"] = body[user_keys[0]]
+
+ reasoning, extensions = _ingest_reasoning(provider, body, compat)
+ kwargs["reasoning"] = reasoning
+ kwargs["cache"] = _ingest_cache(provider, body, compat, system_breakpoint=system_breakpoint, breakpoint_index=breakpoint_index)
+ for key in body:
+ if key in _INGEST_EXTENSIONS_KEYS:
+ extensions[key] = body[key]
+ kwargs["extensions"] = extensions or None
+ return Config(**kwargs)
+
+
+def _ingest_openai_chat(provider: str, body: Mapping[str, Any], compat: ResolvedOpenAIChatCompat) -> Request:
+ if not isinstance(body, Mapping):
+ raise TypeError(f"a Chat Completions request body is a JSON object, got {type(body).__name__}")
+ for key in body:
+ if key in _INGEST_REFUSED_KEYS:
+ raise _ingest_unsupported(provider, f"{key!r}", _INGEST_REFUSED_KEYS[key])
+ if key not in _INGEST_CONFIG_KEYS and key not in _INGEST_EXTENSIONS_KEYS and key not in _INGEST_CALL_MODE_KEYS:
+ raise _ingest_unsupported(provider, f"{key!r}", "no verdict for this key (lm15-contract/tools/openai-chat-ingest-verdicts.json); lm15 never drops a key silently")
+ model = body.get("model")
+ if not isinstance(model, str) or not model:
+ raise ValueError("model must be a non-empty string")
+ if "messages" not in body:
+ raise ValueError("messages is required")
+ system, messages, system_breakpoint, breakpoint_index = _ingest_messages(provider, body["messages"], compat)
+ tools = _ingest_tools(provider, body.get("tools"), compat)
+ config = _ingest_config(provider, body, compat, system_breakpoint=system_breakpoint, breakpoint_index=breakpoint_index)
+ return Request(model=model, messages=tuple(messages), system=system, tools=tuple(tools), config=config)
+
+
+def request_from_openai_chat(body: Mapping[str, Any], *, compat: OpenAIChatCompat | str | None = None) -> Request:
+ """A Chat Completions request body → the canonical :class:`Request` (MAP-12).
+
+ ``body`` is the JSON object a client would POST to ``/chat/completions``
+ (``model``, ``messages``, ``tools``, generation knobs). ``compat`` names
+ the server dialect whose spellings are read — a preset name
+ (``"openai"``, ``"groq"``, ``"deepseek"``, …), an
+ :class:`OpenAIChatCompat`, or None for OpenAI's own — the same policy
+ :class:`OpenAIChatLM` writes with, so what that adapter emits for a
+ Request reads back as that Request wherever the wire can carry it.
+
+ Every key has one verdict: it maps to a canonical field, it passes
+ verbatim through ``config.extensions`` (``seed``, ``logit_bias``,
+ ``presence_penalty``, ``frequency_penalty``, ``metadata``, …), or it is
+ refused with :class:`UnsupportedFeatureError` naming the key (``n``,
+ the deprecated ``functions`` shape, a content block with no part, a
+ spelling another server owns). ``stream`` / ``stream_options`` are
+ call-mode keys with no place on a Request and are read and dropped.
+ Malformed input raises ``ValueError`` / ``TypeError``.
+
+ On the adapter, ``lm.request_from_openai_chat(body)`` is the same
+ function under that adapter's compat, including its per-model overrides.
+ """
+ if isinstance(compat, str):
+ partial = OpenAIChatCompat.preset(compat)
+ elif isinstance(compat, OpenAIChatCompat):
+ partial = compat
+ elif compat is None:
+ partial = OpenAIChatCompat()
+ else:
+ raise TypeError("compat must be a preset name, an OpenAIChatCompat, or None")
+ model = body.get("model") if isinstance(body, Mapping) else None
+ resolved = resolve_openai_chat_compat(partial.for_model(model) if isinstance(model, str) else partial)
+ return _ingest_openai_chat("openai-chat", body, resolved)
+
+
+def _response_from_chat_body(
+ provider: str, data: Any, *, model: str | None, choice: int | None,
+ on_error: Callable[[str, str], ProviderError],
+) -> Response:
+ """The one Chat Completions response reader: ``parse_response`` for
+ provider traffic and :func:`response_from_openai_chat` for a foreign
+ dict share it. ``choice`` names the choice to read; ``None`` means
+ "the only one", and a body with several choices is then refused
+ rather than silently reduced to its first (the reading-side twin of
+ MAP-12's refusal of ``n``)."""
+ if not isinstance(data, Mapping):
+ raise TypeError(f"a Chat Completions response body is a JSON object, got {type(data).__name__}")
+ resp_error = data.get("error")
+ if isinstance(resp_error, dict):
+ raise on_error(str(resp_error.get("code") or ""), str(resp_error.get("message") or resp_error))
+
+ unmapped: list[dict[str, str]] = []
+ choices = data.get("choices") or []
+ if not isinstance(choices, list):
+ raise TypeError("choices must be an array")
+ if choice is None:
+ if len(choices) > 1:
+ raise UnsupportedFeatureError(
+ f"{provider}: the body carries {len(choices)} choices; a canonical Response is one message — "
+ "name the choice to read (choice=i) and read each one, or send no n",
+ provider=provider,
+ )
+ index = 0
+ else:
+ if choice < 0 or choice >= len(choices):
+ raise ValueError(f"choice={choice} but the body carries {len(choices)} choice(s)")
+ index = choice
+ path = f"choices[{index}]"
+ chosen = choices[index] if choices and isinstance(choices[index], dict) else {}
+ if choices and not isinstance(choices[index], dict):
+ _record_unmapped(unmapped, path, type(choices[index]).__name__)
+ message = chosen.get("message") if isinstance(chosen.get("message"), dict) else {}
+
+ parts: list[Any] = []
+ reasoning_text = message.get("reasoning_content") or message.get("reasoning")
+ if reasoning_text:
+ parts.append(ThinkingPart(text=str(reasoning_text)))
+
+ content = message.get("content")
+ if isinstance(content, str):
+ if content:
+ parts.append(TextPart(text=content))
+ elif isinstance(content, list):
+ for content_index, item in enumerate(content):
+ if isinstance(item, dict) and item.get("type") == "text":
+ parts.append(TextPart(text=str(item.get("text") or "")))
+ else:
+ _record_unmapped(
+ unmapped,
+ f"{path}.message.content[{content_index}]",
+ item.get("type") if isinstance(item, dict) else type(item).__name__,
+ )
+ elif content is not None:
+ _record_unmapped(unmapped, f"{path}.message.content", type(content).__name__)
+
+ refusal = message.get("refusal")
+ if refusal:
+ parts.append(RefusalPart(text=str(refusal)))
+
+ for call_index, call in enumerate(message.get("tool_calls") or []):
+ if not isinstance(call, dict):
+ _record_unmapped(unmapped, f"{path}.message.tool_calls[{call_index}]", type(call).__name__)
+ continue
+ call_type = call.get("type") or "function"
+ if call_type != "function":
+ _record_unmapped(unmapped, f"{path}.message.tool_calls[{call_index}]", call_type)
+ continue
+ function = call.get("function") if isinstance(call.get("function"), dict) else {}
+ if not function.get("name"):
+ raise unnamed_tool_call_error(provider, f"{path}.message.tool_calls[{call_index}]")
+ parts.append(
+ ToolCallPart(
+ id=str(call.get("id") or f"call_{len(parts)}"),
+ name=str(function["name"]),
+ input=parse_json_object(function.get("arguments")),
+ )
+ )
+
+ if not parts:
+ # MAP-2: a response message is never empty.
+ parts = [TextPart(text="")]
+
+ has_tool = any(isinstance(part, ToolCallPart) for part in parts)
+ usage = _usage_from_chat(data.get("usage") or {})
+ # choices[i].logprobs.content is the message-level token sequence.
+ # Refusal logprobs (choices[i].logprobs.refusal) stay in
+ # provider_data — no canonical refusal-token concept.
+ logprobs_payload = chosen.get("logprobs") if isinstance(chosen.get("logprobs"), dict) else {}
+ logprob_seq = openai_token_logprobs(logprobs_payload.get("content"))
+ resolved_model = data.get("model") or model
+ if not resolved_model:
+ raise ValueError("the body carries no model; pass model=")
+ return Response(
+ id=str(data.get("id")) if data.get("id") else None,
+ model=str(resolved_model),
+ message=Message(role="assistant", parts=tuple(parts)),
+ finish_reason=OpenAIChatLM._finish_reason(chosen.get("finish_reason"), has_tool_call=has_tool, unmapped=unmapped, path=path),
+ usage=usage,
+ logprobs=logprob_seq or None,
+ provider_data=_attach_unmapped(dict(data), unmapped),
+ )
+
+
+def response_from_openai_chat(body: Mapping[str, Any], *, model: str | None = None, choice: int | None = None) -> Response:
+ """A Chat Completions response body → the canonical :class:`Response`.
+
+ The reading-side twin of :func:`request_from_openai_chat`: ``body`` is
+ the JSON object a Chat Completions server (or a client library that
+ imitates one — litellm's ``ModelResponse.model_dump()``) returned. It
+ is the same reader :meth:`OpenAIChatLM.parse_response` runs on provider
+ traffic, so what it maps (text, ``reasoning_content`` → thinking, tool
+ calls, refusal, usage, logprobs, finish reason) and what it records as
+ unmapped (``provider_data["_lm15_unmapped"]``) are pinned by the
+ contract's ``response`` direction. An error envelope raises the typed
+ provider error.
+
+ ``model`` fills ``Response.model`` when the body carries none.
+ ``choice`` names the choice to read; left unset, a body with more than
+ one choice is refused (a Response is one message; read each choice by
+ index instead) — the twin of the request side's refusal of ``n``.
+ Keys the reader does not know are neither refused nor lost: the whole
+ body is ``provider_data``. No compat is taken: the Chat Completions
+ response shape does not vary by server the way the request does.
+ """
+ def on_error(code: str, message: str) -> ProviderError:
+ cls = OpenAILM._response_error_code_map.get(code, ServerError)
+ return cls(message or code or "provider error", provider="openai-chat", provider_code=code or None)
+
+ return _response_from_chat_body("openai-chat", body, model=model, choice=choice, on_error=on_error)
+
+
+def _usage_from_chat(usage_data: dict[str, Any]) -> Usage:
+ prompt_details = usage_data.get("prompt_tokens_details") or {}
+ completion_details = usage_data.get("completion_tokens_details") or {}
+ return Usage(
+ input_tokens=usage_data.get("prompt_tokens"),
+ output_tokens=usage_data.get("completion_tokens"),
+ total_tokens=usage_data.get("total_tokens"),
+ reasoning_tokens=completion_details.get("reasoning_tokens"),
+ cache_read_tokens=prompt_details.get("cached_tokens"),
+ cache_write_tokens=prompt_details.get("cache_write_tokens"),
+ input_audio_tokens=prompt_details.get("audio_tokens"),
+ output_audio_tokens=completion_details.get("audio_tokens"),
+ )
+
+
+@dataclass(slots=True)
+class OpenAIChatLM(BaseProviderLM):
+ """Adapter for the OpenAI Chat Completions wire dialect.
+
+ ``compat`` may be an :class:`OpenAIChatCompat`, a preset name
+ (``"ollama"``, ``"groq"``, ``"openrouter"``, ``"vllm"``, ``"sglang"``,
+ ``"openai"``, …), or None (plain OpenAI policy). A preset name also
+ supplies that server's default ``base_url``; an explicit non-default
+ ``base_url`` argument always wins.
+ """
+
+ api_key: Credential | None = field(default=None, repr=False)
+ transport: SyncTransport = field(default_factory=default_transport)
+ base_url: str = _DEFAULT_BASE_URL
+ compat: OpenAIChatCompat | str | None = None
+ access: ProviderManifest | None = field(default=None, repr=False)
+ credentials_path: "str | os.PathLike[str] | None" = field(default=None, repr=False)
+ settings: "Mapping[str, str] | None" = None
+ clock: "Callable[[], datetime] | None" = field(default=None, repr=False)
+
+ provider: str = field(default="openai-chat", init=False)
+ account_id: str | None = field(default=None, init=False, repr=False)
+ manifest: ClassVar[ProviderManifest] = OPENAI_CHAT_API
+
+ # OpenAI-compatible servers reuse the same error envelope family;
+ # share the Responses adapter's mapping verbatim.
+ _response_error_code_map: ClassVar[dict[str, type[ProviderError]]] = OpenAILM._response_error_code_map
+ _model_error_codes: ClassVar[frozenset[str]] = OpenAILM._model_error_codes
+ _stream_error_code_map: ClassVar[dict[str, type[ProviderError]]] = OpenAILM._stream_error_code_map
+
+ _is_model_error = staticmethod(OpenAILM._is_model_error)
+ _response_error = OpenAILM._response_error
+ _error_detail = OpenAILM._error_detail
+ normalize_error = OpenAILM.normalize_error
+
+ def __post_init__(self) -> None:
+ self._bind_access(self.access, credentials_path=self.credentials_path, default_base_url=_DEFAULT_BASE_URL, settings=self.settings)
+ compat = self.compat if self.compat is not None else self._registry_compat()
+ if isinstance(compat, str):
+ preset_key = compat.lower().replace("-", "_").replace(" ", "_")
+ partial = OpenAIChatCompat.preset(compat)
+ if self.base_url == _DEFAULT_BASE_URL:
+ self.base_url = OPENAI_CHAT_PRESET_BASE_URLS.get(preset_key, _DEFAULT_BASE_URL)
+ elif isinstance(compat, OpenAIChatCompat):
+ partial = compat
+ else:
+ partial = OpenAIChatCompat()
+ self._compat_partial = partial
+ self._resolved_compat = resolve_openai_chat_compat(partial)
+
+ _resolved_compat: ResolvedOpenAIChatCompat = field(init=False, repr=False, default=ResolvedOpenAIChatCompat())
+ _compat_partial: OpenAIChatCompat | None = field(init=False, repr=False, default=None)
+
+ def _headers(self) -> dict[str, str]:
+ headers: dict[str, str] = {} # auth is applied once, in _emit (AUTH-2)
+ headers["Content-Type"] = "application/json"
+ for key, static in self.access.headers:
+ headers[key] = static
+ return headers
+
+ # ─── Live model listing (provisional endpoint) ──────────────────────
+
+ def _models_request(self):
+ return self._emit(
+ method="GET",
+ url=f"{self.base_url.rstrip('/')}/models",
+ headers=self._headers(),
+ read_timeout=30.0,
+ )
+
+ def _models_from_body(self, body: str):
+ data = json.loads(body)
+ entries = data.get("data") if isinstance(data, dict) else None
+ return model_infos_from_entries(
+ entries,
+ provider=self.provider,
+ api_family="openai_chat",
+ id_of=lambda entry: entry.get("id"),
+ )
+
+ # ─── Request serialization ──────────────────────────────────────
+
+ def _build_messages(self, request: Request, compat: ResolvedOpenAIChatCompat) -> list[dict[str, Any]]:
+ messages: list[dict[str, Any]] = []
+ if request.system:
+ system_text = request.system if isinstance(request.system, str) else parts_to_text(request.system)
+ if _cache_stable_prefix(request, compat.cache_control):
+ # prefix="stable": the mark rides on the system message's
+ # text content part (array form; a bare string cannot carry it).
+ messages.append({"role": compat.instruction_role, "content": [
+ {"type": "text", "text": system_text, "prompt_cache_breakpoint": {"mode": "explicit"}}
+ ]})
+ else:
+ messages.append({"role": compat.instruction_role, "content": system_text})
+
+ breakpoint_index = _cache_breakpoint_index(request, compat.cache_control)
+ for msg_index, msg in enumerate(request.messages):
+ if msg_index == breakpoint_index and msg.role in ("assistant", "tool"):
+ raise _breakpoint_unsupported(self.provider, msg_index, msg.role)
+ if msg.role == "tool":
+ for part in msg.parts:
+ if isinstance(part, ToolResultPart):
+ item: dict[str, Any] = {
+ "role": "tool",
+ "tool_call_id": part.id,
+ "content": _tool_row_content(self.provider, part, compat.tool_result_media),
+ }
+ if compat.tool_result_name == "include" and part.name:
+ item["name"] = part.name
+ messages.append(item)
+ continue
+
+ if msg.role == "assistant":
+ text_bits: list[str] = []
+ for part in msg.parts:
+ if isinstance(part, TextPart):
+ text_bits.append(part.text)
+ elif isinstance(part, RefusalPart) and part.text:
+ text_bits.append(part.text)
+ elif isinstance(part, ThinkingPart) and compat.thinking_replay == "as_text" and part.text:
+ text_bits.append(part.text)
+ tool_calls = [
+ {
+ "id": part.id,
+ "type": "function",
+ "function": {
+ "name": part.name,
+ "arguments": json.dumps(part.input, separators=(",", ":")),
+ },
+ }
+ for part in msg.parts
+ if isinstance(part, ToolCallPart)
+ ]
+ item = {"role": "assistant", "content": "\n".join(text_bits) if text_bits else None}
+ if compat.thinking_replay == "native":
+ thinking = "\n".join(p.text for p in msg.parts if isinstance(p, ThinkingPart) and p.text)
+ if thinking or compat.assistant_reasoning_content == "include_empty":
+ item["reasoning_content"] = thinking
+ if tool_calls:
+ item["tool_calls"] = tool_calls
+ messages.append(item)
+ continue
+
+ role = compat.instruction_role if msg.role == "developer" else msg.role
+ at_breakpoint = msg_index == breakpoint_index
+ content = _chat_content_parts(msg, force_array=at_breakpoint, provider=self.provider)
+ if at_breakpoint:
+ # Same rule as the Responses dialect: the breakpoint rides on
+ # the last text content block of the prefix message
+ # (chat--create.md: ChatCompletionContentPartText carries
+ # prompt_cache_breakpoint).
+ if not isinstance(content, list) or not content or content[-1].get("type") != "text":
+ raise _breakpoint_unsupported(self.provider, msg_index, msg.role)
+ content[-1]["prompt_cache_breakpoint"] = {"mode": "explicit"}
+ if content or content == "":
+ messages.append({"role": role, "content": content})
+ return messages
+
+ def request_from_openai_chat(self, body: Mapping[str, Any]) -> Request:
+ """The inverse of :meth:`build_request`'s body under this adapter's
+ compat (MAP-12): a Chat Completions request body → canonical
+ :class:`Request`. See :func:`request_from_openai_chat`."""
+ model = body.get("model") if isinstance(body, Mapping) else None
+ compat = self._compat_for(model) if isinstance(model, str) else self._resolved_compat
+ return _ingest_openai_chat(self.provider, body, compat)
+
+ def _builtin_tool_payload(self, tool: BuiltinTool, compat: ResolvedOpenAIChatCompat) -> dict[str, Any]:
+ """Map a BuiltinTool for the chat dialect, or raise.
+
+ The base Chat Completions wire carries function/custom tools only,
+ and some compat servers silently IGNORE unknown tool types
+ (OpenRouter returned 200 with no search, verified live 2026-09-01)
+ — passthrough would fabricate wire shapes and silent no-ops, so
+ every unproven target raises.
+ """
+ if compat.builtin_tools == "groq":
+ wire_type = _GROQ_BUILTIN_MAP.get(tool.name)
+ if wire_type is None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: builtin tool {tool.name!r} has no Groq wire "
+ f"mapping — supported: {sorted(_GROQ_BUILTIN_MAP)}",
+ provider=self.provider,
+ )
+ entry: dict[str, Any] = {"type": wire_type}
+ if tool.config:
+ entry.update(tool.config)
+ return entry
+ raise UnsupportedFeatureError(
+ f"{self.provider}: builtin tool {tool.name!r} is not supported on this "
+ "server — the Chat Completions wire carries function tools only, and "
+ "unproven servers may silently ignore unknown tool types. Use "
+ "compat='groq' for Groq's server-executed tools, or the OpenAI "
+ "Responses / Anthropic / Gemini providers",
+ provider=self.provider,
+ )
+
+ def _tool_choice_payload(self, request: Request) -> Any:
+ tc = request.config.tool_choice
+ if tc is None:
+ return None
+ if tc.mode == "none":
+ return "none"
+ if tc.allowed:
+ by_name = {t.name: t for t in request.tools}
+ entries = [by_name[name] for name in tc.allowed]
+ builtins = [t.name for t in entries if isinstance(t, BuiltinTool)]
+ if builtins:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: cannot force builtin tools {builtins} — the "
+ "Chat Completions wire has no hosted-tool tool_choice form "
+ "(OpenAI Responses and Anthropic carry it)",
+ provider=self.provider,
+ )
+ if len(entries) == 1 and tc.mode == "required":
+ return {"type": "function", "function": {"name": entries[0].name}}
+ # mode="auto" restriction or multi-tool subset: the dialect's
+ # allowed_tools form (nested spelling, function tools only).
+ return {
+ "type": "allowed_tools",
+ "allowed_tools": {
+ "mode": tc.mode,
+ "tools": [
+ {"type": "function", "function": {"name": t.name}} for t in entries
+ ],
+ },
+ }
+ if tc.mode == "required":
+ return "required"
+ return "auto"
+
+ def _compat_for(self, model: str) -> ResolvedOpenAIChatCompat:
+ """The resolved compat for this model: the preset's per-family
+ overrides applied (OpenAIChatCompat.model_overrides)."""
+ partial = self._compat_partial
+ if partial is None or not partial.model_overrides:
+ return self._resolved_compat
+ return resolve_openai_chat_compat(partial.for_model(model))
+
+ def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ compat = self._compat_for(request.model)
+ payload: dict[str, Any] = {
+ "model": request.model,
+ "messages": self._build_messages(request, compat),
+ }
+ if stream:
+ payload["stream"] = True
+ if compat.stream_usage == "include":
+ payload["stream_options"] = {"include_usage": True}
+ if request.config.max_tokens is not None:
+ payload[compat.max_tokens_field] = request.config.max_tokens
+ if request.config.temperature is not None:
+ payload["temperature"] = request.config.temperature
+ if request.config.top_p is not None:
+ payload["top_p"] = request.config.top_p
+ if request.config.top_k is not None:
+ # No wire slot on Chat Completions (port.md rule 4: a raise or an
+ # extensions door, never omission).
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.top_k has no field on the Chat Completions wire; servers that accept "
+ "top_k take it through extensions", provider=self.provider,
+ )
+ if request.config.stop:
+ payload["stop"] = list(request.config.stop)
+ if request.config.logprobs is not None:
+ # Verified live 2026-09-01: logprobs=true alone returns chosen
+ # tokens only; top_logprobs adds the alternatives.
+ payload["logprobs"] = True
+ if request.config.logprobs > 0:
+ payload["top_logprobs"] = request.config.logprobs
+ if request.tools:
+ tools_wire: list[dict[str, Any]] = []
+ for tool in request.tools:
+ if isinstance(tool, FunctionTool):
+ function_payload: dict[str, Any] = {
+ "name": tool.name,
+ "description": tool.description,
+ "parameters": tool.parameters,
+ }
+ if compat.strict_tools == "include":
+ function_payload["strict"] = False
+ tools_wire.append({"type": "function", "function": function_payload})
+ elif isinstance(tool, BuiltinTool):
+ tools_wire.append(self._builtin_tool_payload(tool, compat))
+ if tools_wire:
+ payload["tools"] = tools_wire
+ tool_choice = self._tool_choice_payload(request)
+ if tool_choice is not None:
+ tc = request.config.tool_choice
+ if compat.forced_tool_choice == "reject" and (tc.mode != "auto" or tc.allowed):
+ # MAP-8: the server documents tool_choice=auto only and ignores
+ # every other form without an error (Z.AI, live 2026-09-03:
+ # required → text answer, none → a tool call). A silent widen
+ # is worse than an error; omit tool_choice or use "auto".
+ raise UnsupportedFeatureError(
+ f"{self.provider}: tool_choice mode={tc.mode!r}"
+ + (f" allowed={list(tc.allowed)}" if tc.allowed else "")
+ + " is silently ignored by this server (only 'auto' is honoured); "
+ "omit tool_choice, or send only the tools you want callable",
+ provider=self.provider,
+ )
+ payload["tool_choice"] = tool_choice
+ if request.config.tool_choice and request.config.tool_choice.parallel is not None:
+ payload["parallel_tool_calls"] = request.config.tool_choice.parallel
+ if request.config.response_format:
+ if compat.json_schema == "reject" and request.config.response_format["type"] != "json_object":
+ # The server accepts response_format.type=json_schema and
+ # ignores it (Z.AI, live 2026-09-03: HTTP 200, fenced JSON with
+ # keys the schema never named). json_object is honoured.
+ raise UnsupportedFeatureError(
+ f"{self.provider}: response_format type "
+ f"{request.config.response_format['type']!r} is silently ignored by this "
+ "server; use {'type': 'json_object'} and describe the shape in the prompt",
+ provider=self.provider,
+ )
+ payload["response_format"] = _response_format_to_chat(request.config.response_format)
+ if request.config.reasoning:
+ reasoning = request.config.reasoning
+ if not reasoning.is_off:
+ # MAP-7: verbatim effort; no budget on this wire; summary
+ # levels are Responses-only; "auto" maps to the dialect's
+ # visibility knob where one exists (Groq include_reasoning).
+ if reasoning.thinking_budget is not None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.thinking_budget is not supported — the Chat "
+ "Completions wire has no thinking token budget; use effort",
+ provider=self.provider,
+ )
+ if reasoning.summary in ("concise", "detailed"):
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.summary={reasoning.summary!r} is an OpenAI Responses "
+ "detail level; the Chat Completions wire has none (use 'auto')",
+ provider=self.provider,
+ )
+ effort = reasoning.effort
+ if compat.reasoning_efforts is not None and effort not in compat.reasoning_efforts:
+ # MAP-7 rule 2: a word with no native level raises here
+ # when the server would not refuse it (Moonshot kimi-k3
+ # answered 200 to `medium` and to `bogus`, live 2026-09-03).
+ raise UnsupportedFeatureError(
+ f"{self.provider}: reasoning.effort={effort!r} has no level on this server "
+ f"(it accepts {', '.join(compat.reasoning_efforts)}) and would be accepted silently",
+ provider=self.provider,
+ )
+ if compat.builtin_tools == "groq" and reasoning.summary == "auto":
+ # Groq's visibility knob (MAP-7 rule 7): "parsed" returns
+ # the trace as message.reasoning. Live 2026-09-02: Qwen
+ # 3.6's default leaks a raw <think> block into
+ # message.content; this is the wire's fix. Qwen's dial
+ # accepts only none|default, so an effort word still
+ # fails loudly there — extensions={"reasoning_format":
+ # "parsed"} with reasoning absent is the documented door.
+ payload["reasoning_format"] = "parsed"
+ if compat.thinking_format == "reasoning_effort":
+ payload["reasoning_effort"] = effort
+ elif compat.thinking_format == "openrouter":
+ payload["reasoning"] = {"effort": effort}
+ elif compat.thinking_format == "deepseek":
+ payload["thinking"] = {"type": "enabled"}
+ payload["reasoning_effort"] = effort
+ elif compat.thinking_format == "kimi":
+ # Moonshot: the effort word alone, the field kimi-k3
+ # documents (guide--reasoning-effort.md). A `thinking`
+ # object beside it is accepted (live 2026-09-03) but the
+ # docs say not to send it, and it would carry nothing.
+ # Stated trade-off: kimi-k2.6 has no levels and ignores
+ # the word silently (live 2026-09-03, still 44 reasoning
+ # tokens at `low`); the adapter does not sniff model
+ # names, so the docs say: do not set effort on K2.x.
+ payload["reasoning_effort"] = effort
+ elif compat.thinking_format == "qwen":
+ payload["enable_thinking"] = True
+ elif compat.thinking_format == "qwen_chat_template":
+ payload["chat_template_kwargs"] = {
+ "enable_thinking": True,
+ "preserve_thinking": True,
+ }
+ else:
+ # Explicit off must reach the wire; omission lets
+ # reasoning-by-default models spend hidden reasoning tokens
+ # (verified live 2026-09-01 on Groq: gpt-oss-20b spent 45
+ # reasoning tokens when the field was omitted). Servers
+ # whose models cannot disable reasoning reject "none" with
+ # a clear 400 — loud failure over a silent paid no-op.
+ if compat.thinking_format == "reasoning_effort":
+ payload["reasoning_effort"] = "none"
+ elif compat.thinking_format == "openrouter":
+ payload["reasoning"] = {"enabled": False}
+ elif compat.thinking_format in ("deepseek", "kimi"):
+ # "kimi": the K2.x family's documented off switch; the
+ # docs say kimi-k3 "always reasons", but live 2026-09-03
+ # it honoured the object too (200, no reasoning_content,
+ # no reasoning_tokens) — pinned as moonshotai.reasoning_off.
+ payload["thinking"] = {"type": "disabled"}
+ elif compat.thinking_format == "qwen":
+ payload["enable_thinking"] = False
+ elif compat.thinking_format == "qwen_chat_template":
+ payload["chat_template_kwargs"] = {"enable_thinking": False}
+
+ # Prompt caching (MAP-6): off switch, key, retention, resource.
+ _cache_common_payload(request, payload, compat.cache_control, self.provider)
+
+ if compat.routing is not None:
+ payload["provider"] = compat.routing
+
+ # Promoted cross-provider knobs (changes/2026-09-01-extensions-burn-down):
+ # Chat Completions spellings — user_id rides the dialect's `user`
+ # field, or the server's own name when the compat says so (DeepSeek:
+ # `user_id`; Meta: `safety_identifier`, which supersedes `user` on
+ # that server — protocols--chat-completions.md). Servers that
+ # do not implement a field reject it themselves; the dialect adapter
+ # cannot know each compat server's support statically.
+ if request.config.service_tier is not None:
+ payload["service_tier"] = request.config.service_tier
+ if request.config.user_id is not None:
+ payload[compat.user_field] = request.config.user_id
+ if request.config.store is not None:
+ payload["store"] = request.config.store
+
+ if request.config.extensions:
+ reserved = {
+ "prompt_caching",
+ "cache",
+ "compat",
+ "openai_compat",
+ "openai_chat_compat",
+ }
+ passthrough = {k: v for k, v in request.config.extensions.items() if k not in reserved}
+ payload.update(passthrough)
+ return payload
+
+ def build_request(self, request: Request, stream: bool) -> TransportRequest:
+ return self._emit(
+ method="POST",
+ url=f"{self.base_url.rstrip('/')}/chat/completions",
+ endpoint="chat/completions",
+ stream=stream,
+ model=request.model,
+ headers=self._headers(),
+ payload=self._payload(request, stream=stream),
+ read_timeout=120.0 if stream else 60.0,
+ )
+
+ # ─── Response parsing ───────────────────────────────────────────
+
+ @staticmethod
+ def _finish_reason(raw: Any, *, has_tool_call: bool, unmapped: list[dict[str, str]], path: str = "choices[0]") -> str:
+ if has_tool_call:
+ return "tool_call"
+ if raw is None or raw == "":
+ return "stop"
+ mapped = _FINISH_REASON_MAP.get(str(raw))
+ if mapped is None:
+ _record_unmapped(unmapped, f"{path}.finish_reason", raw)
+ return "stop"
+ return mapped
+
+ def parse_response(self, request: Request, response: HttpResponse) -> Response:
+ return _response_from_chat_body(
+ self.provider, response.json(), model=request.model,
+ choice=None, on_error=self._response_error,
+ )
+
+ def response_from_openai_chat(self, body: Mapping[str, Any], *, model: str | None = None, choice: int | None = None) -> Response:
+ """A Chat Completions response body → canonical :class:`Response`
+ under this adapter's provider name and error mapping; see
+ :func:`response_from_openai_chat`."""
+ return _response_from_chat_body(self.provider, body, model=model, choice=choice, on_error=self._response_error)
+
+ # ─── Stream parsing ──────────────────────────────────────────────
+
+ def parse_stream_events(self, request: Request, raw_event: SSEEvent) -> Iterator[StreamEvent]:
+ if not raw_event.data:
+ return
+ if raw_event.data == "[DONE]":
+ yield StreamEndEvent()
+ return
+ payload = json.loads(raw_event.data)
+ if not isinstance(payload, dict):
+ return
+
+ err = payload.get("error")
+ if isinstance(err, dict):
+ provider_code = str(err.get("code") or err.get("type") or "provider")
+ yield StreamErrorEvent(error=self._error_detail(provider_code, str(err.get("message") or "")))
+ return
+
+ choices = payload.get("choices") or []
+ choice = choices[0] if choices and isinstance(choices[0], dict) else {}
+ delta = choice.get("delta") if isinstance(choice.get("delta"), dict) else {}
+
+ reasoning_text = delta.get("reasoning_content") or delta.get("reasoning")
+ if reasoning_text:
+ yield StreamDeltaEvent(delta=ThinkingDelta(text=str(reasoning_text)))
+
+ content = delta.get("content")
+ if isinstance(content, str) and content:
+ logprobs_payload = choice.get("logprobs") if isinstance(choice.get("logprobs"), dict) else {}
+ yield StreamDeltaEvent(
+ delta=TextDelta(
+ text=content,
+ logprobs=openai_token_logprobs(logprobs_payload.get("content")),
+ )
+ )
+
+ for call in delta.get("tool_calls") or []:
+ if not isinstance(call, dict):
+ continue
+ function = call.get("function") if isinstance(call.get("function"), dict) else {}
+ yield StreamDeltaEvent(
+ delta=ToolCallDelta(
+ input=str(function.get("arguments") or ""),
+ part_index=int(call.get("index", 0) or 0),
+ id=str(call.get("id") or "") or None,
+ name=str(function.get("name") or "") or None,
+ )
+ )
+
+ # MAP-3 (D9, 2026-09-06): the end event's provider_data is the frame
+ # that supplied usage, verbatim, else the frame that supplied
+ # finish_reason; [DONE] contributes nothing. The coalescer keeps the
+ # usage frame's when both arrive.
+ finish_raw = choice.get("finish_reason")
+ usage_data = payload.get("usage")
+ if finish_raw:
+ yield StreamEndEvent(
+ finish_reason=_FINISH_REASON_MAP.get(str(finish_raw), "stop"),
+ usage=_usage_from_chat(usage_data) if isinstance(usage_data, dict) else None,
+ provider_data=payload,
+ )
+ elif isinstance(usage_data, dict):
+ # Final usage-only chunk (stream_options.include_usage).
+ yield StreamEndEvent(usage=_usage_from_chat(usage_data), provider_data=payload)
diff --git a/dspy/_vendor/lm15/providers/openai_codex.py b/dspy/_vendor/lm15/providers/openai_codex.py
new file mode 100644
index 000000000..57afb4352
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/openai_codex.py
@@ -0,0 +1,75 @@
+"""
+lm15.providers.openai_codex — the OpenAI Responses dialect on a Codex login.
+
+``OpenAICodexLM`` is a *name*, not a behaviour: it is ``OpenAILM`` bound to
+``lm15.access.OPENAI_CODEX``. The ChatGPT Codex backend's differences —
+bearer OAuth with a ``chatgpt-account-id``, the ``OpenAI-Beta`` and
+``originator`` headers, the instructions prefix, ``store: false``,
+streaming-only, the ``{"detail": ...}`` error envelope, the ``/models``
+shape, no files/batch/images/speech/live — are fields of that policy or
+branches on its ``backend`` inside the dialect, at stated points. A port
+needs the policy table and the dialect, not this class.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import ClassVar
+
+from ..access import ( # noqa: F401
+ DEFAULT_CODEX_BASE_URL,
+ DEFAULT_CODEX_CLIENT_VERSION,
+ DEFAULT_CODEX_INSTRUCTIONS,
+ DEFAULT_CODEX_ORIGINATOR,
+ OPENAI_CODEX,
+)
+from ..features import ProviderManifest
+from .base import Credential, SyncTransport, default_transport
+from .openai import MODEL_LIST_HINT, OpenAILM # noqa: F401
+
+
+class OpenAICodexLM(OpenAILM):
+ """OpenAI Responses adapter authenticated with local Codex CLI OAuth."""
+
+ manifest: ClassVar[ProviderManifest] = OPENAI_CODEX
+
+ def __init__(
+ self,
+ api_key: Credential | None = None,
+ *,
+ account_id: str | None = None,
+ auth_path: str | os.PathLike[str] | None = None,
+ transport: SyncTransport | None = None,
+ base_url: str = DEFAULT_CODEX_BASE_URL,
+ originator: str = DEFAULT_CODEX_ORIGINATOR,
+ client_version: str = DEFAULT_CODEX_CLIENT_VERSION,
+ ) -> None:
+ self.originator = originator
+ self.client_version = client_version
+ policy = OPENAI_CODEX
+ if originator != DEFAULT_CODEX_ORIGINATOR:
+ policy = policy.with_headers({"originator": originator})
+ if client_version != DEFAULT_CODEX_CLIENT_VERSION:
+ from dataclasses import replace
+
+ policy = replace(policy, backend_options={**policy.backend_options, "client_version": client_version})
+ super().__init__(
+ api_key=api_key,
+ transport=transport or default_transport(),
+ base_url=base_url,
+ profile=None,
+ access=policy,
+ credentials_path=auth_path,
+ account_id=account_id,
+ )
+
+ @classmethod
+ def from_codex_cli(
+ cls,
+ *,
+ auth_path: str | os.PathLike[str] | None = None,
+ transport: SyncTransport | None = None,
+ base_url: str = DEFAULT_CODEX_BASE_URL,
+ originator: str = DEFAULT_CODEX_ORIGINATOR,
+ ) -> "OpenAICodexLM":
+ return cls(auth_path=auth_path, transport=transport, base_url=base_url, originator=originator)
diff --git a/dspy/_vendor/lm15/providers/xai.py b/dspy/_vendor/lm15/providers/xai.py
new file mode 100644
index 000000000..cd9a26e13
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/xai.py
@@ -0,0 +1,288 @@
+"""
+lm15.providers.xai — xAI Grok adapter (Chat Completions dialect).
+
+xAI's API speaks the Chat Completions dialect at ``https://api.x.ai/v1``
+(compat preset ``"xai"``, pinned live 2026-09-01). What makes it a
+first-class adapter instead of a preset route is authentication: xAI sells
+subscription access (SuperGrok / X Premium) through a device-code OAuth
+flow, and the resulting access token is sent as an ordinary bearer key.
+
+Credential resolution order (``oauth-unless-explicit`` policy, spec/auth.md
+AUTH-1) — through the router:
+
+1. an explicit ``RouterConfig.api_keys`` entry (or an ``api_key`` argument
+ when constructing this class directly): deliberate, in-process
+ configuration always wins;
+2. the stored subscription OAuth login when one is usable: lm15's own
+ credential store, then the Pi agent store (``~/.pi/agent/auth.json``);
+ refreshed tokens are written back to their source file (xAI rotates
+ refresh tokens);
+3. ``XAI_API_KEY`` from the environment, only when no usable subscription
+ login is stored.
+
+Why the subscription outranks the env var: both are stored state, but using
+the subscription costs nothing per token while a key bills every call — and
+lm15's durable constraint is that normal inference must not unexpectedly
+spend money. Stated residual trade-off: with a subscription stored, a set
+``XAI_API_KEY`` is silently ignored; if you need that key's account, pass it
+explicitly (``api_key=`` / ``RouterConfig.api_keys``). Run
+``lm15.doctor.explain_auth("xai")`` to see which rung won.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from typing import Any, ClassVar
+
+from ..access import DEFAULT_XAI_BASE_URL, XAI
+from ..errors import ProviderError, UnsupportedFeatureError
+from ..features import ProviderManifest
+from ..transports import TransportRequest
+from .common import path_id
+from ..types import ImageGenerationRequest, ImageGenerationResponse, ImagePart, Request, Usage, VideoGenerationRequest, VideoJobInfo, VideoPart
+from .base import Credential, HttpResponse, SyncTransport, default_transport
+from .openai_chat import OpenAIChatLM
+
+
+class XaiLM(OpenAIChatLM):
+ """Chat Completions adapter for xAI, with subscription OAuth fallback.
+
+ xAI is a provider, not an access path: its image and video wire, and
+ its refusals (reasoning off, logprobs, the MAP-8 cells), are provider
+ facts and live here. Only the credential path is composed: the
+ ``lm15.access.XAI`` policy carries the ``oauth-unless-explicit`` chain,
+ the login hint, and the endpoint surfaces.
+ """
+
+ manifest: ClassVar[ProviderManifest] = XAI
+
+ def __init__(
+ self,
+ api_key: Credential | None = None,
+ *,
+ credentials_path: str | os.PathLike[str] | None = None,
+ transport: SyncTransport | None = None,
+ base_url: str = DEFAULT_XAI_BASE_URL,
+ ) -> None:
+ super().__init__(
+ api_key=api_key,
+ transport=transport or default_transport(),
+ base_url=base_url,
+ compat="xai",
+ access=XAI,
+ credentials_path=credentials_path,
+ )
+
+ def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ # Grok reasoning models have no off switch. The inherited deepseek
+ # wire shape (thinking={"type": "disabled"}) is accepted by
+ # api.x.ai but silently ignored — verified live 2026-09-01:
+ # grok-4.6 still spent 158 reasoning tokens. A silent paid no-op
+ # on an explicit disable is worse than an error, so raise. For
+ # non-reasoning Grok variants, omit the reasoning config
+ # (Config(reasoning=None)) — they never reason anyway.
+ reasoning = request.config.reasoning
+ if reasoning is not None and reasoning.is_off:
+ raise UnsupportedFeatureError(
+ "xai: reasoning cannot be disabled — Grok reasoning models have no "
+ "off switch, and xAI silently ignores disable fields on the wire. "
+ "Omit the reasoning config, or pick a non-reasoning Grok model.",
+ provider=self.provider,
+ )
+ # docs.x.ai (models page, 2026-09-01): "logprobs and top_logprobs are
+ # not supported by models grok-4.20 and newer. These fields will be
+ # silently ignored if set." Verified live 2026-09-01 on grok-4.6:
+ # HTTP 200, the choice carries no logprobs key at all. Every Grok
+ # model served today is 4.20 or newer, so sending the field is a
+ # guaranteed silent no-op — raise instead.
+ if request.config.logprobs is not None:
+ raise UnsupportedFeatureError(
+ "xai: config.logprobs is not supported — grok-4.20 and newer "
+ "silently ignore logprobs/top_logprobs on the wire (docs.x.ai, "
+ "verified live 2026-09-01). OpenAI and Gemini carry logprobs.",
+ provider=self.provider,
+ )
+ tc = request.config.tool_choice
+ if tc is not None and tc.allowed and not (len(tc.allowed) == 1 and tc.mode == "required"):
+ # MAP-8 rule 1 (live 2026-09-02): api.x.ai accepts allowed_tools and
+ # ignores it — with {lookup} allowed and weather asked, it called
+ # weather. A silent widen; the forced single-function form held.
+ raise UnsupportedFeatureError(
+ "xai: tool_choice.allowed subsets are silently ignored by api.x.ai "
+ "(verified live 2026-09-02); force a single tool with mode='required', "
+ "or send only the allowed tools in Request.tools",
+ provider=self.provider,
+ )
+ if tc is not None and tc.mode == "required" and request.config.response_format is not None:
+ # MAP-8 rule 3 (live 2026-09-02): a forced tool next to a
+ # response_format returned JSON text and no call.
+ raise UnsupportedFeatureError(
+ "xai: a forced tool (mode='required') cannot be combined with response_format — "
+ "api.x.ai returns JSON text and drops the call (verified live 2026-09-02)",
+ provider=self.provider,
+ )
+ return super()._payload(request, stream)
+
+ def _image_generate_request(self, request: ImageGenerationRequest) -> TransportRequest:
+ base = self.base_url.rstrip("/")
+ payload: dict[str, Any] = {"model": request.model, "prompt": request.prompt, **(request.extensions or {})}
+ if request.size is not None:
+ # No wire slot: xAI sizes through quality/resolution knobs with
+ # their own names (extensions). Raising beats guessing a mapping.
+ raise UnsupportedFeatureError(
+ "xai: size has no wire slot; use extensions for xAI's quality/resolution fields",
+ provider=self.provider,
+ )
+ if not request.images:
+ return self._emit(method="POST", url=f"{base}/images/generations", headers=self._headers(), payload=payload, read_timeout=300.0)
+ if len(request.images) > 1:
+ raise UnsupportedFeatureError(
+ "xai: image edits take exactly one input image; the wire has no slot for more",
+ provider=self.provider,
+ )
+ payload["image"] = _xai_image_input(request.images[0], self.provider)
+ return self._emit(method="POST", url=f"{base}/images/edits", headers=self._headers(), payload=payload, read_timeout=300.0)
+
+ def _image_generation_from_response(self, request: ImageGenerationRequest, resp: HttpResponse) -> ImageGenerationResponse:
+ data = resp.json()
+ images: list[ImagePart] = []
+ for item in data.get("data", []) or []:
+ if not isinstance(item, dict):
+ continue
+ mime = item.get("mime_type")
+ media_type = mime if isinstance(mime, str) and mime else "application/octet-stream"
+ if item.get("b64_json"):
+ images.append(ImagePart(media_type=media_type, data=str(item["b64_json"])))
+ elif item.get("url"):
+ images.append(ImagePart(media_type=media_type, url=str(item["url"])))
+ if not images:
+ raise ProviderError("xai: image response carries no images", provider=self.provider)
+ # Captured: usage reports cost_in_usd_ticks only — no token counts
+ # exist, so Usage stays empty and the figure lives in provider_data.
+ return ImageGenerationResponse(images=tuple(images), usage=Usage(), provider_data=data)
+
+ # ─── Video generation (grok-imagine; captured live 2026-09-01) ──────
+ #
+ # POST /videos/generations -> {"request_id"}; GET /videos/{id} ->
+ # pending + progress %, then done + a PUBLIC MP4 URL (downloads with
+ # no auth, verified) — so the result is URL-addressed, no fetch step.
+ # There is NO list endpoint (probed: 404): the ticket you store is
+ # the only copy.
+
+ _VIDEO_STATUS_MAP: ClassVar[dict[str, str]] = {
+ "pending": "running",
+ "done": "completed",
+ "failed": "failed",
+ }
+
+ def _video_submit_request(self, request: VideoGenerationRequest) -> TransportRequest:
+ if request.seconds is not None:
+ raise UnsupportedFeatureError(
+ "xai: video duration has no wire slot", provider=self.provider,
+ )
+ if request.images:
+ # The image-generation wire silently IGNORES unknown fields
+ # (pixel-verified 2026-09-01); an unverified image-input mapping
+ # here could silently produce prompt-only videos. Raise until
+ # the field is live-receipted.
+ raise UnsupportedFeatureError(
+ "xai: video input images are not mapped yet; "
+ "use extensions until the mapping is live-receipted",
+ provider=self.provider,
+ )
+ payload: dict[str, Any] = {"model": request.model, "prompt": request.prompt, **(request.extensions or {})}
+ return self._emit(
+ method="POST", url=f"{self.base_url.rstrip('/')}/videos/generations",
+ headers=self._headers(), payload=payload, read_timeout=120.0,
+ )
+
+ def _video_job_from_body(self, body: str, video_id: "str | None" = None) -> VideoJobInfo:
+ data = json.loads(body)
+ request_id = data.get("request_id")
+ if isinstance(request_id, str) and request_id:
+ # The submit acknowledgement: a bare ticket, not yet started.
+ return VideoJobInfo(id=request_id, status="queued", provider_data=data)
+ if video_id is None:
+ raise ProviderError("xai: video body carries no request_id", provider=self.provider)
+ return self._video_status_info(video_id, data)
+
+ def _video_status_request(self, video_id: str) -> TransportRequest:
+ return self._emit(
+ method="GET", url=f"{self.base_url.rstrip('/')}/videos/{path_id(video_id)}",
+ headers=self._headers(), read_timeout=60.0,
+ )
+
+ def _video_status_info(self, video_id: str, data: "dict[str, Any]") -> VideoJobInfo:
+ wire_status = str(data.get("status") or "")
+ status = self._VIDEO_STATUS_MAP.get(wire_status)
+ if status is None:
+ raise ProviderError(f"xai: unknown video status {wire_status!r}", provider=self.provider)
+ progress = data.get("progress")
+ return VideoJobInfo(
+ id=video_id,
+ status=status,
+ progress=int(progress) if isinstance(progress, (int, float)) and not isinstance(progress, bool) else None,
+ model=data.get("model"),
+ provider_data=data,
+ )
+
+ def _video_list_request(self, limit: int, model: "str | None") -> TransportRequest:
+ raise UnsupportedFeatureError(
+ "xai: the wire has no video list endpoint (probed 2026-09-01: 404) — "
+ "the ticket you stored is the only copy",
+ provider=self.provider,
+ )
+
+ def _video_result_fetch(self, status_body: "dict[str, Any]") -> None:
+ return None # the terminal body carries a public URL
+
+ def _video_part(self, status_body: "dict[str, Any]", fetched: object) -> VideoPart:
+ video = status_body.get("video") if isinstance(status_body.get("video"), dict) else {}
+ url = video.get("url")
+ if not isinstance(url, str) or not url:
+ raise ProviderError("xai: terminal video carries no url", provider=self.provider)
+ return VideoPart(media_type="video/mp4", url=url)
+
+ def normalize_error(self, status: int, body: str) -> ProviderError:
+ # xAI's own envelope is {"code": str, "error": str} (captured
+ # 2026-09-01: model-not-found 400, unauthenticated 401) — refold it
+ # into the OpenAI shape so the shared mapping preserves the wire
+ # code as provider_code instead of dropping it.
+ try:
+ data = json.loads(body)
+ if isinstance(data, dict) and isinstance(data.get("error"), str):
+ body = json.dumps({"error": {"message": data["error"], "code": data.get("code")}})
+ except ValueError:
+ pass
+ # Auth failures on the subscription path guide the user back to
+ # login (the access policy's hint, applied by the shared mapping
+ # when the stored login was the rung that won).
+ return super().normalize_error(status, body)
+
+
+# ─── Media generation (captured live 2026-09-01) ─────────────────────
+#
+# Images: /images/generations for text-to-image; /images/edits for
+# image-to-image. The split matters: `generations` silently IGNORES
+# input images (verified by pixel check), so edits must never route
+# there. The edit input is `image:{url|file_id}` — an https URL, a
+# data URI (verified honored), or an xAI file id. Exactly one input
+# image; the wire has no slot for more. Responses state `mime_type`
+# per image (JPEG, captured); usage reports only a dollar-tick cost,
+# which stays verbatim in provider_data (no token counts exist).
+# Speech: no endpoint (voice is app-only) — the base hooks raise.
+
+
+def _xai_image_input(part: "ImagePart", provider: str) -> dict[str, str]:
+ if part.url is not None:
+ return {"url": part.url}
+ if part.file_id is not None:
+ return {"file_id": part.file_id}
+ if part.data is not None:
+ return {"url": f"data:{part.media_type};base64,{part.data}"}
+ if part.path is not None:
+ encoded = base64.b64encode(part.path.read_bytes()).decode("ascii")
+ return {"url": f"data:{part.media_type};base64,{encoded}"}
+ raise UnsupportedFeatureError(f"{provider}: input image carries no content", provider=provider)
diff --git a/dspy/_vendor/lm15/py.typed b/dspy/_vendor/lm15/py.typed
new file mode 100644
index 000000000..e69de29bb
diff --git a/dspy/_vendor/lm15/registry.py b/dspy/_vendor/lm15/registry.py
new file mode 100644
index 000000000..92f9a90f6
--- /dev/null
+++ b/dspy/_vendor/lm15/registry.py
@@ -0,0 +1,446 @@
+"""
+lm15.registry — the one table of named providers.
+
+A routable provider string names a :class:`ProviderDefinition`: a wire
+dialect (the adapter class that speaks it), an :class:`AccessPolicy`
+(credential chain, static headers, endpoint surfaces, default base URL)
+and — for the Chat Completions dialect — the compat preset that names the
+server's quirks. The router, the doctor, the vet surface dump (and
+through it the contract's support matrix) and the docs tables all read
+this table. Nothing else lists providers.
+
+Two kinds of entries share one shape:
+
+- **adapter-owned** — the dialect class carries its own manifest
+ (``OpenAILM``, ``AnthropicLM``, ``GeminiLM``, ``XaiLM``, ``ClaudeCodeLM``,
+ ``OpenAICodexLM``). The entry points at the class; ``access`` IS the
+ class manifest.
+- **bound** — a dialect class with an access policy bound at construction
+ plus a compat preset: ``OpenAIChatLM`` for ``groq``, ``openrouter``,
+ ``deepseek``, ``zai``, ``ollama``, ``vllm``, ``sglang``; ``AnthropicLM``
+ for ``deepseek-anthropic``. Pure data: adding one is a declaration in
+ this file plus a live receipt in the contract, never a new class.
+
+Rules this table enforces (``tests/test_registry.py``):
+
+- a provider string names ONE wire behavior — the same service reachable
+ over two dialects is two entries (spec rule: a provider name describes
+ wire behavior, not credential ownership);
+- ``access.provider`` equals the entry id (hyphenated form; the underscore
+ form is an input alias only — spec/vocabularies.md § Open string
+ namespaces, 2026-09-08);
+- a bound entry's ``access.base_url`` equals its dialect's compat table
+ URL for the same preset — one copy of each URL;
+- an entry with ``placeholder_key`` declares no env keys (keyless local
+ servers), and vice versa.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Literal, Mapping
+
+from . import access as _access
+from .compat import (
+ ANTHROPIC_PRESET_BASE_URLS,
+ OPENAI_CHAT_PRESET_BASE_URLS,
+ OPENAI_RESPONSES_PRESET_BASE_URLS,
+ AnthropicCompat,
+ OpenAIChatCompat,
+ OpenAIResponsesCompat,
+)
+from .features import AccessPolicy, CredentialPolicy, EndpointSupport
+from .providers import (
+ AnthropicLM,
+ AsyncAnthropicLM,
+ AsyncClaudeCodeLM,
+ AsyncGeminiLM,
+ AsyncOpenAIChatLM,
+ AsyncOpenAICodexLM,
+ AsyncOpenAILM,
+ AsyncXaiLM,
+ ClaudeCodeLM,
+ GeminiLM,
+ OpenAIChatLM,
+ OpenAICodexLM,
+ OpenAILM,
+ XaiLM,
+)
+
+__all__ = [
+ "Dialect",
+ "ProviderDefinition",
+ "PROVIDERS",
+ "canonical_provider",
+ "lookup",
+]
+
+# The wire formats lm15 speaks. A dialect is a class; a provider is a
+# dialect plus an access policy (plus a compat preset for the chat dialect).
+Dialect = Literal["openai-responses", "openai-chat", "anthropic", "gemini"]
+
+
+# Per dialect: the compat preset constructor and the preset → base URL table
+# a bound entry is validated against. A dialect absent here cannot bind.
+_COMPAT_TABLES: dict[str, tuple] = {
+ "openai-responses": (OpenAIResponsesCompat.preset, OPENAI_RESPONSES_PRESET_BASE_URLS),
+ "openai-chat": (OpenAIChatCompat.preset, OPENAI_CHAT_PRESET_BASE_URLS),
+ "anthropic": (AnthropicCompat.preset, ANTHROPIC_PRESET_BASE_URLS),
+}
+
+
+def canonical_provider(name: str) -> str:
+ """Provider strings are hyphenated (``openai-chat``); the underscore
+ spelling is accepted everywhere as a permanent alias."""
+ return name.replace("_", "-")
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDefinition:
+ """Everything lm15 knows about one named provider, as a value.
+
+ ``id`` canonical provider string (hyphenated).
+ ``dialect`` the wire format; names which adapter class speaks it.
+ ``adapter`` sync LM class; ``async_adapter`` its async mirror.
+ ``access`` the credential chain, headers, surfaces and default
+ base URL (``lm15.access``); for a bound entry the
+ router passes this to the dialect constructor.
+ ``compat`` Chat Completions preset name (bound entries only).
+ ``placeholder_key`` the key a keyless local server accepts when nothing
+ is configured (AUTH-1 last rung); None otherwise.
+ ``console_url`` where a human gets a key (docs, doctor hints).
+ ``note`` one-line human rationale, surfaced in docs and
+ ``Resolution.describe``.
+ """
+
+ id: str
+ dialect: Dialect
+ adapter: type
+ async_adapter: type
+ access: AccessPolicy
+ compat: str | None = None
+ placeholder_key: str | None = None
+ console_url: str | None = None
+ note: str = ""
+
+ def __post_init__(self) -> None:
+ if self.id != canonical_provider(self.id):
+ raise ValueError(f"provider id must be hyphenated: {self.id!r}")
+ if canonical_provider(self.access.provider) != self.id:
+ raise ValueError(f"{self.id}: access policy names provider {self.access.provider!r}")
+ if self.placeholder_key is not None and self.access.env_keys:
+ raise ValueError(f"{self.id}: a keyless local server declares no env_keys")
+ if self.hosted:
+ # A cloud door (AUTH-10 host): the base URL is a template rendered
+ # over the host settings at construction, so the compat-table URL
+ # rule does not apply; a compat preset is optional and, when
+ # named, must exist for the dialect.
+ if self.compat is not None:
+ presets, _ = _COMPAT_TABLES[self.dialect]
+ presets(self.compat)
+ return
+ if self.bound:
+ if self.compat is None:
+ raise ValueError(f"{self.id}: a bound entry names its compat preset")
+ presets, urls = _COMPAT_TABLES[self.dialect]
+ presets(self.compat) # raises for an unknown preset
+ expected = urls.get(self.compat)
+ if self.access.base_url != expected:
+ raise ValueError(
+ f"{self.id}: access.base_url {self.access.base_url!r} != "
+ f"compat table {expected!r} for preset {self.compat!r}"
+ )
+
+ @property
+ def hosted(self) -> bool:
+ """True when the access policy names a cloud host (AUTH-10)."""
+ return self.access.host is not None
+
+ @property
+ def bound(self) -> bool:
+ """True when the router binds ``access`` onto the dialect class at
+ construction (the class's own manifest is not this provider)."""
+ return self.access is not self.adapter.manifest
+
+ @property
+ def env_keys(self) -> tuple[str, ...]:
+ return self.access.env_keys
+
+ @property
+ def credential_policy(self) -> CredentialPolicy:
+ return self.access.credential_policy
+
+ @property
+ def supports(self) -> EndpointSupport:
+ return self.access.supports
+
+ @property
+ def base_url(self) -> str | None:
+ return self.access.base_url
+
+
+def _adapter_owned(
+ id: str,
+ dialect: Dialect,
+ adapter: type,
+ async_adapter: type,
+ *,
+ console_url: str | None = None,
+ note: str = "",
+) -> ProviderDefinition:
+ return ProviderDefinition(
+ id=id,
+ dialect=dialect,
+ adapter=adapter,
+ async_adapter=async_adapter,
+ access=adapter.manifest,
+ console_url=console_url,
+ note=note,
+ )
+
+
+def _responses_bound(
+ access: AccessPolicy,
+ *,
+ compat: str,
+ console_url: str | None = None,
+ note: str = "",
+) -> ProviderDefinition:
+ return ProviderDefinition(
+ id=access.provider,
+ dialect="openai-responses",
+ adapter=OpenAILM,
+ async_adapter=AsyncOpenAILM,
+ access=access,
+ compat=compat,
+ console_url=console_url,
+ note=note,
+ )
+
+
+def _chat_bound(
+ access: AccessPolicy,
+ *,
+ compat: str | None = None,
+ placeholder_key: str | None = None,
+ console_url: str | None = None,
+ note: str = "",
+) -> ProviderDefinition:
+ return ProviderDefinition(
+ id=access.provider,
+ dialect="openai-chat",
+ adapter=OpenAIChatLM,
+ async_adapter=AsyncOpenAIChatLM,
+ access=access,
+ compat=compat or access.provider,
+ placeholder_key=placeholder_key,
+ console_url=console_url,
+ note=note,
+ )
+
+
+def _anthropic_bound(
+ access: AccessPolicy,
+ *,
+ compat: str,
+ console_url: str | None = None,
+ note: str = "",
+) -> ProviderDefinition:
+ return ProviderDefinition(
+ id=access.provider,
+ dialect="anthropic",
+ adapter=AnthropicLM,
+ async_adapter=AsyncAnthropicLM,
+ access=access,
+ compat=compat,
+ console_url=console_url,
+ note=note,
+ )
+
+
+def _hosted(
+ access: AccessPolicy,
+ dialect: Dialect,
+ adapter: type,
+ async_adapter: type,
+ *,
+ compat: str | None = None,
+ console_url: str | None = None,
+ note: str = "",
+) -> ProviderDefinition:
+ """A cloud door: an existing dialect behind a host (changes/2026-09-03-cloud-hosts.md).
+ Declared from documentation until its live receipt lands."""
+ return ProviderDefinition(
+ id=access.provider,
+ dialect=dialect,
+ adapter=adapter,
+ async_adapter=async_adapter,
+ access=access,
+ compat=compat,
+ console_url=console_url,
+ note=note,
+ )
+
+
+# Declaration order is presentation order (docs tables, `known providers`
+# lists are sorted separately). Adapter-owned entries first, then the
+# chat-bound services, then the keyless local servers.
+_DEFINITIONS: tuple[ProviderDefinition, ...] = (
+ _adapter_owned(
+ "openai", "openai-responses", OpenAILM, AsyncOpenAILM,
+ console_url="https://platform.openai.com/api-keys",
+ note="OpenAI Responses API",
+ ),
+ _adapter_owned(
+ "openai-chat", "openai-chat", OpenAIChatLM, AsyncOpenAIChatLM,
+ console_url="https://platform.openai.com/api-keys",
+ note="OpenAI Chat Completions dialect (the de-facto standard other servers speak)",
+ ),
+ _adapter_owned(
+ "anthropic", "anthropic", AnthropicLM, AsyncAnthropicLM,
+ console_url="https://console.anthropic.com",
+ note="Anthropic Messages API",
+ ),
+ _adapter_owned(
+ "gemini", "gemini", GeminiLM, AsyncGeminiLM,
+ console_url="https://aistudio.google.com/apikey",
+ note="Google Gemini API",
+ ),
+ _adapter_owned(
+ "xai", "openai-chat", XaiLM, AsyncXaiLM,
+ console_url="https://console.x.ai",
+ note="xAI Grok (Chat Completions dialect; XAI_API_KEY or subscription OAuth)",
+ ),
+ _adapter_owned(
+ "claude-code", "anthropic", ClaudeCodeLM, AsyncClaudeCodeLM,
+ note="Claude subscription through the local `claude` CLI login",
+ ),
+ _adapter_owned(
+ "openai-codex", "openai-responses", OpenAICodexLM, AsyncOpenAICodexLM,
+ note="ChatGPT subscription through the local `codex` CLI login",
+ ),
+ _chat_bound(
+ _access.GROQ,
+ console_url="https://console.groq.com/keys",
+ note="Groq Cloud (Chat Completions dialect)",
+ ),
+ _chat_bound(
+ _access.OPENROUTER,
+ console_url="https://openrouter.ai/keys",
+ note="OpenRouter (Chat Completions dialect)",
+ ),
+ _chat_bound(
+ _access.DEEPSEEK,
+ console_url="https://platform.deepseek.com/api_keys",
+ note="DeepSeek (Chat Completions dialect; thinking mode on by default)",
+ ),
+ _anthropic_bound(
+ _access.DEEPSEEK_ANTHROPIC,
+ compat="deepseek",
+ console_url="https://platform.deepseek.com/api_keys",
+ note="DeepSeek over the Anthropic Messages wire (same key as `deepseek`; no model listing)",
+ ),
+ _chat_bound(
+ _access.ZAI,
+ console_url="https://z.ai/manage-apikey/apikey-list",
+ note="Z.AI GLM (Chat Completions dialect; general endpoint, not the Coding Plan)",
+ ),
+ _chat_bound(
+ _access.MOONSHOTAI,
+ console_url="https://platform.kimi.ai/console/api-keys",
+ note="Moonshot AI Kimi (Chat Completions dialect; kimi-k3 takes reasoning effort low|high|max, kimi-k2.6 takes effort off; "
+ "Moonshot's docs call the key MOONSHOT_API_KEY — read after MOONSHOTAI_API_KEY)",
+ ),
+ _responses_bound(
+ _access.MOONSHOTAI_RESPONSES,
+ compat="moonshotai",
+ console_url="https://platform.kimi.ai/console/api-keys",
+ note="Moonshot AI Kimi over the Responses wire (same key as `moonshotai`; kimi-k3 only; stateless — reasoning replays as summary text; web_search built-in)",
+ ),
+ _anthropic_bound(
+ _access.MOONSHOTAI_ANTHROPIC,
+ compat="moonshotai",
+ console_url="https://platform.kimi.ai/console/api-keys",
+ note="Moonshot AI Kimi over the Anthropic Messages wire (same key as `moonshotai`, bearer token; kimi-k3 only)",
+ ),
+ _responses_bound(
+ _access.META,
+ compat="meta",
+ console_url="https://dev.meta.ai/",
+ note="Meta Model API — Muse Spark over the Responses wire (reasoning replay, web_search), plus Files, Images (muse-image-1.0) and Models; Meta's docs call the key MODEL_API_KEY — export it as META_API_KEY",
+ ),
+ _chat_bound(
+ _access.META_CHAT,
+ compat="meta",
+ console_url="https://dev.meta.ai/",
+ note="Meta Model API over the Chat Completions wire (same key as `meta`; no cross-turn reasoning)",
+ ),
+ _anthropic_bound(
+ _access.META_ANTHROPIC,
+ compat="meta",
+ console_url="https://dev.meta.ai/",
+ note="Meta Model API over the Anthropic Messages wire (same key as `meta`; bearer token)",
+ ),
+ # ─── Cloud hosts (documentation-evidenced; changes/2026-09-03-cloud-hosts.md) ───
+ _hosted(
+ _access.AZURE, "openai-responses", OpenAILM, AsyncOpenAILM,
+ console_url="https://portal.azure.com/",
+ note="Azure OpenAI v1 Responses wire ({resource}.openai.azure.com; model = deployment name; api-key or Entra token)",
+ ),
+ _hosted(
+ _access.AZURE_CHAT, "openai-chat", OpenAIChatLM, AsyncOpenAIChatLM, compat="openai",
+ console_url="https://portal.azure.com/",
+ note="Azure OpenAI v1 Chat Completions wire (same resource; also Foundry-sold models such as DeepSeek and Grok)",
+ ),
+ _hosted(
+ _access.AZURE_ANTHROPIC, "anthropic", AnthropicLM, AsyncAnthropicLM,
+ console_url="https://ai.azure.com/",
+ note="Claude in Microsoft Foundry ({resource}.services.ai.azure.com/anthropic; api-key, x-api-key or Entra token)",
+ ),
+ _hosted(
+ _access.AWS_ANTHROPIC, "anthropic", AnthropicLM, AsyncAnthropicLM,
+ console_url="https://console.aws.amazon.com/",
+ note="Claude Platform on AWS (Anthropic-operated; SigV4 or ANTHROPIC_AWS_API_KEY; needs AWS_REGION and ANTHROPIC_AWS_WORKSPACE_ID)",
+ ),
+ _hosted(
+ _access.BEDROCK_ANTHROPIC, "anthropic", AnthropicLM, AsyncAnthropicLM,
+ console_url="https://console.aws.amazon.com/bedrock/",
+ note="Claude in Amazon Bedrock (bedrock-mantle, Opus 4.7 and later; SigV4 or AWS_BEARER_TOKEN_BEDROCK; needs AWS_REGION)",
+ ),
+ _hosted(
+ _access.BEDROCK_CHAT, "openai-chat", OpenAIChatLM, AsyncOpenAIChatLM, compat="bedrock",
+ console_url="https://console.aws.amazon.com/bedrock/",
+ note="Amazon Bedrock over the OpenAI Chat Completions wire (bedrock-runtime /openai/v1; SigV4 or AWS_BEARER_TOKEN_BEDROCK)",
+ ),
+ _hosted(
+ _access.BEDROCK_MANTLE_CHAT, "openai-chat", OpenAIChatLM, AsyncOpenAIChatLM, compat="bedrock-mantle",
+ console_url="https://console.aws.amazon.com/bedrock/",
+ note="Amazon Bedrock Chat Completions on bedrock-mantle (un-versioned ids, GET /v1/models; SigV4 or AWS_BEARER_TOKEN_BEDROCK)",
+ ),
+ _hosted(
+ _access.VERTEX, "gemini", GeminiLM, AsyncGeminiLM,
+ console_url="https://console.cloud.google.com/vertex-ai",
+ note="Gemini on Google Cloud (Agent Platform); ADC chain; needs GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION defaults to global",
+ ),
+ _hosted(
+ _access.VERTEX_EXPRESS, "gemini", GeminiLM, AsyncGeminiLM,
+ console_url="https://console.cloud.google.com/vertex-ai/studio",
+ note="Agent Platform express mode: GOOGLE_API_KEY as ?key=, no project or location",
+ ),
+ _hosted(
+ _access.VERTEX_ANTHROPIC, "anthropic", AnthropicLM, AsyncAnthropicLM,
+ console_url="https://console.cloud.google.com/vertex-ai/model-garden",
+ note="Claude on Google Cloud (rawPredict; model in the path, anthropic_version in the body)",
+ ),
+ _chat_bound(_access.OLLAMA, placeholder_key="ollama", note="local ollama server (keyless)"),
+ _chat_bound(_access.VLLM, placeholder_key="EMPTY", note="local vLLM server (keyless)"),
+ _chat_bound(_access.SGLANG, placeholder_key="EMPTY", note="local SGLang server (keyless)"),
+)
+
+PROVIDERS: Mapping[str, ProviderDefinition] = MappingProxyType({d.id: d for d in _DEFINITIONS})
+
+
+def lookup(name: str) -> ProviderDefinition | None:
+ """The definition for a provider string in either spelling, or None."""
+ return PROVIDERS.get(canonical_provider(name))
diff --git a/dspy/_vendor/lm15/result.py b/dspy/_vendor/lm15/result.py
new file mode 100644
index 000000000..beaffaa31
--- /dev/null
+++ b/dspy/_vendor/lm15/result.py
@@ -0,0 +1,810 @@
+"""
+lm15.result — Stream materialization.
+
+One engine and two skins, all speaking the canonical StreamEvent
+vocabulary:
+
+- ``StreamAccumulator`` — the push-based engine. Feed it events, ask it
+ for the ``Response``. It is the shape every port shares (Rust/Go/TS
+ have no generators) and the only place accumulation logic lives.
+- ``ResponseStream`` / ``AsyncResponseStream`` — lazy iteration sugar
+ over a live stream: iterate for text as it arrives, ``.events()`` for
+ the canonical typed events, ``.response`` afterwards for the same
+ Response a non-streaming call returns.
+- ``materialize_response`` / ``amaterialize_response`` — the one-shot
+ functional form.
+
+Nothing here executes anything: tool calls are surfaced as data, and
+any execute-tools-until-done loop belongs to the layer above lm15.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field, replace
+from typing import Any, AsyncIterator, Iterator
+
+from .errors import LM15Error, error_class_for_code
+from .types import (
+ AudioDelta,
+ AudioPart,
+ CitationDelta,
+ CitationPart,
+ ContinuationDelta,
+ ContinuationState,
+ ErrorDetail,
+ ImageDelta,
+ ImagePart,
+ JsonObject,
+ Message,
+ Part,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamEvent,
+ StreamStartEvent,
+ TextDelta,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ TokenLogprob,
+ ToolCallDelta,
+ ToolCallPart,
+ Usage,
+)
+
+__all__ = [
+ "StreamAccumulator",
+ "ResponseStream",
+ "AsyncResponseStream",
+ "materialize_response",
+ "amaterialize_response",
+ "response_to_events",
+ "coalesce_stream",
+ "acoalesce_stream",
+]
+
+
+@dataclass(slots=True)
+class StreamAccumulator:
+ """Accumulates canonical stream events into a complete Response.
+
+ Push-based so that sync iteration, async iteration, and one-shot
+ materialization all share the same accumulation logic:
+
+ acc = StreamAccumulator(request)
+ for event in lm.stream(request):
+ acc.push(event)
+ response = acc.response()
+
+ ``push`` ignores error events — deciding whether to raise is the
+ caller's job (``ResponseStream`` raises; a resumption layer might
+ not). ``response()`` materializes whatever has been accumulated so
+ far; callers normally push through the end event first.
+ """
+
+ request: Request
+ started_id: str | None = None
+ started_model: str | None = None
+ finish_reason: str | None = None
+ usage: Usage | None = None
+ text_parts: dict[int, list[str]] = field(default_factory=dict)
+ thinking_parts: dict[int, list[str]] = field(default_factory=dict)
+ audio_chunks: dict[int, list[str]] = field(default_factory=dict)
+ audio_media_types: dict[int, str | None] = field(default_factory=dict)
+ image_parts: dict[int, ImagePart] = field(default_factory=dict)
+ citation_parts: dict[int, list[CitationPart]] = field(default_factory=dict)
+ tool_call_raw: dict[int, str] = field(default_factory=dict)
+ tool_call_meta: dict[int, dict[str, Any]] = field(default_factory=dict)
+ message_continuation: list[ContinuationState] = field(default_factory=list)
+ part_continuation: dict[int, list[ContinuationState]] = field(default_factory=dict)
+ logprob_seq: list[TokenLogprob] = field(default_factory=list)
+ provider_data: dict[str, Any] | None = None
+
+ def push(self, event: StreamEvent) -> None:
+ """Fold one canonical stream event into the accumulated state."""
+ if event.type == "start":
+ self.started_id = event.id or self.started_id
+ self.started_model = event.model or self.started_model
+ return
+
+ if event.type == "end":
+ self.finish_reason = event.finish_reason or self.finish_reason
+ self.usage = event.usage or self.usage
+ if event.provider_data is not None:
+ self.provider_data = event.provider_data
+ return
+
+ if event.type != "delta" or event.delta is None:
+ return
+
+ delta = event.delta
+
+ if delta.type == "text":
+ self.text_parts.setdefault(delta.part_index, []).append(delta.text or "")
+ if delta.logprobs:
+ self.logprob_seq.extend(delta.logprobs)
+
+ elif delta.type == "thinking":
+ self.thinking_parts.setdefault(delta.part_index, []).append(delta.text or "")
+
+ elif delta.type == "audio":
+ self.audio_chunks.setdefault(delta.part_index, []).append(delta.data or "")
+ self.audio_media_types.setdefault(delta.part_index, delta.media_type)
+
+ elif delta.type == "tool_call":
+ idx = delta.part_index
+ meta = self.tool_call_meta.setdefault(idx, {})
+ if delta.id is not None:
+ meta["id"] = str(delta.id)
+ if delta.name is not None:
+ meta["name"] = str(delta.name)
+ aggregate = self.tool_call_raw.get(idx, "") + delta.input
+ self.tool_call_raw[idx] = aggregate
+ meta["input"] = _parse_json_best_effort(aggregate)
+
+ elif delta.type == "image":
+ mt = delta.media_type or "image/png"
+ if delta.data is not None:
+ part = ImagePart(media_type=mt, data=str(delta.data))
+ elif delta.url is not None:
+ part = ImagePart(media_type=mt, url=str(delta.url))
+ elif delta.file_id is not None:
+ part = ImagePart(media_type=mt, file_id=str(delta.file_id))
+ else:
+ return
+ self.image_parts[delta.part_index] = part
+
+ elif delta.type == "citation":
+ self.citation_parts.setdefault(delta.part_index, []).append(CitationPart(
+ text=delta.text, url=delta.url, title=delta.title,
+ ))
+
+ elif delta.type == "continuation":
+ state = delta.to_state()
+ if delta.part_index is None:
+ self.message_continuation.append(state)
+ else:
+ self.part_continuation.setdefault(delta.part_index, []).append(state)
+
+ def response(self) -> Response:
+ """Build a complete Response from the accumulated state.
+
+ Raises :class:`StreamAssemblyError` when a tool call's fragments
+ never carried a name (MAP-9): the error carries everything else
+ that did assemble as ``partial``.
+ """
+ unnamed = sorted(
+ idx for idx, meta in self.tool_call_meta.items() if not meta.get("name")
+ )
+ if unnamed:
+ partial = self._assemble(skip=frozenset(unnamed))
+ from .errors import StreamAssemblyError
+
+ raise StreamAssemblyError(
+ f"tool call at part {unnamed[0]} arrived without a name; the adapter "
+ "that produced this stream must set ToolCallDelta.name on the call's "
+ "first fragment (MAP-9: lm15 does not guess which tool the model meant)",
+ partial=partial,
+ part_index=unnamed[0],
+ )
+ return self._assemble(skip=frozenset())
+
+ def _assemble(self, *, skip: frozenset[int]) -> Response:
+ parts: list[Part] = []
+
+ part_indexes = sorted(
+ set(self.thinking_parts)
+ | set(self.text_parts)
+ | set(self.image_parts)
+ | set(self.audio_chunks)
+ | set(self.citation_parts)
+ | set(self.tool_call_meta)
+ | set(self.part_continuation)
+ )
+
+ for idx in part_indexes:
+ continuation = tuple(self.part_continuation.get(idx, ()))
+ has_tool = idx in self.tool_call_meta and idx not in skip
+ if idx in self.thinking_parts:
+ parts.append(ThinkingPart(text="".join(self.thinking_parts[idx]), continuation=continuation))
+ if idx in self.text_parts:
+ parts.append(TextPart(text="".join(self.text_parts[idx]), continuation=continuation))
+ if idx in self.image_parts:
+ parts.append(replace(self.image_parts[idx], continuation=continuation))
+ if idx in self.audio_chunks:
+ raw_data = _concat_b64_chunks(self.audio_chunks[idx])
+ media_type = self.audio_media_types.get(idx)
+ from .types import audio as make_audio
+ if media_type in (None, "audio/pcm", "audio/pcm16"):
+ parts.append(make_audio(data=_pcm_to_wav(raw_data), media_type="audio/wav", continuation=continuation))
+ else:
+ parts.append(make_audio(data=raw_data, media_type=media_type, continuation=continuation))
+ if idx in self.citation_parts:
+ parts.extend(replace(part, continuation=continuation) for part in self.citation_parts[idx])
+ if has_tool:
+ meta = self.tool_call_meta[idx]
+ payload = meta.get("input")
+ if not isinstance(payload, dict):
+ payload = _parse_json_best_effort(self.tool_call_raw.get(idx, ""))
+ # A missing id gets an lm15-minted correlator (Gemini sends
+ # none); a missing name is never minted — see response().
+ tc_id = str(meta.get("id") or f"tool_call_{idx}")
+ parts.append(ToolCallPart(id=tc_id, name=str(meta["name"]), input=payload, continuation=continuation))
+ elif (
+ idx not in skip
+ and idx not in self.thinking_parts
+ and idx not in self.text_parts
+ and idx not in self.image_parts
+ and idx not in self.audio_chunks
+ and idx not in self.citation_parts
+ ):
+ parts.append(TextPart(text="", continuation=continuation))
+
+ if not parts:
+ parts = [TextPart(text="")]
+
+ finish = self.finish_reason
+ has_tool_calls = any(isinstance(p, ToolCallPart) for p in parts)
+ if finish is None:
+ finish = "tool_call" if has_tool_calls else "stop"
+ elif finish == "stop" and has_tool_calls:
+ finish = "tool_call"
+
+ return Response(
+ id=self.started_id,
+ model=self.started_model or self.request.model,
+ message=Message(role="assistant", parts=tuple(parts), continuation=tuple(self.message_continuation)),
+ finish_reason=finish,
+ usage=self.usage or Usage(),
+ logprobs=tuple(self.logprob_seq) if self.logprob_seq else None,
+ provider_data=self.provider_data,
+ )
+
+
+class ResponseStream:
+ """Lazy stream-backed response assembler.
+
+ rs = ResponseStream(lm.stream(request), request)
+ for text in rs: # text as it arrives
+ print(text, end="")
+ rs.response # the same Response complete() returns
+
+ ``rs.events()`` yields the canonical StreamEvents instead — one
+ vocabulary for raw and assembled streaming. Accessors mirror
+ Response's own minimal set; everything richer is
+ ``rs.response.message.first(...)`` / ``.parts_of(...)``.
+
+ Tool calls are surfaced as data only; ResponseStream never executes
+ anything.
+ """
+
+ def __init__(self, events: Iterator[StreamEvent], request: Request) -> None:
+ self._accumulator = StreamAccumulator(request)
+ self._source = events
+ self._response: Response | None = None
+ self._failure: BaseException | None = None
+ self._done = False
+ self._source_closed = False
+ self._event_iter = self._pump()
+
+ def _close_source(self) -> None:
+ if not self._source_closed:
+ self._source_closed = True
+ close = getattr(self._source, "close", None)
+ if close is not None:
+ close()
+
+ def close(self) -> None:
+ """Stop reading and release the source, without draining it.
+
+ An unfinished stream has no complete response. Closing does not
+ promise that the provider stops generating or billing immediately.
+ """
+ if not self._done and self._response is None and self._failure is None:
+ self._failure = RuntimeError("stream closed before completion")
+ try:
+ self._event_iter.close()
+ finally:
+ self._done = True
+ self._close_source()
+
+ def __enter__(self) -> "ResponseStream":
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ self.close()
+
+ def __iter__(self) -> Iterator[str]:
+ for event in self.events():
+ if event.type == "delta" and event.delta is not None:
+ if event.delta.type == "text" and event.delta.text is not None:
+ yield event.delta.text
+
+ def events(self) -> Iterator[StreamEvent]:
+ """Canonical stream events, teed through the accumulator."""
+ while True:
+ try:
+ yield next(self._event_iter)
+ except StopIteration:
+ return
+
+ @property
+ def text(self) -> str | None:
+ return self.response.text
+
+ @property
+ def tool_calls(self) -> list[ToolCallPart]:
+ return self.response.tool_calls
+
+ @property
+ def citations(self) -> list[CitationPart]:
+ return self.response.citations
+
+ @property
+ def usage(self) -> Usage:
+ return self.response.usage
+
+ @property
+ def finish_reason(self) -> str:
+ return self.response.finish_reason
+
+ @property
+ def model(self) -> str:
+ return self.response.model
+
+ @property
+ def json(self) -> Any:
+ return self.response.json
+
+ @property
+ def response(self) -> Response:
+ if self._failure is not None:
+ raise self._failure
+ if not self._done:
+ for _ in self.events():
+ pass
+ if self._failure is not None: # pragma: no cover - pump raises first
+ raise self._failure
+ assert self._response is not None
+ return self._response
+
+ def _pump(self) -> Iterator[StreamEvent]:
+ try:
+ for event in self._source:
+ if event.type == "error":
+ self._failure = _exception_from_error(event)
+ raise self._failure
+ self._accumulator.push(event)
+ if event.type == "end":
+ self._response = self._accumulator.response()
+ self._done = True
+ yield event
+ return
+ yield event
+ self._response = self._accumulator.response()
+ except BaseException as exc:
+ if self._failure is None and self._response is None:
+ self._failure = exc
+ raise
+ finally:
+ self._done = True
+ self._close_source()
+
+
+class AsyncResponseStream:
+ """Async mirror of :class:`ResponseStream`, same accumulator engine.
+
+ rs = AsyncResponseStream(lm.stream(request), request)
+ async for text in rs:
+ print(text, end="")
+ response = await rs.response()
+
+ ``response()`` is a method (it may need to consume the stream, which
+ is an awaitable operation in async code).
+ """
+
+ def __init__(self, events: AsyncIterator[StreamEvent], request: Request) -> None:
+ self._accumulator = StreamAccumulator(request)
+ self._source = events
+ self._response: Response | None = None
+ self._failure: BaseException | None = None
+ self._done = False
+ self._source_closed = False
+ self._event_gen = self._pump()
+
+ async def _close_source(self) -> None:
+ if not self._source_closed:
+ self._source_closed = True
+ close = getattr(self._source, "aclose", None)
+ if close is not None:
+ await close()
+
+ async def aclose(self) -> None:
+ """Stop reading and release the source, without draining it."""
+ if not self._done and self._response is None and self._failure is None:
+ self._failure = RuntimeError("stream closed before completion")
+ try:
+ await self._event_gen.aclose()
+ finally:
+ self._done = True
+ await self._close_source()
+
+ async def __aenter__(self) -> "AsyncResponseStream":
+ return self
+
+ async def __aexit__(self, *_exc: Any) -> None:
+ await self.aclose()
+
+ def __aiter__(self) -> AsyncIterator[str]:
+ return self._text_iter()
+
+ async def _text_iter(self) -> AsyncIterator[str]:
+ async for event in self.events():
+ if event.type == "delta" and event.delta is not None:
+ if event.delta.type == "text" and event.delta.text is not None:
+ yield event.delta.text
+
+ async def events(self) -> AsyncIterator[StreamEvent]:
+ """Canonical stream events, teed through the accumulator."""
+ async for event in self._event_gen:
+ yield event
+
+ async def response(self) -> Response:
+ if self._failure is not None:
+ raise self._failure
+ if not self._done:
+ async for _ in self.events():
+ pass
+ if self._failure is not None: # pragma: no cover - pump raises first
+ raise self._failure
+ assert self._response is not None
+ return self._response
+
+ async def _pump(self) -> AsyncIterator[StreamEvent]:
+ try:
+ async for event in self._source:
+ if event.type == "error":
+ self._failure = _exception_from_error(event)
+ raise self._failure
+ self._accumulator.push(event)
+ if event.type == "end":
+ self._response = self._accumulator.response()
+ self._done = True
+ yield event
+ return
+ yield event
+ self._response = self._accumulator.response()
+ except BaseException as exc:
+ if self._failure is None and self._response is None:
+ self._failure = exc
+ raise
+ finally:
+ self._done = True
+ await self._close_source()
+
+
+# ─── One-shot materialization ────────────────────────────────────────
+
+def materialize_response(events: Iterator[StreamEvent], request: Request) -> Response:
+ """Consume stream events and build a complete Response."""
+ accumulator = StreamAccumulator(request)
+ for event in events:
+ if event.type == "error":
+ raise _exception_from_error(event)
+ accumulator.push(event)
+ if event.type == "end":
+ break
+ return accumulator.response()
+
+
+async def amaterialize_response(events: AsyncIterator[StreamEvent], request: Request) -> Response:
+ """Async mirror of :func:`materialize_response`."""
+ accumulator = StreamAccumulator(request)
+ async for event in events:
+ if event.type == "error":
+ raise _exception_from_error(event)
+ accumulator.push(event)
+ if event.type == "end":
+ break
+ return accumulator.response()
+
+
+# ─── Conversion utilities ────────────────────────────────────────────
+
+def response_to_events(response: Response) -> Iterator[StreamEvent]:
+ """Convert a complete Response to stream events.
+
+ The conversion is intentionally lossless for the Delta vocabulary. If a
+ response contains a valid Part that has no Delta representation, this
+ function raises instead of silently dropping content.
+ """
+ yield StreamStartEvent(id=response.id, model=response.model)
+ # Response.logprobs is message-level; the delta vocabulary carries
+ # logprobs on text deltas. Emitting the whole sequence on the first
+ # text delta makes Response -> events -> Response lossless.
+ pending_logprobs = response.logprobs or ()
+ for idx, part in enumerate(response.message.parts):
+ if isinstance(part, TextPart):
+ yield StreamDeltaEvent(delta=TextDelta(text=part.text, part_index=idx, logprobs=pending_logprobs))
+ pending_logprobs = ()
+ elif isinstance(part, ThinkingPart):
+ yield StreamDeltaEvent(delta=ThinkingDelta(text=part.text, part_index=idx))
+ elif isinstance(part, ToolCallPart):
+ yield StreamDeltaEvent(
+ delta=ToolCallDelta(
+ input=json.dumps(part.input),
+ part_index=idx,
+ id=part.id,
+ name=part.name,
+ )
+ )
+ elif isinstance(part, ImagePart):
+ yield StreamDeltaEvent(
+ delta=ImageDelta(
+ part_index=idx,
+ data=part.data,
+ url=part.url,
+ file_id=part.file_id,
+ media_type=part.media_type,
+ )
+ )
+ elif isinstance(part, AudioPart):
+ if part.data is None:
+ _raise_non_streamable_part(
+ part,
+ reason="AudioDelta only supports inline data",
+ )
+ yield StreamDeltaEvent(
+ delta=AudioDelta(
+ data=part.data,
+ part_index=idx,
+ media_type=part.media_type,
+ )
+ )
+ elif isinstance(part, CitationPart):
+ yield StreamDeltaEvent(
+ delta=CitationDelta(
+ text=part.text,
+ url=part.url,
+ title=part.title,
+ part_index=idx,
+ )
+ )
+ else:
+ _raise_non_streamable_part(part)
+ for state in part.continuation:
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider=state.provider,
+ kind=state.kind,
+ data=state.data,
+ part_index=idx,
+ )
+ )
+ for state in response.message.continuation:
+ yield StreamDeltaEvent(
+ delta=ContinuationDelta(
+ provider=state.provider,
+ kind=state.kind,
+ data=state.data,
+ part_index=None,
+ )
+ )
+ yield StreamEndEvent(
+ finish_reason=response.finish_reason,
+ usage=response.usage,
+ provider_data=response.provider_data,
+ )
+
+
+class _EndProviderData:
+ """MAP-3 / D9: which adapter end event's ``provider_data`` the merged
+ end carries. Rank 2: a frame that supplied usage. Rank 1: a frame that
+ supplied finish_reason. Rank 0: anything else that carried data. A
+ later frame replaces an earlier one only at the same or a higher rank,
+ so the usage frame wins over a finish-only frame in either order."""
+
+ __slots__ = ("value", "rank")
+
+ def __init__(self) -> None:
+ self.value: dict[str, Any] | None = None
+ self.rank = -1
+
+ def absorb(self, event: StreamEndEvent) -> None:
+ if event.provider_data is None:
+ return
+ rank = 2 if event.usage is not None else 1 if event.finish_reason is not None else 0
+ if rank >= self.rank:
+ self.value = event.provider_data
+ self.rank = rank
+
+
+def coalesce_stream(
+ events: Iterator[StreamEvent], *, model: str | None = None
+) -> Iterator[StreamEvent]:
+ """Enforce MAP-3 and MAP-4: one final StreamEndEvent, one leading StreamStartEvent.
+
+ Adapters are stateless and may emit one end event per provider terminal
+ frame (finish_reason chunk, usage-only chunk, ``[DONE]``,
+ ``message_delta`` + ``message_stop``). This wrapper passes delta and
+ error events through unchanged, absorbs every end event's fields —
+ a later non-None field replaces the accumulated value, a None field never
+ erases one — and emits the single merged end event once the underlying
+ iterator is exhausted. If no end event was seen (e.g. the stream errored
+ or was truncated), no end event is fabricated. ``provider_data`` follows
+ D9 (2026-09-06): the merged end carries the frame that supplied usage,
+ else the frame that supplied finish_reason; a later usage-bearing frame
+ replaces an earlier one, a finish-only frame never displaces a usage
+ frame.
+
+ Dialects without a start frame (chat completions, gemini SSE) get a
+ synthesized ``StreamStartEvent`` before the first delta or end event, so
+ every successful stream reads start → deltas → end (MAP-4). A provider
+ start passes through; duplicates after the first are dropped. Error
+ events never force a start: a stream that fails to open has no start.
+
+ See docs/mapping-rules.md MAP-3 and MAP-4.
+ """
+ try:
+ yield from _coalesce_stream(events, model=model)
+ finally:
+ close = getattr(events, "close", None)
+ if close is not None:
+ close()
+
+
+def _coalesce_stream(events: Iterator[StreamEvent], *, model: str | None) -> Iterator[StreamEvent]:
+ started = False
+ saw_end = False
+ finish_reason = None
+ usage: Usage | None = None
+ end_data = _EndProviderData()
+ for event in events:
+ if event.type == "start":
+ if started:
+ continue
+ started = True
+ yield event
+ continue
+ if event.type == "end":
+ saw_end = True
+ if event.finish_reason is not None:
+ finish_reason = event.finish_reason
+ if event.usage is not None:
+ usage = event.usage
+ end_data.absorb(event)
+ continue
+ if not started and event.type == "delta":
+ started = True
+ yield StreamStartEvent(model=model)
+ yield event
+ if saw_end:
+ if not started:
+ yield StreamStartEvent(model=model)
+ yield StreamEndEvent(
+ finish_reason=finish_reason,
+ usage=usage,
+ provider_data=end_data.value,
+ )
+
+
+async def acoalesce_stream(
+ events: "AsyncIterator[StreamEvent]", *, model: str | None = None
+) -> "AsyncIterator[StreamEvent]":
+ """Async mirror of :func:`coalesce_stream` — same MAP-3/MAP-4 semantics.
+
+ Passes delta/error events through unchanged, absorbs every end
+ event's fields (later non-None replaces, None never erases), and emits
+ exactly one merged final StreamEndEvent once the source is exhausted.
+ No end event is fabricated if none was seen. Synthesizes one leading
+ StreamStartEvent for dialects without a start frame; duplicate starts
+ are dropped; error events never force a start.
+ """
+ try:
+ async for event in _acoalesce_stream(events, model=model):
+ yield event
+ finally:
+ close = getattr(events, "aclose", None)
+ if close is not None:
+ await close()
+
+
+async def _acoalesce_stream(events: AsyncIterator[StreamEvent], *, model: str | None) -> AsyncIterator[StreamEvent]:
+ started = False
+ saw_end = False
+ finish_reason = None
+ usage: Usage | None = None
+ end_data = _EndProviderData()
+ async for event in events:
+ if event.type == "start":
+ if started:
+ continue
+ started = True
+ yield event
+ continue
+ if event.type == "end":
+ saw_end = True
+ if event.finish_reason is not None:
+ finish_reason = event.finish_reason
+ if event.usage is not None:
+ usage = event.usage
+ end_data.absorb(event)
+ continue
+ if not started and event.type == "delta":
+ started = True
+ yield StreamStartEvent(model=model)
+ yield event
+ if saw_end:
+ if not started:
+ yield StreamStartEvent(model=model)
+ yield StreamEndEvent(
+ finish_reason=finish_reason,
+ usage=usage,
+ provider_data=end_data.value,
+ )
+
+
+# ─── Internal helpers ────────────────────────────────────────────────
+
+def _raise_non_streamable_part(part: Part, *, reason: str | None = None) -> None:
+ detail = reason or f"no {part.type!r} Delta variant exists"
+ raise TypeError(f"Cannot convert {type(part).__name__} to StreamEvent: {detail}")
+
+
+def _exception_from_error(event: StreamEvent) -> Exception:
+ err = event.error or ErrorDetail(code="provider", message="stream error")
+ code = err.code
+ message = err.message
+ exc_cls = error_class_for_code(code)
+ if issubclass(exc_cls, LM15Error):
+ return exc_cls(message, provider_code=err.provider_code)
+ return exc_cls(message)
+
+
+def _concat_b64_chunks(chunks: list[str]) -> bytes:
+ """Decode each base64 chunk and concatenate raw bytes."""
+ import base64
+ raw = bytearray()
+ for chunk in chunks:
+ if not chunk:
+ continue
+ try:
+ raw.extend(base64.b64decode(chunk))
+ except Exception:
+ padded = chunk + "=" * (-len(chunk) % 4)
+ try:
+ raw.extend(base64.b64decode(padded))
+ except Exception:
+ pass
+ return bytes(raw)
+
+
+def _pcm_to_wav(pcm: bytes, sample_rate: int = 24000, channels: int = 1, bits: int = 16) -> bytes:
+ """Wrap raw PCM bytes in a WAV header."""
+ import struct
+ byte_rate = sample_rate * channels * bits // 8
+ block_align = channels * bits // 8
+ data_size = len(pcm)
+ header = struct.pack(
+ "<4sI4s4sIHHIIHH4sI",
+ b"RIFF", 36 + data_size, b"WAVE", b"fmt ", 16, 1,
+ channels, sample_rate, byte_rate, block_align, bits,
+ b"data", data_size,
+ )
+ return header + pcm
+
+
+def _parse_json_best_effort(raw: str | None) -> JsonObject:
+ if not raw:
+ return {}
+ try:
+ value = json.loads(raw, parse_constant=_reject_json_constant)
+ return value if isinstance(value, dict) else {"value": value}
+ except Exception:
+ return {"partial_json": raw}
+
+
+def _reject_json_constant(value: str) -> None:
+ raise ValueError(f"non-standard JSON constant: {value}")
diff --git a/dspy/_vendor/lm15/router.py b/dspy/_vendor/lm15/router.py
new file mode 100644
index 000000000..75efc9ca8
--- /dev/null
+++ b/dspy/_vendor/lm15/router.py
@@ -0,0 +1,1010 @@
+"""
+lm15.router — Minimalist model-string router.
+
+The router is a lookup table you can read, not a framework. Four
+resolution rungs, in fixed order, with no configuration of the order
+itself:
+
+ 0. object attribute a ``provider`` attribute carried by the model
+ value itself -> source="object"
+ (catalog packages ship model ids as str
+ subclasses that know their provider; duck-typed —
+ lm15 names no package. An attribute that names
+ nothing routable falls through.)
+ 1. explicit prefix ``"openai:gpt-4.1-mini"`` -> source="prefix"
+ 2. catalog match against ``registry.list()`` -> source="catalog"
+ entries by id or alias; exact-id matches beat
+ alias matches; multiple providers (or multiple
+ same-provider entries) raise AmbiguousModelError
+ (only if you passed a registry; catalogs are
+ opt-in via ``ModelRegistry.discover()``)
+ 3. built-in rules ``DEFAULT_RULES`` prefix match -> source="rule"
+
+Nothing else. No plugins, no callbacks, no fallback chains.
+
+A provider is routable when the provider registry (``lm15.registry``)
+declares it: either adapter-owned (a key of :data:`ADAPTERS`) or
+chat-bound (a key of :data:`CHAT_PRESET_ROUTES`: groq, openrouter,
+deepseek, ollama, vllm, sglang). Chat-bound providers route to
+``OpenAIChatLM(compat=<preset>, access=<policy>)``: the preset names the
+server's quirks and default base_url, the access policy its credential.
+
+Model-string grammar
+--------------------
+A model string is split on the FIRST ``:``. If the head is a routable
+provider string, the remainder is the model id sent on the wire.
+Otherwise the whole string (colons and all) is treated as a bare model
+id and falls through to the catalog and rule rungs. Consequence: a
+fine-tune id like ``ft:gpt-4.1:org`` needs the explicit form
+``openai:ft:gpt-4.1:org``.
+
+Credentials
+-----------
+``resolve()`` touches no network and invokes no credential provider.
+It checks configured keys and environment presence, but its result records
+WHICH env var would be used, never the value. ``lm()``
+reads the key — first from ``RouterConfig.api_keys`` (explicit,
+repr-suppressed; values may be static strings or zero-argument
+credential-provider callables, resolved per request by the adapter),
+then from the env mapping via the provider's ``ProviderManifest.env_keys``
+or the preset's own convention (first hit wins), then a keyless local
+server's placeholder key. OAuth providers (``claude-code``,
+``openai-codex``) declare no env keys and pass through to their
+self-resolving constructors.
+
+The direct LM classes remain first-class; the router is just the
+recommended front door. Needing a custom ``base_url``/transport/compat
+(azure, a self-hosted gateway) is the documented escape hatch: ``lm()``
+returns the ordinary provider LM — keep it and configure it yourself
+next time.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field, replace
+from types import MappingProxyType
+from typing import AsyncIterator, Iterator, Literal, Mapping, overload
+
+from .result import AsyncResponseStream, ResponseStream
+
+from .errors import AmbiguousModelError, NotConfiguredError, UnknownModelError
+from .models import ModelInfo, ModelRegistry
+from .providers import Credential
+from .registry import PROVIDERS, ProviderDefinition, canonical_provider as _canonical_provider
+from .types import Request, Response, StreamEvent
+
+__all__ = [
+ "RouteRule",
+ "DEFAULT_RULES",
+ "ADAPTERS",
+ "ASYNC_ADAPTERS",
+ "PresetRoute",
+ "CHAT_PRESET_ROUTES",
+ "Resolution",
+ "RouterConfig",
+ "RouterError",
+ "UnknownModelError",
+ "AmbiguousModelError",
+ "MissingCredentialError",
+ "LMRouter",
+ "LITELLM_PROVIDER_PREFIXES",
+ "openai_chat_model_string",
+ "AsyncLMRouter",
+]
+
+
+# ---------------------------------------------------------------- rules ----
+
+
+@dataclass(frozen=True, slots=True)
+class RouteRule:
+ """Maps a model-id prefix to a provider. That's all a rule is.
+
+ ``note`` is a short human rationale surfaced in docs and
+ :meth:`Resolution.describe` output.
+ """
+
+ prefix: str
+ provider: str
+ note: str = ""
+
+
+# The complete built-in knowledge of the router. Inspectable, printable,
+# overridable by passing rules=... in RouterConfig. First match wins.
+# This table is a convenience, not a registry of truth: new model
+# families need a release (or a catalog, or the provider: prefix).
+DEFAULT_RULES: tuple[RouteRule, ...] = (
+ RouteRule("claude-", "anthropic", note="Anthropic Claude family"),
+ RouteRule("gpt-", "openai", note="OpenAI GPT family (Responses API; use openai-chat: for Chat Completions)"),
+ RouteRule("o1", "openai", note="OpenAI o1 reasoning family"),
+ RouteRule("o3", "openai", note="OpenAI o3 reasoning family"),
+ RouteRule("o4", "openai", note="OpenAI o4 reasoning family"),
+ RouteRule("gemini-", "gemini", note="Google Gemini family"),
+ RouteRule("gemma-", "gemini", note="Google Gemma open models, served by the Gemini API (live /models listing 2026-09-01)"),
+ RouteRule("nano-banana", "gemini", note="Google image models on the Gemini API (live /models listing 2026-09-01)"),
+ RouteRule("grok-", "xai", note="xAI Grok family (XAI_API_KEY or subscription OAuth)"),
+ RouteRule("sora-", "openai", note="OpenAI Sora video generation"),
+ RouteRule("veo-", "gemini", note="Google Veo video generation"),
+ RouteRule("chat-latest", "openai", note="OpenAI rolling chat alias (live /models listing 2026-09-01)"),
+)
+
+
+# provider string -> LM class. Read-only views of the provider registry
+# (lm15.registry.PROVIDERS): adapter-owned entries here, chat-bound
+# entries in CHAT_PRESET_ROUTES. Exported and inspectable, as before;
+# the registry is the one place a provider is declared.
+# Values are the *sync* classes; AsyncLMRouter uses ASYNC_ADAPTERS.
+ADAPTERS: Mapping[str, type] = MappingProxyType(
+ {d.id: d.adapter for d in PROVIDERS.values() if not d.bound}
+)
+
+ASYNC_ADAPTERS: Mapping[str, type] = MappingProxyType(
+ {d.id: d.async_adapter for d in PROVIDERS.values() if not d.bound}
+)
+
+
+def _definition(provider: str) -> ProviderDefinition | None:
+ return PROVIDERS.get(provider)
+
+
+def _credential_policy(provider: str, adapters: Mapping[str, type] | None = None) -> str:
+ """The provider's declared ``AccessPolicy.credential_policy``.
+
+ Read from the registry entry's access policy — for an adapter-owned
+ entry that is the class manifest; for a chat-bound entry the bound
+ policy (always ``"key"`` today). This is the single source the router
+ and doctor consult — there is deliberately no hardcoded provider-name
+ list that could drift from the declarations. ``adapters`` lets tests
+ substitute fake classes; a provider found there but not in the
+ registry answers with its class manifest.
+ """
+ definition = _definition(provider)
+ if definition is not None:
+ return definition.credential_policy
+ lookup = ADAPTERS if adapters is None else adapters
+ cls = lookup.get(provider)
+ if cls is None:
+ return "key"
+ return cls.manifest.credential_policy
+
+
+@dataclass(frozen=True, slots=True)
+class PresetRoute:
+ """A provider routable through ``OpenAIChatLM`` with a named compat
+ preset — the registry's chat-bound entry, projected to the fields this
+ table always carried. Pure data: the provider string doubles as the
+ preset name (which also supplies the server's default base_url);
+ ``env_keys`` is that server's own key convention; ``default_key`` is
+ the placeholder local servers accept when no key is configured."""
+
+ provider: str
+ env_keys: tuple[str, ...] = ()
+ default_key: str | None = None
+ note: str = ""
+
+
+# Chat Completions preset providers, keyed by provider string: the
+# chat-bound entries of the registry. Same spirit as DEFAULT_RULES — the
+# complete built-in knowledge, inspectable and printable. A new entry is
+# an AccessPolicy in lm15.access plus a registry declaration, landed with
+# live receipts first, like every provider behavior. Bound entries of
+# other dialects (deepseek-anthropic) are routable too; they are read from
+# the registry directly, not from this table.
+CHAT_PRESET_ROUTES: Mapping[str, PresetRoute] = MappingProxyType(
+ {
+ d.id: PresetRoute(d.id, env_keys=d.env_keys, default_key=d.placeholder_key, note=d.note)
+ for d in PROVIDERS.values()
+ if d.bound and d.dialect == "openai-chat"
+ }
+)
+
+
+def _bound(provider: str, adapters: Mapping[str, type]) -> ProviderDefinition | None:
+ """The registry's bound entry for ``provider``, or None when the provider
+ is adapter-owned (a key of ``adapters``) or unknown."""
+ if provider in adapters:
+ return None
+ definition = PROVIDERS.get(provider)
+ return definition if definition is not None and definition.bound else None
+
+
+def _routable(provider: str, adapters: Mapping[str, type]) -> bool:
+ return provider in adapters or _bound(provider, adapters) is not None
+
+
+def _adapter_for(provider: str, adapters: Mapping[str, type]) -> type:
+ if provider in adapters:
+ return adapters[provider]
+ definition = PROVIDERS[provider] # bound entry: its dialect class
+ return definition.async_adapter if adapters is ASYNC_ADAPTERS else definition.adapter
+
+
+def _bound_ids(adapters: Mapping[str, type]) -> set[str]:
+ return {d.id for d in PROVIDERS.values() if d.bound and d.id not in adapters}
+
+
+def _check_provider_keyed(config: RouterConfig, adapters: Mapping[str, type]) -> None:
+ """Every provider string a RouterConfig is keyed by (api_keys, base_urls,
+ settings) must name a routable provider. A near miss is named: an
+ entry that matches nothing is otherwise silently ignored, and the
+ request goes out on whatever the environment holds — the wrong
+ account, with nothing said (AUTH-1)."""
+ import difflib
+
+ known = sorted(set(adapters) | _bound_ids(adapters))
+ for field_name in ("api_keys", "base_urls", "settings"):
+ mapping = getattr(config, field_name)
+ if not mapping:
+ continue
+ seen: set[str] = set()
+ for key in mapping:
+ provider = _canonical_provider(key)
+ if field_name == "api_keys" and provider in seen:
+ raise NotConfiguredError(f"RouterConfig(api_keys=...): duplicate spellings for {provider!r}; use one entry")
+ seen.add(provider)
+ if provider in known:
+ continue
+ close = difflib.get_close_matches(provider, known, n=1, cutoff=0.6)
+ hint = f" Did you mean {close[0]!r}?" if close else ""
+ raise NotConfiguredError(
+ f"RouterConfig({field_name}=...): {key!r} is not a provider lm15 routes to.{hint} "
+ f"router.resolve(model).provider (or resolve_openai_chat) names the one a model "
+ f"string uses; known: {', '.join(known)}",
+ )
+
+
+# --------------------------------------------------------------- errors ----
+#
+# The router's failures are ErrorCode vocabulary entries (spec/vocabularies.md,
+# 2026-09-08): UnknownModelError / AmbiguousModelError live in lm15.errors
+# under ConfigurationError and are re-exported here. There is no router-wide
+# base class or code: a code names a failure the caller can act on, not the
+# component that raised it.
+
+
+class MissingCredentialError(NotConfiguredError):
+ """Provider resolved but no API key was found.
+
+ A :class:`lm15.errors.NotConfiguredError` (code ``not_configured``) —
+ semantically the credential case IS not-configured — so
+ ``except NotConfiguredError`` handlers keep working. Carries
+ ``provider`` and ``env_keys`` straight from the ProviderManifest.
+ """
+
+ default_code = "not_configured"
+
+
+# ----------------------------------------------------------- resolution ----
+
+
+@dataclass(frozen=True, slots=True)
+class Resolution:
+ """The complete answer to "how did you route this string".
+
+ ``resolve()`` returning this IS the explain() method — there is no
+ separate one.
+ """
+
+ requested: str # verbatim input string
+ model: str # id sent on the wire (prefix stripped)
+ provider: str # canonical provider string
+ adapter: str # LM class name, e.g. "AnthropicLM"
+ source: str # "object" | "prefix" | "catalog" | "rule"
+ rule: RouteRule | None = None # the matching rule when source == "rule"
+ env_key: str | None = None # env var the key would be read from;
+ # None for OAuth providers or when an
+ # explicit api_keys entry overrides env
+ model_info: ModelInfo | None = None # catalog metadata when source == "catalog"
+ compat: str | None = None # compat preset name when routed through
+ # a bound registry entry (CHAT_PRESET_ROUTES
+ # or an Anthropic-dialect binding)
+
+ def describe(self) -> str:
+ """One-paragraph human-readable explanation of this resolution."""
+ parts = [f"{self.requested!r} -> provider {self.provider!r} ({self.adapter})"]
+ if self.source == "object":
+ parts.append("via provider attribute on the model value")
+ elif self.source == "prefix":
+ parts.append("via explicit provider prefix")
+ elif self.source == "catalog":
+ parts.append("via catalog match")
+ elif self.source == "rule" and self.rule is not None:
+ note = f" — {self.rule.note}" if self.rule.note else ""
+ parts.append(f"via built-in rule prefix={self.rule.prefix!r}{note}")
+ if self.compat is not None:
+ parts.append(f"compat preset {self.compat!r}")
+ parts.append(f"wire model {self.model!r}")
+ definition = _bound(self.provider, ADAPTERS)
+ policy = _credential_policy(self.provider)
+ if policy == "oauth-unless-explicit":
+ # resolve() is pure (no file reads), so it describes the chain
+ # rather than asserting a winner.
+ chain = "key from explicit api_keys, else the stored subscription OAuth credential"
+ if self.env_key is not None:
+ chain += f", else ${self.env_key}"
+ parts.append(chain)
+ elif self.env_key is not None:
+ parts.append(f"key from ${self.env_key}")
+ elif policy == "oauth":
+ parts.append("local OAuth credential (no env key)")
+ elif definition is not None and definition.placeholder_key is not None:
+ parts.append("key from explicit api_keys or the preset's local-server default")
+ else:
+ parts.append("key from explicit api_keys")
+ return "; ".join(parts) + "."
+
+ def __str__(self) -> str:
+ return self.describe()
+
+
+# ---------------------------------------------------------------- config ----
+
+
+@dataclass(frozen=True, slots=True)
+class RouterConfig:
+ """Everything the router consults. All explicit, nothing discovered
+ behind your back. Catalog use is opt-in: pass
+ ``registry=ModelRegistry.discover()``.
+
+ ``api_keys`` maps provider string -> credential and beats env (repr-
+ suppressed; lets hermetic tests pass ``env={}``). A credential is a
+ static key string or a zero-argument provider callable, resolved per
+ request by the adapter. ``env`` defaults to ``os.environ`` at
+ lookup time. An exact provider entry wins; otherwise one entry for a
+ provider with the identical non-empty declared env-key tuple supplies
+ the credential (e.g. ``openai`` also covers ``openai-chat``). Multiple
+ shared candidates raise rather than guess an account. URLs and host
+ settings are never shared this way.
+
+ ``base_urls`` maps provider string -> the URL the provider's LM is
+ built with, replacing the adapter's (or the preset's) default: a
+ proxy in front of OpenAI, a vLLM server on another port. Not for
+ the cloud doors (azure, bedrock, vertex): their URL is derived from
+ ``settings`` (resource, region), and an entry for one is refused.
+ """
+
+ registry: ModelRegistry | None = None
+ rules: tuple[RouteRule, ...] = DEFAULT_RULES
+ env: Mapping[str, str] | None = None
+ api_keys: Mapping[str, Credential] | None = field(default=None, repr=False)
+ base_urls: Mapping[str, str] | None = field(default=None, kw_only=True)
+ # Cloud-host settings per provider (AUTH-10): {"bedrock-anthropic":
+ # {"region": "us-east-1"}}. A setting not given here is read from its
+ # env variables in order, then its default; region and resource have
+ # none and raise.
+ settings: Mapping[str, Mapping[str, str]] | None = field(default=None, kw_only=True)
+ transport: object | None = None # SyncTransport for LMRouter, AsyncTransport
+ # for AsyncLMRouter; passed to every LM the
+ # router constructs (tests, custom pooling)
+
+
+# ------------------------------------------------------------- internals ----
+
+
+def _resolution(
+ *,
+ requested: str,
+ wire_model: str,
+ provider: str,
+ source: str,
+ config: RouterConfig,
+ adapters: Mapping[str, type],
+ rule: RouteRule | None = None,
+ model_info: ModelInfo | None = None,
+) -> Resolution:
+ definition = _bound(provider, adapters)
+ return Resolution(
+ requested=requested,
+ model=wire_model,
+ provider=provider,
+ adapter=_adapter_for(provider, adapters).__name__,
+ source=source,
+ rule=rule,
+ env_key=_env_key_for(provider, config, adapters),
+ model_info=model_info,
+ compat=definition.compat if definition is not None else None,
+ )
+
+
+def _resolve(model: str, config: RouterConfig, adapters: Mapping[str, type]) -> Resolution:
+ if not isinstance(model, str) or not model:
+ raise UnknownModelError(
+ "model must be a non-empty string", model=str(model),
+ rules_tried=config.rules, catalog_searched=config.registry is not None,
+ )
+
+ requested = model
+
+ # Rung 0: a provider attribute carried by the model value itself.
+ # Catalog packages ship model ids as str subclasses that know their
+ # provider; duck-typed, so lm15 names no package. An attribute that
+ # names nothing routable falls through (and is mentioned if nothing
+ # else matches either).
+ object_provider = getattr(model, "provider", None)
+ if isinstance(object_provider, str) and object_provider:
+ object_provider = _canonical_provider(object_provider)
+ else:
+ object_provider = None
+ if object_provider is not None and _routable(object_provider, adapters):
+ return _resolution(
+ requested=requested,
+ wire_model=str(model),
+ provider=object_provider,
+ source="object",
+ config=config,
+ adapters=adapters,
+ )
+
+ # Rung 1: explicit provider prefix (split on FIRST colon).
+ if ":" in model:
+ raw_head, rest = model.split(":", 1)
+ head = _canonical_provider(raw_head)
+ if _routable(head, adapters) and rest:
+ return _resolution(
+ requested=requested,
+ wire_model=rest,
+ provider=head,
+ source="prefix",
+ config=config,
+ adapters=adapters,
+ )
+
+ # Rung 2: catalog (only if a registry was explicitly supplied).
+ if config.registry is not None:
+ matches = tuple(
+ info
+ for info in config.registry.list()
+ if info.id == model or model in info.aliases
+ )
+ providers = tuple(dict.fromkeys(info.provider for info in matches))
+ if len(providers) > 1:
+ options = " or ".join(f'"{p}:{model}"' for p in providers)
+ raise AmbiguousModelError(
+ f"model {model!r} is offered by multiple providers: "
+ f"{', '.join(providers)}. Fix: use the explicit form, e.g. "
+ f"Request(model={providers[0] + ':' + model!r}) — options: {options}.",
+ model=model,
+ providers=providers,
+ )
+ if matches:
+ # Exact-id matches beat alias matches; an alias must never
+ # shadow an entry whose canonical id IS the requested string.
+ exact = tuple(info for info in matches if info.id == model)
+ narrowed = exact if exact else matches
+ if len(narrowed) > 1:
+ # Same provider (multi-provider was caught above), multiple
+ # entries: never pick one by insertion order.
+ ids = ", ".join(info.id for info in narrowed)
+ raise AmbiguousModelError(
+ f"model {model!r} matches multiple catalog entries "
+ f"({ids}) under provider {narrowed[0].provider!r}. "
+ "Fix: request a canonical id directly.",
+ model=model,
+ providers=providers,
+ )
+ info = narrowed[0]
+ catalog_provider = _canonical_provider(info.provider)
+ if not _routable(catalog_provider, adapters):
+ raise UnknownModelError(
+ f"model {model!r} resolved in the catalog to provider "
+ f"{info.provider!r}, but lm15 has no adapter or compat "
+ f"preset for it. Known providers: {_known_providers(adapters)}. "
+ "Construct a provider LM directly (e.g. OpenAIChatLM with "
+ "a custom base_url) for OpenAI-compatible servers.",
+ model=model,
+ rules_tried=config.rules,
+ catalog_searched=True,
+ )
+ return _resolution(
+ requested=requested,
+ wire_model=info.id if model in info.aliases else str(model),
+ provider=catalog_provider,
+ source="catalog",
+ config=config,
+ adapters=adapters,
+ model_info=info,
+ )
+
+ # Rung 3: built-in prefix rules, first match wins.
+ for rule in config.rules:
+ if model.startswith(rule.prefix):
+ rule_provider = _canonical_provider(rule.provider)
+ if not _routable(rule_provider, adapters):
+ raise UnknownModelError(
+ f"rule {rule!r} names provider {rule.provider!r}, which has "
+ f"no adapter. Known providers: {_known_providers(adapters)}.",
+ model=model,
+ rules_tried=config.rules,
+ catalog_searched=config.registry is not None,
+ )
+ return _resolution(
+ requested=requested,
+ wire_model=str(model),
+ provider=rule_provider,
+ source="rule",
+ config=config,
+ adapters=adapters,
+ rule=rule,
+ )
+
+ hints = []
+ if ":" in model:
+ import difflib
+
+ head = _canonical_provider(model.split(":", 1)[0])
+ close = difflib.get_close_matches(head, sorted({*adapters, *_bound_ids(adapters)}), n=1, cutoff=0.75)
+ if close:
+ hints.append(f'Did you mean "{close[0]}:{model.split(":", 1)[1]}"?')
+ if object_provider is not None:
+ hints.append(
+ f"The model value carries provider {object_provider!r}, which has "
+ f"no adapter or compat preset (known providers: {_known_providers(adapters)})."
+ )
+ hints.append(
+ f'Use an explicit provider prefix — "provider:{model}" with provider '
+ f"one of: {_known_providers(adapters)}."
+ )
+ if config.registry is None:
+ hints.append(
+ "Or pass a model catalog: "
+ "LMRouter(config=RouterConfig(registry=ModelRegistry.discover())) "
+ "— install a catalog package such as 'aimo' first."
+ )
+ raise UnknownModelError(
+ f"could not route model {model!r}: no provider prefix, "
+ f"{'no catalog match' if config.registry is not None else 'no catalog supplied'}, "
+ f"and none of the {len(config.rules)} built-in rules matched. "
+ + " ".join(hints),
+ model=model,
+ rules_tried=config.rules,
+ catalog_searched=config.registry is not None,
+ )
+
+
+def _known_providers(adapters: Mapping[str, type]) -> str:
+ return ", ".join(sorted({*adapters, *_bound_ids(adapters)}))
+
+
+def _declared_env_keys(provider: str, adapters: Mapping[str, type]) -> tuple[str, ...]:
+ definition = _bound(provider, adapters)
+ if definition is not None:
+ return definition.env_keys
+ return adapters[provider].manifest.env_keys
+
+
+def _api_keys_source(
+ config: RouterConfig, provider: str, adapters: Mapping[str, type] = ADAPTERS,
+) -> str | None:
+ """Select a config key, not its value; never invoke credential providers.
+
+ Exact provider first, else identical non-empty env-key tuples. Empty
+ tuples do not join unrelated local servers, OAuth stores or ADC chains.
+ Multiple candidates are ambiguous even if their values look equal:
+ credential callables can change independently at request time.
+ """
+ keys = config.api_keys
+ if not keys:
+ return None
+ exact = [key for key in keys if _canonical_provider(key) == provider]
+ candidates = exact
+ if not exact and _routable(provider, adapters):
+ env_keys = _declared_env_keys(provider, adapters)
+ if env_keys:
+ candidates = [key for key in keys
+ if _routable(_canonical_provider(key), adapters)
+ and _declared_env_keys(_canonical_provider(key), adapters) == env_keys]
+ if len(candidates) > 1:
+ raise NotConfiguredError(
+ f"RouterConfig(api_keys=...): ambiguous credentials for {provider!r} from "
+ f"{', '.join(repr(key) for key in sorted(candidates))}; "
+ f"supply one entry under {provider!r} or keep only one shared entry",
+ )
+ if not candidates:
+ return None
+ key = candidates[0]
+ value = keys[key]
+ if value is None or (isinstance(value, str) and not value):
+ raise NotConfiguredError(f"RouterConfig(api_keys=...): empty credential under {key!r}; no environment fallback")
+ return key
+
+
+def _api_keys_entry(
+ config: RouterConfig, provider: str, adapters: Mapping[str, type] = ADAPTERS,
+) -> tuple[Credential | None, bool]:
+ key = _api_keys_source(config, provider, adapters)
+ return (config.api_keys[key], True) if key is not None else (None, False)
+
+
+def _base_url_entry(config: RouterConfig, provider: str) -> str | None:
+ """Explicit base_urls entry for a provider, matching either spelling."""
+ if config.base_urls is None:
+ return None
+ for key, value in config.base_urls.items():
+ if _canonical_provider(key) == provider:
+ return value
+ return None
+
+
+def _env_key_for(provider: str, config: RouterConfig, adapters: Mapping[str, type]) -> str | None:
+ """WHICH env var lm() would read for this provider (never the value).
+
+ None when the provider is OAuth-based or a keyless local preset
+ (declares no env keys) or when an explicit ``api_keys`` entry
+ overrides env lookup entirely.
+ """
+ if _api_keys_entry(config, provider, adapters)[1]:
+ return None
+ env_keys = _declared_env_keys(provider, adapters)
+ if not env_keys:
+ return None
+ env = config.env if config.env is not None else os.environ
+ for key in env_keys:
+ if env.get(key):
+ return key
+ return env_keys[0]
+
+
+def _build_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[str, type]):
+ cls = _adapter_for(resolution.provider, adapters)
+ definition = _bound(resolution.provider, adapters)
+ extra: dict = {}
+ if config.transport is not None:
+ extra["transport"] = config.transport
+ base_url = _base_url_entry(config, resolution.provider)
+ if base_url is not None:
+ if definition is not None and definition.hosted:
+ raise NotConfiguredError(
+ f"RouterConfig(base_urls={{{resolution.provider!r}: ...}}): a cloud door's URL is built from its "
+ f"host settings (resource, region), not given whole; set them in "
+ f"RouterConfig(settings={{{resolution.provider!r}: {{...}}}}) instead.",
+ )
+ extra["base_url"] = base_url
+ policy = _credential_policy(resolution.provider, adapters)
+ if policy == "oauth":
+ return cls(**extra) # self-resolving local OAuth constructor
+ api_key, _ = _api_keys_entry(config, resolution.provider, adapters)
+ if definition is not None and definition.hosted:
+ # A cloud door (AUTH-10): host settings from config, then env, then
+ # defaults; the credential from the explicit entry or, for a cloud
+ # chain policy, the chain's caching provider (AUTH-1/AUTH-2).
+ from .cloud.chains import ChainContext, credential_provider
+ from .cloud.hosts import resolve_settings
+
+ from .cloud.chains import profile_settings
+
+ env = config.env if config.env is not None else os.environ
+ given = (config.settings or {}).get(resolution.provider)
+ ctx = ChainContext.online(env)
+ settings = resolve_settings(definition.access.host, given, env, provider=resolution.provider,
+ profile=profile_settings(definition.access, ctx))
+ ctx.settings = settings
+ if api_key is None and definition.access.cloud_chain:
+ api_key = credential_provider(definition.access, ctx)
+ elif api_key is None:
+ for key in definition.access.env_keys:
+ value = env.get(key)
+ if value:
+ api_key = value
+ break
+ if api_key is None:
+ env_keys = definition.access.env_keys
+ raise MissingCredentialError(
+ f"no credential found for provider {resolution.provider!r}. "
+ f"Set {' or '.join(env_keys)} in the environment, or pass "
+ f"RouterConfig(api_keys={{{resolution.provider!r}: \"...\"}}).",
+ provider=resolution.provider,
+ env_keys=env_keys,
+ )
+ if definition.compat is not None:
+ extra["compat"] = definition.compat
+ return cls(api_key=api_key, access=definition.access, settings=settings, **extra)
+ if api_key is None and policy == "oauth-unless-explicit" and cls.has_stored_credential():
+ # A usable stored subscription login outranks ambient env keys:
+ # it spends no money per token (AUTH-1, oauth-unless-explicit).
+ return cls(**extra) # self-resolving local OAuth constructor
+ if api_key is None:
+ env = config.env if config.env is not None else os.environ
+ for key in _declared_env_keys(resolution.provider, adapters):
+ value = env.get(key)
+ if value:
+ api_key = value
+ break
+ if api_key is None and definition is not None and definition.placeholder_key is not None:
+ api_key = definition.placeholder_key
+ if not api_key and policy == "oauth-unless-explicit":
+ # Nothing anywhere: the constructor raises the typed login-hint error.
+ return cls(**extra)
+ if not api_key:
+ env_keys = _declared_env_keys(resolution.provider, adapters)
+ raise MissingCredentialError(
+ f"no API key found for provider {resolution.provider!r}. "
+ f"Set {' or '.join(env_keys)} in the environment, or pass "
+ f"RouterConfig(api_keys={{{resolution.provider!r}: \"...\"}}).",
+ provider=resolution.provider,
+ env_keys=env_keys,
+ )
+ if definition is not None:
+ # Bound entry: the dialect class with this provider's access policy
+ # (credential header, surfaces, base_url) and compat preset bound at
+ # construction. The LM then names itself by the provider (errors,
+ # ModelInfo.provider), not by the dialect.
+ return cls(api_key=api_key, compat=definition.compat, access=definition.access, **extra)
+ return cls(api_key=api_key, **extra)
+
+
+def _routed_request(request: Request, resolution: Resolution) -> Request:
+ if request.model == resolution.model:
+ return request
+ return replace(request, model=resolution.model)
+
+
+# ------------------------------------------------- the OpenAI-shaped door ----
+
+# litellm's routing prefixes (`<provider>/<model>`) that name a door lm15
+# has, copied as data. A prefix absent here is refused by name — never
+# routed by rule — because litellm's own rule is "a leading known provider
+# name is the provider", and an unknown one is an error there too. Where
+# litellm's name covers two lm15 doors (bedrock, vertex_ai: Anthropic or
+# not, by model) it is left out: choosing would be a guess.
+LITELLM_PROVIDER_PREFIXES: Mapping[str, str] = MappingProxyType({
+ "openai": "openai-chat",
+ "anthropic": "anthropic",
+ "gemini": "gemini",
+ "groq": "groq",
+ "openrouter": "openrouter",
+ "deepseek": "deepseek",
+ "xai": "xai",
+ "ollama": "ollama",
+ "ollama_chat": "ollama",
+ "hosted_vllm": "vllm",
+ "moonshot": "moonshotai",
+ "azure": "azure-chat",
+})
+
+# Keyword arguments of `create()` / `completion()` that configure the
+# CLIENT, not the request: refused with the lm15 place they belong.
+_CLIENT_KEYWORDS: Mapping[str, str] = MappingProxyType({
+ "api_key": "LMRouter(RouterConfig(api_keys={provider: key})) or the environment",
+ "api_base": "LMRouter(RouterConfig(base_urls={provider: url}))",
+ "base_url": "LMRouter(RouterConfig(base_urls={provider: url}))",
+ "timeout": "RouterConfig(transport=...)",
+ "num_retries": "your own retry loop over lm15.RETRYABLE_ERRORS (lm15 never retries)",
+ "max_retries": "your own retry loop over lm15.RETRYABLE_ERRORS (lm15 never retries)",
+ "headers": "RouterConfig(transport=...)",
+ "extra_headers": "RouterConfig(transport=...)",
+ "extra_body": "config.extensions on the Request (build it with request_from_openai_chat and edit)",
+ "extra_query": "RouterConfig(transport=...)",
+ "cache": "your own cache keyed on the Request (lm15 has no response cache)",
+ "caching": "your own cache keyed on the Request (lm15 has no response cache)",
+ "mock_response": "lm15.testing.FakeLM",
+ "drop_params": "nothing: lm15 refuses what it cannot carry instead of dropping it",
+ "custom_llm_provider": "the model string's prefix",
+})
+
+
+def openai_chat_model_string(model: str) -> str:
+ """The lm15 model string for a model string written for the OpenAI SDK
+ or litellm (`playbooks/api-family.md` § Ingest):
+
+ - an lm15 string (``provider:model``) is left alone;
+ - litellm's ``provider/model`` maps its prefix through
+ :data:`LITELLM_PROVIDER_PREFIXES` (only the first segment; a model
+ id may contain slashes itself: ``groq/openai/gpt-oss-20b``);
+ - a bare name routes by lm15's rules, except that OpenAI's models go
+ to the Chat Completions door (``openai-chat:``) — the endpoint both
+ libraries were using — not the Responses API.
+ """
+ if ":" in model:
+ return model
+ head, sep, rest = model.partition("/")
+ if sep and rest:
+ provider = LITELLM_PROVIDER_PREFIXES.get(head)
+ if provider is None:
+ raise UnknownModelError(
+ f"could not read {model!r} as a litellm model string: {head!r} is not a provider prefix lm15 "
+ f"has a door for (known: {', '.join(sorted(LITELLM_PROVIDER_PREFIXES))}); write it as lm15's "
+ "provider:model instead",
+ model=model,
+ )
+ return f"{provider}:{rest}"
+ return model
+
+
+def _split_openai_chat_call(model: str, messages: object, kwargs: dict) -> dict:
+ """``(model, messages, **kwargs)`` → the Chat Completions body, after
+ refusing the client keywords by name."""
+ for key, where in _CLIENT_KEYWORDS.items():
+ if key in kwargs:
+ raise NotConfiguredError(
+ f"{key!r} configures the client, not the request; in lm15 it lives in {where}",
+ )
+ return {"model": model, "messages": messages, **kwargs}
+
+
+# ---------------------------------------------------------------- router ----
+
+
+class LMRouter:
+ """Routes model strings to provider LMs.
+
+ Four methods, no state you can't see: config is frozen; the only
+ mutation is an LM cache keyed by provider (one LM per provider,
+ built lazily, reused).
+ """
+
+ def __init__(self, config: RouterConfig = RouterConfig()) -> None:
+ _check_provider_keyed(config, self._adapters)
+ self.config = config
+ self._lms: dict[str, object] = {}
+
+ _adapters: Mapping[str, type] = ADAPTERS
+
+ def resolve(self, model: str) -> Resolution:
+ """Offline lookup; invokes no credential providers and returns no secrets.
+
+ Raises UnknownModelError / AmbiguousModelError. This IS the
+ explain() method — there is no separate one.
+ """
+ return _resolve(model, self.config, self._adapters)
+
+ def lm(self, model: str):
+ """resolve(), then construct-or-reuse the provider LM.
+
+ Raises MissingCredentialError when no key is found. The
+ returned LM is an ordinary OpenAILM/AnthropicLM/... — the escape
+ hatch is built in: keep it, configure transports yourself.
+ """
+ resolution = self.resolve(model)
+ lm = self._lms.get(resolution.provider)
+ if lm is None:
+ lm = _build_lm(resolution, self.config, self._adapters)
+ self._lms[resolution.provider] = lm
+ return lm
+
+ def complete(self, request: Request) -> Response:
+ resolution = self.resolve(request.model)
+ return self.lm(request.model).complete(_routed_request(request, resolution))
+
+ def stream(self, request: Request) -> Iterator[StreamEvent]:
+ resolution = self.resolve(request.model)
+ return self.lm(request.model).stream(_routed_request(request, resolution))
+
+ def cache(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None):
+ """``router.cache(prefix)``: the MAP-6 door, routed by the prefix's model."""
+ resolution = self.resolve(prefix.model)
+ return self.lm(prefix.model).cache(_routed_request(prefix, resolution), ttl_seconds=ttl_seconds, label=label)
+
+ # ─── the OpenAI-shaped door (api-family § Ingest) ──────────────────
+
+ def resolve_openai_chat(self, model: str) -> Resolution:
+ """:meth:`resolve` for the OpenAI-shaped door: ``model`` is read by
+ :func:`openai_chat_model_string`, and a bare OpenAI name goes to
+ Chat Completions (``openai-chat``), the endpoint the OpenAI SDK and
+ litellm were using. Like ``resolve()``: no network, no credential
+ invocation or secret values in the result — "which provider, which env var"
+ before any key exists."""
+ resolution = self.resolve(openai_chat_model_string(model))
+ if resolution.source == "rule" and resolution.provider == "openai":
+ resolution = self.resolve(f"openai-chat:{resolution.model}")
+ return resolution
+
+ def request_from_openai_chat(self, model: str, messages: object, /, **kwargs) -> tuple[Request, object]:
+ """The Request behind :meth:`complete_from_openai_chat`, and the LM
+ it routes to. ``model`` may be written for the OpenAI SDK, for
+ litellm, or for lm15 (:meth:`resolve_openai_chat`); the body is
+ read with the destination door's own spellings when it speaks
+ the Chat Completions wire, else with OpenAI's."""
+ resolution = self.resolve_openai_chat(model)
+ body = _split_openai_chat_call(resolution.requested, messages, kwargs)
+ lm = self.lm(resolution.requested)
+ reader = getattr(lm, "request_from_openai_chat", None)
+ if reader is None:
+ from .providers.openai_chat import request_from_openai_chat as read_openai
+
+ request = read_openai(body)
+ else:
+ request = reader(body)
+ return _routed_request(request, resolution), lm
+
+ @overload
+ def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: Literal[False] = False, **kwargs) -> Response: ...
+
+ @overload
+ def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: Literal[True], **kwargs) -> ResponseStream: ...
+
+ @overload
+ def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: bool, **kwargs) -> Response | ResponseStream: ...
+
+ def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: bool = False, **kwargs) -> Response | ResponseStream:
+ """``client.chat.completions.create(model=, messages=, ...)`` or
+ ``litellm.completion(model=, messages=, ...)`` — the same call,
+ answered by lm15. The messages and keywords are read by
+ :func:`request_from_openai_chat` (MAP-12: every key maps, passes
+ through, or is refused by name); the model string by
+ :func:`openai_chat_model_string`. Returns a canonical
+ :class:`Response`, or with ``stream=True`` a lazy
+ :class:`ResponseStream`: iterate text, inspect ``.events()`` for
+ typed events and ``.response`` for the assembled answer. Close the
+ result (or use ``with``) when leaving a stream early. The native
+ ``complete(Request)`` method retains its single return type."""
+ if not isinstance(stream, bool):
+ raise TypeError("stream must be a boolean")
+ request, lm = self.request_from_openai_chat(model, messages, **kwargs)
+ if stream:
+ return ResponseStream(lm.stream(request), request)
+ return lm.complete(request)
+
+ def stream_from_openai_chat(self, model: str, messages: object, /, **kwargs) -> Iterator[StreamEvent]:
+ """The streaming twin of :meth:`complete_from_openai_chat`: typed
+ lm15 stream events, not OpenAI-shaped chunks."""
+ request, lm = self.request_from_openai_chat(model, messages, **kwargs)
+ return lm.stream(request)
+
+
+class AsyncLMRouter:
+ """Async mirror of :class:`LMRouter`.
+
+ Same four methods; ``lm()`` returns Async* mirrors; ``complete`` is
+ a coroutine and ``stream`` returns an async iterator. ``resolve()``
+ stays sync (it is pure).
+ """
+
+ def __init__(self, config: RouterConfig = RouterConfig()) -> None:
+ _check_provider_keyed(config, self._adapters)
+ self.config = config
+ self._lms: dict[str, object] = {}
+
+ _adapters: Mapping[str, type] = ASYNC_ADAPTERS
+
+ def resolve(self, model: str) -> Resolution:
+ return _resolve(model, self.config, self._adapters)
+
+ def lm(self, model: str):
+ resolution = self.resolve(model)
+ lm = self._lms.get(resolution.provider)
+ if lm is None:
+ lm = _build_lm(resolution, self.config, self._adapters)
+ self._lms[resolution.provider] = lm
+ return lm
+
+ async def complete(self, request: Request) -> Response:
+ resolution = self.resolve(request.model)
+ return await self.lm(request.model).complete(_routed_request(request, resolution))
+
+ def stream(self, request: Request) -> AsyncIterator[StreamEvent]:
+ resolution = self.resolve(request.model)
+ return self.lm(request.model).stream(_routed_request(request, resolution))
+
+ async def cache(self, prefix: Request, *, ttl_seconds: int | None = None, label: str | None = None):
+ resolution = self.resolve(prefix.model)
+ return await self.lm(prefix.model).cache(_routed_request(prefix, resolution), ttl_seconds=ttl_seconds, label=label)
+
+ resolve_openai_chat = LMRouter.resolve_openai_chat
+ request_from_openai_chat = LMRouter.request_from_openai_chat
+
+ @overload
+ async def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: Literal[False] = False, **kwargs) -> Response: ...
+
+ @overload
+ async def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: Literal[True], **kwargs) -> AsyncResponseStream: ...
+
+ @overload
+ async def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: bool, **kwargs) -> Response | AsyncResponseStream: ...
+
+ async def complete_from_openai_chat(self, model: str, messages: object, /, *, stream: bool = False, **kwargs) -> Response | AsyncResponseStream:
+ """Await for a Response, or a lazy AsyncResponseStream when stream=True.
+
+ Iterate the latter with ``async for``; ``await result.response()``
+ assembles the answer. ``async with result`` closes on early exit.
+ """
+ if not isinstance(stream, bool):
+ raise TypeError("stream must be a boolean")
+ request, lm = self.request_from_openai_chat(model, messages, **kwargs)
+ if stream:
+ return AsyncResponseStream(lm.stream(request), request)
+ return await lm.complete(request)
+
+ def stream_from_openai_chat(self, model: str, messages: object, /, **kwargs) -> AsyncIterator[StreamEvent]:
+ request, lm = self.request_from_openai_chat(model, messages, **kwargs)
+ return lm.stream(request)
diff --git a/dspy/_vendor/lm15/serde.py b/dspy/_vendor/lm15/serde.py
new file mode 100644
index 000000000..af4a30dd3
--- /dev/null
+++ b/dspy/_vendor/lm15/serde.py
@@ -0,0 +1,1319 @@
+"""
+lm15.serde — Serialization and deserialization for the lm15 type system.
+
+One function pair per type: xxx_to_dict / xxx_from_dict.
+All Part field names are consistent: "input" on the wire matches .input
+in memory. No name translation (no "arguments" vs "input" split).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .models import (
+ InferenceModelInfo,
+ InferencePricing,
+ ModelInfo,
+ ModelOrigin,
+)
+from .types import (
+ AudioDelta,
+ AudioFormat,
+ AudioPart,
+ BatchEntry,
+ BatchJobInfo,
+ BatchRequest,
+ BinaryPart,
+ BuiltinTool,
+ CacheConfig,
+ CachedPrefix,
+ CacheInfo,
+ CachePage,
+ CitationDelta,
+ CitationPart,
+ Config,
+ ContinuationDelta,
+ ContinuationState,
+ Delta,
+ DocumentPart,
+ ErrorDetail,
+ FileInfo,
+ FilePage,
+ FileUploadRequest,
+ ImageGenerationRequest,
+ ImageGenerationResponse,
+ SpeechGenerationRequest,
+ SpeechGenerationResponse,
+ VideoGenerationRequest,
+ VideoJobInfo,
+ FunctionTool,
+ ImageDelta,
+ ImagePart,
+ LiveClientAudioEvent,
+ LiveClientEndAudioEvent,
+ LiveClientEvent,
+ LiveClientImageEvent,
+ LiveClientInterruptEvent,
+ LiveClientTextEvent,
+ LiveClientToolResultEvent,
+ LiveClientTurnEvent,
+ LiveConfig,
+ LiveServerAudioEvent,
+ LiveServerErrorEvent,
+ LiveServerEvent,
+ LiveServerInterruptedEvent,
+ LiveServerTextEvent,
+ LiveServerToolCallDeltaEvent,
+ LiveServerToolCallEvent,
+ LiveServerTurnEndEvent,
+ LiveServerUsageEvent,
+ Message,
+ Part,
+ PART_TYPES,
+ Reasoning,
+ Request,
+ Response,
+ StreamDeltaEvent,
+ StreamEndEvent,
+ StreamErrorEvent,
+ StreamEvent,
+ StreamStartEvent,
+ TextDelta,
+ TokenLogprob,
+ TopLogprob,
+ TextPart,
+ ThinkingDelta,
+ ThinkingPart,
+ RefusalPart,
+ Tool,
+ ToolCallDelta,
+ ToolCallPart,
+ ToolChoice,
+ ToolResultPart,
+ Usage,
+ VideoPart,
+)
+
+
+# ─── Helpers ─────────────────────────────────────────────────────────
+
+def _is_empty(value: Any) -> bool:
+ return value is None or value == "" or value == () or value == [] or value == {}
+
+
+def _clean_mapping(values: dict[str, Any]) -> dict[str, Any]:
+ """Drop empty optional fields — at the top level of this object ONLY.
+
+ The omission rule (docs/serde-rules.md): each typed serializer omits its
+ own empty optional fields; nested values are either already-serialized
+ typed objects or opaque user/provider payloads, and both are embedded
+ verbatim. Recursing here would give the same value different wire forms
+ depending on the serialization entry point.
+ """
+ out: dict[str, Any] = {}
+ for key, value in values.items():
+ if isinstance(value, tuple):
+ value = list(value)
+ if _is_empty(value):
+ continue
+ out[key] = value
+ return out
+
+
+
+# ─── Continuation state ──────────────────────────────────────────────
+
+def continuation_to_dict(state: ContinuationState) -> dict[str, Any]:
+ return {
+ "provider": state.provider,
+ "kind": state.kind,
+ "data": state.data,
+ }
+
+
+def continuation_from_dict(d: dict[str, Any]) -> ContinuationState:
+ return ContinuationState(
+ provider=d["provider"],
+ kind=d["kind"],
+ data=d.get("data", {}),
+ )
+
+
+def _continuation_to_json(values: tuple[ContinuationState, ...]) -> list[dict[str, Any]] | None:
+ if not values:
+ return None
+ return [continuation_to_dict(state) for state in values]
+
+
+def _continuation_from_json(value: Any) -> tuple[ContinuationState, ...]:
+ if value is None:
+ return ()
+ if not isinstance(value, list):
+ raise TypeError("continuation must be a list")
+ states: list[ContinuationState] = []
+ for item in value:
+ if not isinstance(item, dict):
+ raise TypeError("continuation entries must be objects")
+ states.append(continuation_from_dict(item))
+ return tuple(states)
+
+
+# ─── Parts ───────────────────────────────────────────────────────────
+
+def part_to_dict(part: Part) -> dict[str, Any]:
+ """Serialize a Part to the canonical lm15 JSON format."""
+ d: dict[str, Any] = {"type": part.type}
+
+ if isinstance(part, TextPart):
+ d["text"] = part.text
+
+ elif isinstance(part, ThinkingPart):
+ d["text"] = part.text
+
+ elif isinstance(part, RefusalPart):
+ d["text"] = part.text
+
+ elif isinstance(part, CitationPart):
+ if part.text is not None:
+ d["text"] = part.text
+ if part.url is not None:
+ d["url"] = part.url
+ if part.title is not None:
+ d["title"] = part.title
+
+ elif isinstance(part, (ImagePart, AudioPart, VideoPart, DocumentPart, BinaryPart)):
+ d["media_type"] = part.media_type
+ if part.data is not None:
+ d["data"] = part.data
+ if part.url is not None:
+ d["url"] = part.url
+ if part.file_id is not None:
+ d["file_id"] = part.file_id
+ if part.path is not None:
+ d["path"] = str(part.path)
+ if hasattr(part, "detail") and part.detail is not None:
+ d["detail"] = part.detail
+
+ elif isinstance(part, ToolCallPart):
+ d["id"] = part.id
+ d["name"] = part.name
+ d["input"] = part.input # consistent: "input" everywhere
+
+ elif isinstance(part, ToolResultPart):
+ d["id"] = part.id
+ if part.name is not None:
+ d["name"] = part.name
+ d["content"] = [part_to_dict(p) for p in part.content] if part.content else []
+ if part.is_error:
+ d["is_error"] = part.is_error
+
+ continuation = _continuation_to_json(part.continuation)
+ if continuation is not None:
+ d["continuation"] = continuation
+
+ return d
+
+
+def part_from_dict(d: dict[str, Any]) -> Part:
+ """Deserialize a Part from the canonical lm15 JSON format."""
+ t = d["type"]
+
+ continuation = _continuation_from_json(d.get("continuation"))
+
+ if t == "text":
+ return TextPart(text=d.get("text", ""), continuation=continuation)
+
+ if t == "thinking":
+ return ThinkingPart(text=d.get("text", ""), continuation=continuation)
+
+ if t == "refusal":
+ return RefusalPart(text=d.get("text", ""), continuation=continuation)
+
+ if t == "citation":
+ return CitationPart(text=d.get("text"), url=d.get("url"), title=d.get("title"), continuation=continuation)
+
+ if t in ("image", "audio", "video", "document", "binary"):
+ cls = PART_TYPES[t]
+ kwargs: dict[str, Any] = {
+ "media_type": d.get("media_type", ""),
+ "data": d.get("data"),
+ "url": d.get("url"),
+ "file_id": d.get("file_id"),
+ "path": d.get("path"),
+ "continuation": continuation,
+ }
+ if t == "image":
+ kwargs["detail"] = d.get("detail")
+ return cls(**kwargs)
+
+ if t == "tool_call":
+ return ToolCallPart(
+ id=d["id"],
+ name=d["name"],
+ input=d.get("input", {}),
+ continuation=continuation,
+ )
+
+ if t == "tool_result":
+ raw_content = d.get("content", [])
+ if isinstance(raw_content, str):
+ content = (TextPart(text=raw_content),) if raw_content else ()
+ elif isinstance(raw_content, list):
+ content = tuple(
+ part_from_dict(c) if isinstance(c, dict) else TextPart(text=str(c))
+ for c in raw_content
+ )
+ else:
+ content = ()
+ return ToolResultPart(
+ id=d["id"],
+ content=content,
+ name=d.get("name"),
+ is_error=d.get("is_error", False),
+ continuation=continuation,
+ )
+
+ raise ValueError(f"unsupported part type: {t}")
+
+
+# ─── Messages ────────────────────────────────────────────────────────
+
+def message_to_dict(msg: Message) -> dict[str, Any]:
+ out: dict[str, Any] = {"role": msg.role, "parts": [part_to_dict(p) for p in msg.parts]}
+ continuation = _continuation_to_json(msg.continuation)
+ if continuation is not None:
+ out["continuation"] = continuation
+ return out
+
+
+def message_from_dict(d: dict[str, Any]) -> Message:
+ role = d["role"]
+ parts_raw = d.get("parts", [])
+ parts = tuple(
+ part_from_dict(p) if isinstance(p, dict) else TextPart(text=str(p))
+ for p in parts_raw
+ )
+ if not parts:
+ raise ValueError(f"message for role '{role}' has no parts")
+ return Message(role=role, parts=parts, continuation=_continuation_from_json(d.get("continuation")))
+
+
+def messages_to_json(messages: list[Message] | tuple[Message, ...]) -> list[dict[str, Any]]:
+ return [message_to_dict(m) for m in messages]
+
+
+def messages_from_json(data: list[dict[str, Any]]) -> list[Message]:
+ return [message_from_dict(d) for d in data]
+
+
+# ─── Tools ───────────────────────────────────────────────────────────
+
+def tool_to_dict(t: Tool) -> dict[str, Any]:
+ if isinstance(t, FunctionTool):
+ out = _clean_mapping({
+ "type": "function",
+ "name": t.name,
+ "description": t.description,
+ })
+ # parameters is required-with-shape (INV-033): always emitted, even
+ # when it is the opaque literal {} — opaque payloads round-trip
+ # verbatim and are never subject to the omission rule.
+ out["parameters"] = t.parameters
+ return out
+ if isinstance(t, BuiltinTool):
+ return _clean_mapping({
+ "type": "builtin",
+ "name": t.name,
+ "config": t.config,
+ })
+ raise TypeError(f"unsupported tool type: {type(t)}")
+
+
+def tool_from_dict(d: dict[str, Any]) -> Tool:
+ if d.get("type") == "builtin":
+ return BuiltinTool(name=d["name"], config=d.get("config"))
+ return FunctionTool(
+ name=d["name"],
+ description=d.get("description"),
+ parameters=d.get("parameters", {"type": "object", "properties": {}}),
+ )
+
+
+# ─── Config ──────────────────────────────────────────────────────────
+
+def tool_choice_to_dict(tc: ToolChoice) -> dict[str, Any]:
+ return _clean_mapping({
+ "mode": tc.mode,
+ "allowed": list(tc.allowed),
+ "parallel": tc.parallel,
+ })
+
+
+
+def _bare_or_list(value: Any) -> tuple:
+ """INV-020: a bare string coerces to a 1-tuple; a list becomes a tuple.
+ (A bare string used to be iterated into characters — 2026-09-07.)"""
+ if isinstance(value, str):
+ return (value,)
+ return tuple(value)
+
+
+def tool_choice_from_dict(d: dict[str, Any]) -> ToolChoice:
+ return ToolChoice(
+ mode=d.get("mode", "auto"),
+ allowed=_bare_or_list(d.get("allowed", [])), # INV-020: a bare str is one element
+ parallel=d.get("parallel"),
+ )
+
+
+def reasoning_to_dict(r: Reasoning) -> dict[str, Any]:
+ return _clean_mapping({
+ "effort": r.effort,
+ "thinking_budget": r.thinking_budget,
+ "summary": r.summary,
+ })
+
+
+def reasoning_from_dict(d: dict[str, Any]) -> Reasoning:
+ default_effort = "off" if d.get("enabled") is False else "medium"
+ effort = d.get("effort", default_effort)
+ # Legacy payloads could combine enabled=false with a budget. In the
+ # current type system, off reasoning has no budgets, so discard them.
+ # `total_budget` (removed 2026-09-02, MAP-7) and `adaptive` (now
+ # "absent") are legacy spellings: the first is dropped on read, the
+ # second reads as medium — INV-043 leniency for pre-MAP-7 payloads.
+ if effort == "adaptive":
+ effort = "medium"
+ if effort == "off":
+ return Reasoning(effort="off")
+ return Reasoning(
+ effort=effort,
+ thinking_budget=d.get("thinking_budget", d.get("budget")),
+ summary=d.get("summary"),
+ )
+
+
+_CACHE_MODES = ("auto", "off")
+_CACHE_RETENTIONS = ("short", "long")
+
+
+def cache_config_to_dict(c: CacheConfig) -> dict[str, Any]:
+ return _clean_mapping({
+ "mode": c.mode,
+ "retention": c.retention,
+ "key": c.key,
+ "prefix_until_index": c.prefix_until_index,
+ "prefix": c.prefix,
+ "resource": c.resource,
+ })
+
+
+def cache_config_from_dict(d: dict[str, Any]) -> CacheConfig:
+ mode = d.get("mode", "auto")
+ if mode not in _CACHE_MODES:
+ raise ValueError(f"unsupported cache mode: {mode}")
+ retention = d.get("retention")
+ if retention is not None and retention not in _CACHE_RETENTIONS:
+ raise ValueError(f"unsupported cache retention: {retention}")
+ return CacheConfig(
+ mode=mode,
+ retention=retention,
+ key=d.get("key"),
+ prefix_until_index=d.get("prefix_until_index"),
+ prefix=d.get("prefix"),
+ resource=d.get("resource"),
+ )
+
+
+# ─── Cache resources ─────────────────────────────────────────────────
+
+def cache_info_to_dict(c: CacheInfo) -> dict[str, Any]:
+ return _clean_mapping({
+ "id": c.id,
+ "model": c.model,
+ "tokens": c.tokens,
+ "created_at": c.created_at,
+ "expires_at": c.expires_at,
+ "label": c.label,
+ "provider_data": c.provider_data,
+ })
+
+
+def cache_info_from_dict(d: dict[str, Any]) -> CacheInfo:
+ return CacheInfo(
+ id=d["id"],
+ model=d["model"],
+ tokens=d.get("tokens"),
+ created_at=d.get("created_at"),
+ expires_at=d.get("expires_at"),
+ label=d.get("label"),
+ provider_data=d.get("provider_data"),
+ )
+
+
+def cache_page_to_dict(p: CachePage) -> dict[str, Any]:
+ return _clean_mapping({
+ "items": [cache_info_to_dict(c) for c in p.items],
+ "next_cursor": p.next_cursor,
+ })
+
+
+def cache_page_from_dict(d: dict[str, Any]) -> CachePage:
+ return CachePage(
+ items=tuple(cache_info_from_dict(c) for c in d.get("items", [])),
+ next_cursor=d.get("next_cursor"),
+ )
+
+
+def cached_prefix_to_dict(c: CachedPrefix) -> dict[str, Any]:
+ return _clean_mapping({
+ "prefix": request_to_dict(c.prefix),
+ "resource": cache_info_to_dict(c.resource) if c.resource is not None else None,
+ })
+
+
+def cached_prefix_from_dict(d: dict[str, Any]) -> CachedPrefix:
+ return CachedPrefix(
+ prefix=request_from_dict(d["prefix"]),
+ resource=cache_info_from_dict(d["resource"]) if isinstance(d.get("resource"), dict) else None,
+ )
+
+
+def config_to_dict(c: Config) -> dict[str, Any]:
+ return _clean_mapping({
+ "max_tokens": c.max_tokens,
+ "temperature": c.temperature,
+ "top_p": c.top_p,
+ "top_k": c.top_k,
+ "stop": list(c.stop),
+ "response_format": c.response_format,
+ "tool_choice": tool_choice_to_dict(c.tool_choice) if c.tool_choice else None,
+ "reasoning": reasoning_to_dict(c.reasoning) if c.reasoning else None,
+ "cache": cache_config_to_dict(c.cache) if c.cache else None,
+ "service_tier": c.service_tier,
+ "user_id": c.user_id,
+ "store": c.store, # False is data (opt-out), not emptiness — emitted
+ "logprobs": c.logprobs, # 0 is data (chosen-only), not emptiness — emitted
+ "extensions": c.extensions,
+ })
+
+
+def _config_nest(d: dict[str, Any], key: str) -> dict[str, Any] | None:
+ """Return config.<key> as a dict, None when absent/null.
+
+ A present non-dict value is malformed canonical JSON and raises
+ TypeError (INV-042): an error, never silent data loss.
+ """
+ value = d.get(key)
+ if value is None:
+ return None
+ if not isinstance(value, dict):
+ raise TypeError(f"config.{key} must be a JSON object, got {type(value).__name__}")
+ return value
+
+
+def config_from_dict(d: dict[str, Any]) -> Config:
+ tool_choice = _config_nest(d, "tool_choice")
+ reasoning = _config_nest(d, "reasoning")
+ cache = _config_nest(d, "cache")
+ return Config(
+ max_tokens=d.get("max_tokens"),
+ temperature=d.get("temperature"),
+ top_p=d.get("top_p"),
+ top_k=d.get("top_k"),
+ stop=_bare_or_list(d.get("stop", [])), # INV-020: a bare str is one element
+ response_format=d.get("response_format"),
+ tool_choice=tool_choice_from_dict(tool_choice) if tool_choice is not None else None,
+ reasoning=reasoning_from_dict(reasoning) if reasoning is not None else None,
+ cache=cache_config_from_dict(cache) if cache is not None else None,
+ service_tier=d.get("service_tier"),
+ user_id=d.get("user_id"),
+ store=d.get("store"),
+ logprobs=d.get("logprobs"),
+ extensions=d.get("extensions"),
+ )
+
+
+# ─── Logprobs ────────────────────────────────────────────────────────
+
+def _top_logprob_to_dict(t: TopLogprob) -> dict[str, Any]:
+ # token and logprob are required — "" and 0.0 are data, not emptiness,
+ # so they bypass the omission rule.
+ out: dict[str, Any] = {"token": t.token, "logprob": t.logprob}
+ if t.bytes is not None:
+ out["bytes"] = list(t.bytes)
+ if t.token_id is not None:
+ out["token_id"] = t.token_id
+ return out
+
+
+def token_logprob_to_dict(t: TokenLogprob) -> dict[str, Any]:
+ out = _top_logprob_to_dict(TopLogprob(token=t.token, logprob=t.logprob, bytes=t.bytes, token_id=t.token_id))
+ if t.top:
+ out["top"] = [_top_logprob_to_dict(x) for x in t.top]
+ return out
+
+
+def token_logprob_from_dict(d: dict[str, Any]) -> TokenLogprob:
+ return TokenLogprob(
+ token=d["token"],
+ logprob=d["logprob"],
+ bytes=tuple(d["bytes"]) if d.get("bytes") is not None else None,
+ token_id=d.get("token_id"),
+ top=tuple(
+ TopLogprob(
+ token=x["token"],
+ logprob=x["logprob"],
+ bytes=tuple(x["bytes"]) if x.get("bytes") is not None else None,
+ token_id=x.get("token_id"),
+ )
+ for x in d.get("top", [])
+ ),
+ )
+
+
+def _logprobs_to_json(logprobs: tuple[TokenLogprob, ...] | None) -> list[dict[str, Any]] | None:
+ if not logprobs:
+ return None
+ return [token_logprob_to_dict(t) for t in logprobs]
+
+
+def _logprobs_from_json(value: Any) -> tuple[TokenLogprob, ...] | None:
+ if value is None:
+ return None
+ return tuple(token_logprob_from_dict(x) for x in value)
+
+
+# ─── ErrorDetail ─────────────────────────────────────────────────────
+
+def error_detail_to_dict(e: ErrorDetail) -> dict[str, Any]:
+ return _clean_mapping({
+ "code": e.code,
+ "message": e.message,
+ "provider_code": e.provider_code,
+ })
+
+
+def error_detail_from_dict(d: dict[str, Any]) -> ErrorDetail:
+ return ErrorDetail(
+ code=d["code"],
+ message=d.get("message", ""),
+ provider_code=d.get("provider_code"),
+ )
+
+
+# ─── Delta ───────────────────────────────────────────────────────────
+
+def delta_to_dict(d: Delta) -> dict[str, Any]:
+ out: dict[str, Any] = {
+ "type": d.type,
+ "part_index": d.part_index,
+ }
+
+ if isinstance(d, TextDelta):
+ out["text"] = d.text
+ if d.logprobs:
+ out["logprobs"] = _logprobs_to_json(d.logprobs)
+ elif isinstance(d, ThinkingDelta):
+ out["text"] = d.text
+ elif isinstance(d, AudioDelta):
+ out["data"] = d.data
+ out["url"] = d.url
+ out["file_id"] = d.file_id
+ out["media_type"] = d.media_type
+ elif isinstance(d, ImageDelta):
+ out["data"] = d.data
+ out["url"] = d.url
+ out["file_id"] = d.file_id
+ out["media_type"] = d.media_type
+ elif isinstance(d, ToolCallDelta):
+ out["input"] = d.input
+ out["id"] = d.id
+ out["name"] = d.name
+ elif isinstance(d, CitationDelta):
+ out["text"] = d.text
+ out["url"] = d.url
+ out["title"] = d.title
+ elif isinstance(d, ContinuationDelta):
+ out["provider"] = d.provider
+ out["kind"] = d.kind
+ out["data"] = d.data
+ out["part_index"] = d.part_index
+ else:
+ raise TypeError(f"unsupported delta type: {type(d)}")
+
+ return {key: value for key, value in out.items() if value is not None}
+
+
+def delta_from_dict(d: dict[str, Any]) -> Delta:
+ t = d["type"]
+ part_index = d.get("part_index", 0)
+
+ if t == "text":
+ return TextDelta(
+ text=d.get("text", ""),
+ part_index=part_index,
+ logprobs=_logprobs_from_json(d.get("logprobs")) or (),
+ )
+ if t == "thinking":
+ return ThinkingDelta(text=d.get("text", ""), part_index=part_index)
+ if t == "audio":
+ return AudioDelta(
+ data=d.get("data"),
+ url=d.get("url"),
+ file_id=d.get("file_id"),
+ part_index=part_index,
+ media_type=d.get("media_type"),
+ )
+ if t == "image":
+ return ImageDelta(
+ data=d.get("data"),
+ url=d.get("url"),
+ file_id=d.get("file_id"),
+ part_index=part_index,
+ media_type=d.get("media_type"),
+ )
+ if t == "tool_call":
+ return ToolCallDelta(
+ input=d.get("input", ""),
+ part_index=part_index,
+ id=d.get("id"),
+ name=d.get("name"),
+ )
+ if t == "citation":
+ return CitationDelta(
+ text=d.get("text"),
+ url=d.get("url"),
+ title=d.get("title"),
+ part_index=part_index,
+ )
+ if t == "continuation":
+ return ContinuationDelta(
+ provider=d["provider"],
+ kind=d["kind"],
+ data=d.get("data", {}),
+ part_index=d.get("part_index"),
+ )
+
+ raise ValueError(f"unsupported delta type: {t}")
+
+
+# ─── Usage ───────────────────────────────────────────────────────────
+
+def usage_to_dict(u: Usage) -> dict[str, Any]:
+ return _clean_mapping({
+ "input_tokens": u.input_tokens,
+ "output_tokens": u.output_tokens,
+ "total_tokens": u.total_tokens,
+ "cache_read_tokens": u.cache_read_tokens,
+ "cache_write_tokens": u.cache_write_tokens,
+ "reasoning_tokens": u.reasoning_tokens,
+ "input_audio_tokens": u.input_audio_tokens,
+ "output_audio_tokens": u.output_audio_tokens,
+ })
+
+
+def usage_from_dict(d: dict[str, Any]) -> Usage:
+ return Usage(
+ input_tokens=d.get("input_tokens"),
+ output_tokens=d.get("output_tokens"),
+ total_tokens=d.get("total_tokens"),
+ cache_read_tokens=d.get("cache_read_tokens"),
+ cache_write_tokens=d.get("cache_write_tokens"),
+ reasoning_tokens=d.get("reasoning_tokens"),
+ input_audio_tokens=d.get("input_audio_tokens"),
+ output_audio_tokens=d.get("output_audio_tokens"),
+ )
+
+
+# ─── StreamEvent ─────────────────────────────────────────────────────
+
+def stream_event_to_dict(e: StreamEvent) -> dict[str, Any]:
+ if isinstance(e, StreamStartEvent):
+ return _clean_mapping({"type": e.type, "id": e.id, "model": e.model})
+ if isinstance(e, StreamDeltaEvent):
+ return {"type": e.type, "delta": delta_to_dict(e.delta)}
+ if isinstance(e, StreamEndEvent):
+ return _clean_mapping({
+ "type": e.type,
+ "finish_reason": e.finish_reason,
+ "usage": usage_to_dict(e.usage) if e.usage else None,
+ "provider_data": e.provider_data,
+ })
+ if isinstance(e, StreamErrorEvent):
+ return {"type": e.type, "error": error_detail_to_dict(e.error)}
+ raise TypeError(f"unsupported stream event type: {type(e)}")
+
+
+def stream_event_from_dict(d: dict[str, Any]) -> StreamEvent:
+ t = d["type"]
+ if t == "start":
+ return StreamStartEvent(id=d.get("id"), model=d.get("model"))
+ if t == "delta":
+ return StreamDeltaEvent(delta=delta_from_dict(d["delta"]))
+ if t == "end":
+ return StreamEndEvent(
+ finish_reason=d.get("finish_reason"),
+ usage=usage_from_dict(d["usage"]) if isinstance(d.get("usage"), dict) else None,
+ provider_data=d.get("provider_data"),
+ )
+ if t == "error":
+ return StreamErrorEvent(error=error_detail_from_dict(d["error"]))
+ raise ValueError(f"unsupported stream event type: {t}")
+
+
+# ─── Request / Response ─────────────────────────────────────────────
+
+def request_to_dict(r: Request) -> dict[str, Any]:
+ system: Any
+ if isinstance(r.system, tuple):
+ system = [part_to_dict(p) for p in r.system]
+ else:
+ system = r.system
+ return _clean_mapping({
+ "model": r.model,
+ "messages": [message_to_dict(m) for m in r.messages],
+ "system": system,
+ "tools": [tool_to_dict(t) for t in r.tools],
+ "config": config_to_dict(r.config),
+ })
+
+
+def request_from_dict(d: dict[str, Any]) -> Request:
+ raw_system = d.get("system")
+ system: str | tuple[Part, ...] | None
+ if isinstance(raw_system, list):
+ system = tuple(part_from_dict(x) for x in raw_system)
+ else:
+ system = raw_system
+ return Request(
+ model=d["model"],
+ messages=tuple(message_from_dict(m) for m in d["messages"]),
+ system=system,
+ tools=tuple(tool_from_dict(t) for t in d.get("tools", [])),
+ config=config_from_dict(d.get("config", {})),
+ )
+
+
+def response_to_dict(r: Response, *, include_provider_data: bool = False) -> dict[str, Any]:
+ out: dict[str, Any] = {
+ "id": r.id,
+ "model": r.model,
+ "message": message_to_dict(r.message),
+ "finish_reason": r.finish_reason,
+ "usage": usage_to_dict(r.usage),
+ "logprobs": _logprobs_to_json(r.logprobs),
+ }
+ if include_provider_data and r.provider_data is not None:
+ out["provider_data"] = r.provider_data
+ return _clean_mapping(out)
+
+
+def response_from_dict(d: dict[str, Any]) -> Response:
+ return Response(
+ id=d.get("id"),
+ model=d["model"],
+ message=message_from_dict(d["message"]),
+ finish_reason=d["finish_reason"],
+ usage=usage_from_dict(d["usage"]) if isinstance(d.get("usage"), dict) else Usage(),
+ logprobs=_logprobs_from_json(d.get("logprobs")),
+ provider_data=d.get("provider_data"),
+ )
+
+
+# ─── Batch ─────────────────────────────────────────────────────────────
+
+def batch_request_to_dict(b: BatchRequest) -> dict[str, Any]:
+ return _clean_mapping({
+ "model": b.model,
+ "requests": [request_to_dict(r) for r in b.requests],
+ "label": b.label,
+ "extensions": b.extensions,
+ })
+
+
+def batch_request_from_dict(d: dict[str, Any]) -> BatchRequest:
+ return BatchRequest(
+ model=d.get("model"),
+ requests=tuple(request_from_dict(r) for r in d.get("requests", [])),
+ label=d.get("label"),
+ extensions=d.get("extensions"),
+ )
+
+
+def batch_job_to_dict(j: BatchJobInfo) -> dict[str, Any]:
+ return _clean_mapping({
+ "id": j.id,
+ "status": j.status,
+ "label": j.label,
+ "created_at": j.created_at,
+ "provider_data": j.provider_data,
+ })
+
+
+def batch_job_from_dict(d: dict[str, Any]) -> BatchJobInfo:
+ return BatchJobInfo(
+ id=d["id"],
+ status=d["status"],
+ label=d.get("label"),
+ created_at=d.get("created_at"),
+ provider_data=d.get("provider_data"),
+ )
+
+
+def batch_entry_to_dict(e: BatchEntry) -> dict[str, Any]:
+ return _clean_mapping({
+ "index": e.index,
+ "outcome": e.outcome,
+ "response": response_to_dict(e.response, include_provider_data=True) if e.response else None,
+ "error": error_detail_to_dict(e.error) if e.error else None,
+ })
+
+
+def batch_entry_from_dict(d: dict[str, Any]) -> BatchEntry:
+ return BatchEntry(
+ index=d["index"],
+ outcome=d["outcome"],
+ response=response_from_dict(d["response"]) if isinstance(d.get("response"), dict) else None,
+ error=error_detail_from_dict(d["error"]) if isinstance(d.get("error"), dict) else None,
+ )
+
+
+# ─── Files ─────────────────────────────────────────────────────────
+
+def file_upload_request_to_dict(r: FileUploadRequest) -> dict[str, Any]:
+ """Bytes travel as base64 (the media-part precedent); a path-backed
+ request serializes its path as a plain string, exactly like
+ path-addressed media Parts — meaningful only where the filesystem is
+ shared, which is the same caveat Parts already carry."""
+ import base64
+
+ return _clean_mapping({
+ "filename": r.filename,
+ "bytes_data": base64.b64encode(r.bytes_data).decode("ascii") if r.bytes_data is not None else None,
+ "media_type": r.media_type,
+ "extensions": r.extensions,
+ "path": str(r.path) if r.path is not None else None,
+ })
+
+
+def file_upload_request_from_dict(d: dict[str, Any]) -> FileUploadRequest:
+ import base64
+
+ raw = d.get("bytes_data")
+ return FileUploadRequest(
+ filename=d["filename"],
+ bytes_data=base64.b64decode(raw) if isinstance(raw, str) else None,
+ media_type=d.get("media_type", "application/octet-stream"),
+ extensions=d.get("extensions"),
+ path=d.get("path"),
+ )
+
+
+def file_info_to_dict(f: FileInfo) -> dict[str, Any]:
+ return _clean_mapping({
+ "id": f.id,
+ "filename": f.filename,
+ "media_type": f.media_type,
+ "size_bytes": f.size_bytes,
+ "created_at": f.created_at,
+ "expires_at": f.expires_at,
+ "readiness": f.readiness,
+ "downloadable": f.downloadable,
+ "provider_data": f.provider_data,
+ })
+
+
+def file_info_from_dict(d: dict[str, Any]) -> FileInfo:
+ return FileInfo(
+ id=d["id"],
+ filename=d.get("filename"),
+ media_type=d.get("media_type"),
+ size_bytes=d.get("size_bytes"),
+ created_at=d.get("created_at"),
+ expires_at=d.get("expires_at"),
+ readiness=d.get("readiness", "ready"),
+ downloadable=d.get("downloadable"),
+ provider_data=d.get("provider_data"),
+ )
+
+
+def file_page_to_dict(p: FilePage) -> dict[str, Any]:
+ return _clean_mapping({
+ "items": [file_info_to_dict(f) for f in p.items],
+ "next_cursor": p.next_cursor,
+ })
+
+
+def file_page_from_dict(d: dict[str, Any]) -> FilePage:
+ return FilePage(
+ items=tuple(file_info_from_dict(f) for f in d.get("items", [])),
+ next_cursor=d.get("next_cursor"),
+ )
+
+
+# ─── Media generation ────────────────────────────────────────────────
+
+def image_generation_request_to_dict(r: ImageGenerationRequest) -> dict[str, Any]:
+ return _clean_mapping({
+ "model": r.model,
+ "prompt": r.prompt,
+ "size": r.size,
+ "images": [part_to_dict(img) for img in r.images] or None,
+ "extensions": r.extensions,
+ })
+
+
+def image_generation_request_from_dict(d: dict[str, Any]) -> ImageGenerationRequest:
+ return ImageGenerationRequest(
+ model=d["model"],
+ prompt=d["prompt"],
+ size=d.get("size"),
+ images=tuple(part_from_dict(img) for img in d.get("images", [])),
+ extensions=d.get("extensions"),
+ )
+
+
+def image_generation_response_to_dict(r: ImageGenerationResponse) -> dict[str, Any]:
+ return _clean_mapping({
+ "images": [part_to_dict(img) for img in r.images],
+ "text": r.text,
+ "id": r.id,
+ "model": r.model,
+ "usage": usage_to_dict(r.usage) or None,
+ "provider_data": r.provider_data,
+ })
+
+
+def image_generation_response_from_dict(d: dict[str, Any]) -> ImageGenerationResponse:
+ return ImageGenerationResponse(
+ images=tuple(part_from_dict(img) for img in d.get("images", [])),
+ text=d.get("text"),
+ id=d.get("id"),
+ model=d.get("model"),
+ usage=usage_from_dict(d.get("usage") or {}),
+ provider_data=d.get("provider_data"),
+ )
+
+
+def speech_generation_request_to_dict(r: SpeechGenerationRequest) -> dict[str, Any]:
+ return _clean_mapping({
+ "model": r.model,
+ "prompt": r.prompt,
+ "voice": r.voice,
+ "format": r.format,
+ "extensions": r.extensions,
+ })
+
+
+def speech_generation_request_from_dict(d: dict[str, Any]) -> SpeechGenerationRequest:
+ return SpeechGenerationRequest(
+ model=d["model"],
+ prompt=d["prompt"],
+ voice=d.get("voice"),
+ format=d.get("format"),
+ extensions=d.get("extensions"),
+ )
+
+
+def speech_generation_response_to_dict(r: SpeechGenerationResponse) -> dict[str, Any]:
+ return _clean_mapping({
+ "audio": part_to_dict(r.audio),
+ "id": r.id,
+ "model": r.model,
+ "usage": usage_to_dict(r.usage) or None,
+ "provider_data": r.provider_data,
+ })
+
+
+def speech_generation_response_from_dict(d: dict[str, Any]) -> SpeechGenerationResponse:
+ return SpeechGenerationResponse(
+ audio=part_from_dict(d["audio"]),
+ id=d.get("id"),
+ model=d.get("model"),
+ usage=usage_from_dict(d.get("usage") or {}),
+ provider_data=d.get("provider_data"),
+ )
+
+
+# ─── Video generation ────────────────────────────────────────────────
+
+def video_generation_request_to_dict(r: VideoGenerationRequest) -> dict[str, Any]:
+ return _clean_mapping({
+ "model": r.model,
+ "prompt": r.prompt,
+ "seconds": r.seconds,
+ "images": [part_to_dict(img) for img in r.images] or None,
+ "extensions": r.extensions,
+ })
+
+
+def video_generation_request_from_dict(d: dict[str, Any]) -> VideoGenerationRequest:
+ return VideoGenerationRequest(
+ model=d["model"],
+ prompt=d["prompt"],
+ seconds=d.get("seconds"),
+ images=tuple(part_from_dict(img) for img in d.get("images", [])),
+ extensions=d.get("extensions"),
+ )
+
+
+def video_job_to_dict(j: VideoJobInfo) -> dict[str, Any]:
+ return _clean_mapping({
+ "id": j.id,
+ "status": j.status,
+ "progress": j.progress,
+ "created_at": j.created_at,
+ "model": j.model,
+ "provider_data": j.provider_data,
+ })
+
+
+def video_job_from_dict(d: dict[str, Any]) -> VideoJobInfo:
+ return VideoJobInfo(
+ id=d["id"],
+ status=d["status"],
+ progress=d.get("progress"),
+ created_at=d.get("created_at"),
+ model=d.get("model"),
+ provider_data=d.get("provider_data"),
+ )
+
+
+# ─── ModelInfo ───────────────────────────────────────────────────────
+
+def _inference_pricing_to_dict(p: InferencePricing) -> dict[str, Any]:
+ return _clean_mapping({
+ "input_per_million": p.input_per_million,
+ "output_per_million": p.output_per_million,
+ "cache_read_per_million": p.cache_read_per_million,
+ "cache_write_per_million": p.cache_write_per_million,
+ "currency": p.currency,
+ "dimensions": p.dimensions,
+ })
+
+
+def _inference_pricing_from_dict(d: dict[str, Any]) -> InferencePricing:
+ return InferencePricing(
+ input_per_million=d.get("input_per_million"),
+ output_per_million=d.get("output_per_million"),
+ cache_read_per_million=d.get("cache_read_per_million"),
+ cache_write_per_million=d.get("cache_write_per_million"),
+ currency=d.get("currency", "USD"),
+ dimensions=d.get("dimensions"),
+ )
+
+
+def _inference_model_info_to_dict(i: InferenceModelInfo) -> dict[str, Any]:
+ return _clean_mapping({
+ "input_modalities": list(i.input_modalities),
+ "output_modalities": list(i.output_modalities),
+ "context_window": i.context_window,
+ "max_output_tokens": i.max_output_tokens,
+ "supports_reasoning": i.supports_reasoning or None,
+ "reasoning_efforts": list(i.reasoning_efforts),
+ "pricing": _inference_pricing_to_dict(i.pricing) if i.pricing else None,
+ "extensions": i.extensions,
+ })
+
+
+def _inference_model_info_from_dict(d: dict[str, Any]) -> InferenceModelInfo:
+ return InferenceModelInfo(
+ input_modalities=tuple(d.get("input_modalities", ["text"])),
+ output_modalities=tuple(d.get("output_modalities", ["text"])),
+ context_window=d.get("context_window"),
+ max_output_tokens=d.get("max_output_tokens"),
+ supports_reasoning=d.get("supports_reasoning", False),
+ reasoning_efforts=tuple(d.get("reasoning_efforts", [])),
+ pricing=_inference_pricing_from_dict(d["pricing"]) if isinstance(d.get("pricing"), dict) else None,
+ extensions=d.get("extensions"),
+ )
+
+
+def _model_origin_to_dict(o: ModelOrigin) -> dict[str, Any]:
+ return _clean_mapping({
+ "type": o.type,
+ "id": o.id,
+ "base_model": o.base_model,
+ "provider_data": o.provider_data,
+ })
+
+
+def _model_origin_from_dict(d: dict[str, Any]) -> ModelOrigin:
+ return ModelOrigin(
+ type=d.get("type", "provider"),
+ id=d.get("id"),
+ base_model=d.get("base_model"),
+ provider_data=d.get("provider_data"),
+ )
+
+
+def model_info_to_dict(m: ModelInfo) -> dict[str, Any]:
+ origin = _model_origin_to_dict(m.origin)
+ if origin == {"type": "provider"}: # the default origin carries no information
+ origin = {}
+ return _clean_mapping({
+ "id": m.id,
+ "provider": m.provider,
+ "api_family": m.api_family,
+ "aliases": list(m.aliases),
+ "origin": origin,
+ "inference": _inference_model_info_to_dict(m.inference) if m.inference else None,
+ "extensions": m.extensions,
+ })
+
+
+def model_info_from_dict(d: dict[str, Any]) -> ModelInfo:
+ return ModelInfo(
+ id=d["id"],
+ provider=d["provider"],
+ api_family=d["api_family"],
+ aliases=tuple(d.get("aliases", [])),
+ origin=_model_origin_from_dict(d["origin"]) if isinstance(d.get("origin"), dict) else ModelOrigin(),
+ inference=_inference_model_info_from_dict(d["inference"]) if isinstance(d.get("inference"), dict) else None,
+ extensions=d.get("extensions"),
+ )
+
+
+# ─── AudioFormat ─────────────────────────────────────────────────────
+
+def audio_format_to_dict(af: AudioFormat) -> dict[str, Any]:
+ return _clean_mapping({
+ "encoding": af.encoding,
+ "sample_rate": af.sample_rate,
+ "channels": af.channels,
+ })
+
+
+def audio_format_from_dict(d: dict[str, Any]) -> AudioFormat:
+ return AudioFormat(
+ encoding=d["encoding"],
+ sample_rate=d["sample_rate"],
+ channels=d.get("channels", 1),
+ )
+
+
+# ─── LiveConfig ──────────────────────────────────────────────────────
+
+def live_config_to_dict(lc: LiveConfig) -> dict[str, Any]:
+ system: Any
+ if isinstance(lc.system, tuple):
+ system = [part_to_dict(p) for p in lc.system]
+ else:
+ system = lc.system
+ return _clean_mapping({
+ "model": lc.model,
+ "system": system,
+ "tools": [tool_to_dict(t) for t in lc.tools],
+ "voice": lc.voice,
+ "input_format": audio_format_to_dict(lc.input_format) if lc.input_format else None,
+ "output_format": audio_format_to_dict(lc.output_format) if lc.output_format else None,
+ "extensions": lc.extensions,
+ })
+
+
+def live_config_from_dict(d: dict[str, Any]) -> LiveConfig:
+ raw_system = d.get("system")
+ system: str | tuple[Part, ...] | None
+ if isinstance(raw_system, list):
+ system = tuple(part_from_dict(x) for x in raw_system)
+ else:
+ system = raw_system
+ return LiveConfig(
+ model=d["model"],
+ system=system,
+ tools=tuple(tool_from_dict(t) for t in d.get("tools", [])),
+ voice=d.get("voice"),
+ input_format=audio_format_from_dict(d["input_format"]) if isinstance(d.get("input_format"), dict) else None,
+ output_format=audio_format_from_dict(d["output_format"]) if isinstance(d.get("output_format"), dict) else None,
+ extensions=d.get("extensions"),
+ )
+
+
+# ─── LiveClientEvent / LiveServerEvent ───────────────────────────────
+
+def live_client_event_to_dict(e: LiveClientEvent) -> dict[str, Any]:
+ if isinstance(e, LiveClientTurnEvent):
+ return {"type": e.type, "parts": [part_to_dict(p) for p in e.parts], "turn_complete": e.turn_complete}
+ if isinstance(e, (LiveClientAudioEvent, LiveClientImageEvent)):
+ return {"type": e.type, "data": e.data, "media_type": e.media_type}
+ if isinstance(e, LiveClientTextEvent):
+ return {"type": e.type, "text": e.text}
+ if isinstance(e, LiveClientToolResultEvent):
+ return {"type": e.type, "id": e.id, "content": [part_to_dict(p) for p in e.content]}
+ if isinstance(e, (LiveClientInterruptEvent, LiveClientEndAudioEvent)):
+ return {"type": e.type}
+ raise TypeError(f"unsupported live client event type: {type(e)}")
+
+
+def live_client_event_from_dict(d: dict[str, Any]) -> LiveClientEvent:
+ t = d["type"]
+ if t == "turn":
+ return LiveClientTurnEvent(
+ parts=tuple(part_from_dict(p) for p in d.get("parts", [])),
+ turn_complete=d.get("turn_complete", True),
+ )
+ if t == "audio":
+ return LiveClientAudioEvent(data=d["data"], media_type=d.get("media_type", "audio/pcm;rate=16000"))
+ if t == "image":
+ return LiveClientImageEvent(data=d["data"], media_type=d.get("media_type", "image/jpeg"))
+ if t == "text":
+ return LiveClientTextEvent(text=d.get("text", ""))
+ if t == "tool_result":
+ return LiveClientToolResultEvent(
+ id=d["id"],
+ content=tuple(part_from_dict(p) for p in d.get("content", [])),
+ )
+ if t == "interrupt":
+ return LiveClientInterruptEvent()
+ if t == "end_audio":
+ return LiveClientEndAudioEvent()
+ raise ValueError(f"unsupported live client event type: {t}")
+
+
+def live_server_event_to_dict(e: LiveServerEvent) -> dict[str, Any]:
+ if isinstance(e, LiveServerAudioEvent):
+ return _clean_mapping({"type": e.type, "data": e.data, "media_type": e.media_type})
+ if isinstance(e, LiveServerTextEvent):
+ return {"type": e.type, "text": e.text}
+ if isinstance(e, LiveServerToolCallEvent):
+ return {"type": e.type, "id": e.id, "name": e.name, "input": e.input}
+ if isinstance(e, LiveServerToolCallDeltaEvent):
+ return _clean_mapping({
+ "type": e.type,
+ "id": e.id,
+ "name": e.name,
+ "input_delta": e.input_delta,
+ })
+ if isinstance(e, LiveServerInterruptedEvent):
+ return {"type": e.type}
+ if isinstance(e, LiveServerTurnEndEvent):
+ return _clean_mapping({"type": e.type, "usage": usage_to_dict(e.usage)})
+ if isinstance(e, LiveServerUsageEvent):
+ return _clean_mapping({"type": e.type, "usage": usage_to_dict(e.usage)})
+ if isinstance(e, LiveServerErrorEvent):
+ return {"type": e.type, "error": error_detail_to_dict(e.error)}
+ raise TypeError(f"unsupported live server event type: {type(e)}")
+
+
+def live_server_event_from_dict(d: dict[str, Any]) -> LiveServerEvent:
+ t = d["type"]
+ if t == "audio":
+ return LiveServerAudioEvent(data=d["data"], media_type=d.get("media_type"))
+ if t == "text":
+ return LiveServerTextEvent(text=d.get("text", ""))
+ if t == "tool_call":
+ return LiveServerToolCallEvent(id=d["id"], name=d["name"], input=d.get("input", {}))
+ if t == "tool_call_delta":
+ return LiveServerToolCallDeltaEvent(
+ input_delta=d.get("input_delta", ""), id=d.get("id"), name=d.get("name")
+ )
+ if t == "interrupted":
+ return LiveServerInterruptedEvent()
+ if t == "turn_end":
+ return LiveServerTurnEndEvent(usage=usage_from_dict(d.get("usage", {})))
+ if t == "usage":
+ return LiveServerUsageEvent(usage=usage_from_dict(d.get("usage", {})))
+ if t == "error":
+ return LiveServerErrorEvent(error=error_detail_from_dict(d["error"]))
+ raise ValueError(f"unsupported live server event type: {t}")
diff --git a/dspy/_vendor/lm15/sse.py b/dspy/_vendor/lm15/sse.py
new file mode 100644
index 000000000..93f99e592
--- /dev/null
+++ b/dspy/_vendor/lm15/sse.py
@@ -0,0 +1,105 @@
+"""
+lm15.sse — Server-Sent Events parser.
+
+Parses a byte-line iterator (from a streaming HTTP response) into
+typed SSEEvent objects.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import AsyncIterator, Iterator
+
+from .errors import TransportError
+
+
+@dataclass(frozen=True, slots=True)
+class SSEEvent:
+ event: str | None
+ data: str
+
+
+def parse_sse(
+ lines: Iterator[bytes],
+ *,
+ max_line_bytes: int = 64 * 1024,
+ max_event_bytes: int = 1024 * 1024,
+) -> Iterator[SSEEvent]:
+ """Parse SSE byte lines into events."""
+ event_name: str | None = None
+ data_lines: list[str] = []
+ event_bytes = 0
+
+ for raw in lines:
+ if len(raw) > max_line_bytes:
+ raise TransportError(f"SSE line exceeds limit ({len(raw)} > {max_line_bytes})")
+
+ line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+ event_bytes += len(raw)
+ if event_bytes > max_event_bytes:
+ raise TransportError(f"SSE event exceeds limit ({event_bytes} > {max_event_bytes})")
+
+ if line == "":
+ if data_lines:
+ yield SSEEvent(event=event_name, data="\n".join(data_lines))
+ event_name = None
+ data_lines = []
+ event_bytes = 0
+ continue
+
+ if line.startswith(":"):
+ continue
+ if line.startswith("event:"):
+ event_name = line[len("event:"):].strip()
+ continue
+ if line.startswith("data:"):
+ data_lines.append(line[len("data:"):].lstrip())
+ continue
+
+ if data_lines:
+ yield SSEEvent(event=event_name, data="\n".join(data_lines))
+
+
+async def aparse_sse(
+ lines: AsyncIterator[bytes],
+ *,
+ max_line_bytes: int = 64 * 1024,
+ max_event_bytes: int = 1024 * 1024,
+) -> AsyncIterator[SSEEvent]:
+ """Async mirror of :func:`parse_sse` over an async byte-line iterator.
+
+ Same field grammar and limits; the only difference is ``async for`` over
+ the line source.
+ """
+ event_name: str | None = None
+ data_lines: list[str] = []
+ event_bytes = 0
+
+ async for raw in lines:
+ if len(raw) > max_line_bytes:
+ raise TransportError(f"SSE line exceeds limit ({len(raw)} > {max_line_bytes})")
+
+ line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+ event_bytes += len(raw)
+ if event_bytes > max_event_bytes:
+ raise TransportError(f"SSE event exceeds limit ({event_bytes} > {max_event_bytes})")
+
+ if line == "":
+ if data_lines:
+ yield SSEEvent(event=event_name, data="\n".join(data_lines))
+ event_name = None
+ data_lines = []
+ event_bytes = 0
+ continue
+
+ if line.startswith(":"):
+ continue
+ if line.startswith("event:"):
+ event_name = line[len("event:"):].strip()
+ continue
+ if line.startswith("data:"):
+ data_lines.append(line[len("data:"):].lstrip())
+ continue
+
+ if data_lines:
+ yield SSEEvent(event=event_name, data="\n".join(data_lines))
diff --git a/dspy/_vendor/lm15/testing.py b/dspy/_vendor/lm15/testing.py
new file mode 100644
index 000000000..dd67a1fb4
--- /dev/null
+++ b/dspy/_vendor/lm15/testing.py
@@ -0,0 +1,168 @@
+"""
+lm15.testing — shipped test doubles for code built on lm15.
+
+Two seams, pick by what you are testing:
+
+- :class:`FakeLM` — a canonical-level provider double. Script it with
+ ``Response`` objects (or plain strings, or exceptions) and it answers
+ ``complete()`` / ``stream()`` with them, streaming via
+ ``response_to_events``. No wire format involved, works wherever a
+ provider LM does — the right seam for testing tool loops, retries,
+ and everything above the wire.
+- :class:`FakeTransport` / :class:`FakeResponse` — a wire-level double.
+ Inject it as any adapter's ``transport`` and the REAL adapter serde
+ runs both directions against your scripted HTTP bytes; the fake
+ records every ``TransportRequest`` so one fixture asserts behavior
+ AND wire format. The right seam for testing provider dialects.
+
+Both record the requests they serve. Neither performs any I/O.
+
+ from lm15.testing import FakeLM
+ lm = FakeLM(responses=["hello"])
+ assert lm.complete(request).text == "hello"
+
+The router accepts a transport too — ``RouterConfig(transport=...)`` —
+so routed code paths are testable without touching the LM cache.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, ClassVar, Iterator, Sequence
+
+from .features import EndpointSupport, ProviderManifest
+from .result import response_to_events
+from .types import (
+ Message,
+ Request,
+ Response,
+ StreamEvent,
+ TextPart,
+ Usage,
+)
+
+__all__ = ["FakeLM", "FakeTransport", "FakeResponse"]
+
+
+@dataclass
+class FakeResponse:
+ """A scripted wire response served by :class:`FakeTransport`.
+
+ ``body`` is the exact bytes the adapter will parse; ``chunks`` (when
+ given) is what streaming iteration yields instead — SSE tests script
+ the frames there.
+ """
+
+ status: int
+ body: bytes
+ headers: list[tuple[str, str]] | None = None
+ reason: str = "OK"
+ http_version: str = "HTTP/1.1"
+ chunks: list[bytes] | None = None
+
+ def __post_init__(self) -> None:
+ if self.headers is None:
+ self.headers = [("content-type", "application/json")]
+
+ def __enter__(self) -> "FakeResponse":
+ return self
+
+ def __exit__(self, exc_type, exc, tb) -> None:
+ return None
+
+ def __iter__(self) -> Iterator[bytes]:
+ yield from (self.chunks if self.chunks is not None else [self.body])
+
+ def read(self) -> bytes:
+ return b"".join(iter(self))
+
+ def header(self, name: str) -> str | None:
+ lname = name.lower()
+ for key, value in self.headers or []:
+ if key.lower() == lname:
+ return value
+ return None
+
+
+class FakeTransport:
+ """Wire-level double: serves scripted :class:`FakeResponse` objects
+ in order and records every request in ``.requests``.
+
+ Script an ``Exception`` instance instead of a response and it is
+ raised at request time (dropped-socket tests: script
+ ``lm15.transports.TransportError``).
+ """
+
+ def __init__(self, responses: Sequence[FakeResponse | Exception] | None = None) -> None:
+ self.responses: list[FakeResponse | Exception] = list(responses or [])
+ self.requests: list[Any] = []
+
+ def stream(self, request: Any) -> FakeResponse:
+ self.requests.append(request)
+ assert self.responses, (
+ "FakeTransport ran out of scripted responses "
+ f"(served {len(self.requests) - 1}, then got another request)"
+ )
+ item = self.responses.pop(0)
+ if isinstance(item, Exception):
+ raise item
+ return item
+
+
+def _as_response(item: "Response | str") -> Response:
+ if isinstance(item, Response):
+ return item
+ return Response(
+ id="fake",
+ model="fake",
+ message=Message.assistant(TextPart(str(item))),
+ finish_reason="stop",
+ usage=Usage(),
+ )
+
+
+class FakeLM:
+ """Canonical-level provider double.
+
+ Scripted with ``Response`` objects, plain strings (shorthand for a
+ text response), or ``Exception`` instances (raised in order).
+ ``stream()`` replays the same scripted response through
+ ``response_to_events``, so streaming code paths see exactly the
+ events a real adapter would emit for that response.
+ """
+
+ provider: str = "fake"
+ supports: ClassVar[EndpointSupport] = EndpointSupport(complete=True, stream=True)
+ manifest: ClassVar[ProviderManifest] = ProviderManifest(
+ provider="fake", supports=supports, auth_modes=(), env_keys=(),
+ )
+
+ def __init__(
+ self,
+ responses: Sequence["Response | str | Exception"] = (),
+ *,
+ provider: str = "fake",
+ ) -> None:
+ self.provider = provider
+ self._script: list[Any] = list(responses)
+ self.requests: list[Request] = []
+
+ def _next(self, request: Request) -> Response:
+ self.requests.append(request)
+ assert self._script, (
+ "FakeLM ran out of scripted responses "
+ f"(served {len(self.requests) - 1}, then got another request)"
+ )
+ item = self._script.pop(0)
+ if isinstance(item, Exception):
+ raise item
+ return _as_response(item)
+
+ def complete(self, request: Request) -> Response:
+ return self._next(request)
+
+ def stream(self, request: Request) -> Iterator[StreamEvent]:
+ return response_to_events(self._next(request))
+
+ def close(self) -> None: # symmetric with real adapters
+ return None
diff --git a/dspy/_vendor/lm15/tools.py b/dspy/_vendor/lm15/tools.py
new file mode 100644
index 000000000..8fee390f2
--- /dev/null
+++ b/dspy/_vendor/lm15/tools.py
@@ -0,0 +1,725 @@
+"""
+lm15.tools — derive a FunctionTool from a Python callable.
+
+Pure functions only. ``tool(fn)`` reads *fn*'s signature, type hints, and
+docstring, and returns an ordinary, frozen :class:`lm15.FunctionTool`.
+Nothing is registered, cached, wrapped, or executed. The JSON-Schema path
+remains primary and canonical: this module is sugar that *produces* that
+JSON. The wire format of FunctionTool is untouched (INV-033 intact).
+
+Design notes:
+
+* Derivation is eager: errors surface at definition time, never at request
+ time — matching the ``__post_init__`` validation culture of lm15.types.
+* Soft where the input is prose, hard where the input is types: docstring
+ parsing is best-effort (missing descriptions are never errors), while
+ type-hint mapping raises :class:`ToolDerivationError` rather than guess.
+* ``Optional[X]`` / ``X | None`` is about VALUE nullability and maps to
+ ``anyOf`` with ``{"type": "null"}``. Required-ness comes solely from the
+ presence of a default. The two axes are orthogonal.
+* No ``$ref`` / recursive schemas in v1: nested dataclasses and TypedDicts
+ are inlined, and cycles raise ToolDerivationError. Adding ``$ref`` later
+ is therefore an extension, not a behavior change.
+* Dispatch stays in user hands — lm15 never executes tools:
+
+ handlers = {fn.__name__: fn for fn in (get_weather,)}
+ result = handlers[call.name](**call.input)
+
+Stdlib only: inspect, typing, dataclasses, enum, types.
+"""
+
+from __future__ import annotations
+
+import collections.abc as _collections_abc
+import dataclasses
+import enum
+import inspect
+import math
+import types as _types
+import typing
+from dataclasses import dataclass, field
+from typing import Any, Callable, Literal, Union, get_args, get_origin, get_type_hints
+
+from .errors import LM15Error
+from .types import FunctionTool, JsonObject, JsonValue
+
+__all__ = [
+ "ToolDerivationError",
+ "ToolConfig",
+ "DerivedParam",
+ "ToolDerivation",
+ "tool",
+ "derive",
+]
+
+_ESCAPE_HATCH = (
+ "; override this parameter via ToolConfig(overrides=...) or pass an "
+ "explicit FunctionTool with hand-written parameters"
+)
+
+
+class ToolDerivationError(LM15Error):
+ """Raised when a callable cannot be derived into a FunctionTool.
+
+ Always names the function and, when applicable, the offending parameter
+ and the unsupported annotation, plus both escape hatches: a per-parameter
+ ``ToolConfig(overrides=...)`` entry, or a hand-written FunctionTool.
+ """
+
+ default_code = "tool_derivation"
+
+
+@dataclass(frozen=True, slots=True)
+class ToolConfig:
+ """Options for :func:`tool` / :func:`derive`.
+
+ Explicit over magic: every knob is visible.
+
+ docstring_style: ``"auto"`` tries Google, NumPy, then Sphinx
+ (``:param x:``) markers pragmatically; or pin one style; ``"none"``
+ skips parameter descriptions entirely.
+ include_defaults: emit JSON-compatible default values as ``"default"``
+ in the property schema. Informational only; never affects
+ required-ness. Non-JSON defaults are silently skipped (documented).
+ additional_properties_false: emit ``"additionalProperties": false`` on
+ the top-level object. Off by default (provider-neutral); some
+ providers' strict tool modes want this — see the cookbook caveat
+ about strict mode also requiring all properties to be required.
+ overrides: per-parameter raw JSON-Schema fragments used *in place of*
+ derivation for the named parameter, e.g.
+ ``(("when", {"type": "string", "format": "date-time"}),)``.
+ A surgical escape hatch: one un-derivable parameter no longer forces
+ a fully hand-written FunctionTool. Stored as a tuple of
+ ``(param_name, schema)`` pairs so ToolConfig stays a plain frozen
+ dataclass; a docstring description is still merged in when the
+ override fragment has no ``"description"`` of its own.
+ """
+
+ docstring_style: Literal["auto", "google", "numpy", "sphinx", "none"] = "auto"
+ include_defaults: bool = True
+ additional_properties_false: bool = False
+ overrides: tuple[tuple[str, JsonObject], ...] = ()
+
+ def __post_init__(self) -> None:
+ if self.docstring_style not in ("auto", "google", "numpy", "sphinx", "none"):
+ raise ValueError(
+ "ToolConfig.docstring_style must be one of "
+ "'auto', 'google', 'numpy', 'sphinx', 'none'"
+ )
+ if not isinstance(self.overrides, tuple):
+ raise TypeError(
+ "ToolConfig.overrides must be a tuple of (name, schema) pairs"
+ )
+ for entry in self.overrides:
+ if (
+ not isinstance(entry, tuple)
+ or len(entry) != 2
+ or not isinstance(entry[0], str)
+ or not isinstance(entry[1], dict)
+ ):
+ raise TypeError(
+ "ToolConfig.overrides entries must be (str, dict) pairs"
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class DerivedParam:
+ """Explainable record of how one parameter was derived."""
+
+ name: str
+ annotation: str # repr of the hint, e.g. "list[int] | None"
+ schema: JsonObject # the JSON-Schema fragment produced
+ required: bool
+ description: str | None # from docstring, if found
+ source: Literal["hint", "hint+docstring", "override", "override+docstring"]
+
+
+@dataclass(frozen=True, slots=True)
+class ToolDerivation:
+ """Full, typed account of a derivation — :func:`tool`'s explain() analogue.
+
+ Python-only diagnostic surface (other lm15 languages derive from
+ idiomatic sources — struct tags, macros, schema literals — and do not
+ mirror this type).
+ """
+
+ tool: FunctionTool
+ fn_qualname: str
+ params: tuple[DerivedParam, ...]
+ docstring_style_detected: Literal["google", "numpy", "sphinx", "plain", "none"]
+
+
+# ─── JSON-value check (for defaults and enum/Literal members) ────────
+
+def _is_json_value(value: object) -> bool:
+ if isinstance(value, float):
+ return math.isfinite(value) # NaN/Infinity are not JSON values
+ if value is None or isinstance(value, (str, bool, int)):
+ return True
+ if isinstance(value, (list, tuple)):
+ return all(_is_json_value(v) for v in value)
+ if isinstance(value, dict):
+ return all(isinstance(k, str) and _is_json_value(v) for k, v in value.items())
+ return False
+
+
+def _json_default(value: object) -> JsonValue:
+ if isinstance(value, tuple):
+ return [_json_default(v) for v in value]
+ if isinstance(value, list):
+ return [_json_default(v) for v in value]
+ if isinstance(value, dict):
+ return {k: _json_default(v) for k, v in value.items()}
+ return value # type: ignore[return-value]
+
+
+# ─── Hint → schema mapping ───────────────────────────────────────────
+
+_PRIMITIVES: dict[type, str] = {
+ str: "string",
+ int: "integer",
+ float: "number",
+ bool: "boolean",
+}
+
+_NONE_TYPE = type(None)
+
+
+def _err(fn_name: str, message: str) -> ToolDerivationError:
+ return ToolDerivationError(
+ f"cannot derive '{fn_name}': {message}{_ESCAPE_HATCH}"
+ )
+
+
+def _is_typed_dict(hint: object) -> bool:
+ return isinstance(hint, type) and hasattr(hint, "__required_keys__") and hasattr(
+ hint, "__optional_keys__"
+ )
+
+
+def _schema_for(
+ hint: object,
+ *,
+ fn_name: str,
+ param: str,
+ seen: frozenset[object],
+) -> JsonObject:
+ """Map one type hint to a JSON-Schema fragment. Conservative: anything
+ not obviously JSON-Schema-able raises ToolDerivationError."""
+
+ def fail(detail: str) -> ToolDerivationError:
+ return _err(fn_name, f"parameter '{param}' {detail}")
+
+ origin = get_origin(hint)
+
+ # Annotated[X, "text"]: first str metadata wins as description.
+ if origin is typing.Annotated:
+ base, *metadata = get_args(hint)
+ schema = _schema_for(base, fn_name=fn_name, param=param, seen=seen)
+ for meta in metadata:
+ if isinstance(meta, str):
+ schema = dict(schema)
+ schema["description"] = meta
+ break
+ return schema
+
+ # Any: explicitly-anything.
+ if hint is Any:
+ return {}
+
+ # None / NoneType.
+ if hint is None or hint is _NONE_TYPE:
+ return {"type": "null"}
+
+ # Unions (typing.Union and X | Y).
+ if origin is Union or origin is _types.UnionType:
+ members = [
+ _schema_for(arg, fn_name=fn_name, param=param, seen=seen)
+ for arg in get_args(hint)
+ ]
+ return {"anyOf": members}
+
+ # Literal["a", "b", 3] -> enum (+ type when homogeneous).
+ if origin is Literal:
+ values = get_args(hint)
+ for v in values:
+ if not (v is None or isinstance(v, (str, bool, int, float))):
+ raise fail(
+ f"has Literal value {v!r} that is not JSON-compatible"
+ )
+ schema = {"enum": list(values)}
+ kinds = {type(v) for v in values}
+ if len(kinds) == 1:
+ sole = next(iter(kinds))
+ if sole in _PRIMITIVES:
+ schema["type"] = _PRIMITIVES[sole]
+ elif sole is _NONE_TYPE:
+ schema["type"] = "null"
+ return schema
+
+ # Containers.
+ if origin in (list, typing.Sequence, _abc_sequence()):
+ args = get_args(hint)
+ if not args: # bare typing.List / typing.Sequence
+ return {"type": "array"}
+ items = _schema_for(args[0], fn_name=fn_name, param=param, seen=seen)
+ return {"type": "array", "items": items}
+ if origin in (set, frozenset):
+ args = get_args(hint)
+ if not args: # bare typing.Set / typing.FrozenSet
+ return {"type": "array", "uniqueItems": True}
+ items = _schema_for(args[0], fn_name=fn_name, param=param, seen=seen)
+ return {"type": "array", "items": items, "uniqueItems": True}
+ if origin is tuple:
+ args = get_args(hint)
+ if not args: # bare typing.Tuple
+ return {"type": "array"}
+ if len(args) == 2 and args[1] is Ellipsis:
+ items = _schema_for(args[0], fn_name=fn_name, param=param, seen=seen)
+ return {"type": "array", "items": items}
+ raise fail(
+ f"has fixed-length tuple annotation {_annotation_repr(hint)}; "
+ "only homogeneous tuple[X, ...] is supported"
+ )
+ if origin in (dict, typing.Mapping, _abc_mapping()):
+ dict_args = get_args(hint)
+ if not dict_args: # bare typing.Dict / typing.Mapping
+ return {"type": "object"}
+ key_t, value_t = dict_args
+ if key_t is not str:
+ raise fail(
+ f"has dict annotation with non-str keys ({_annotation_repr(hint)}); "
+ "JSON object keys must be strings"
+ )
+ value_schema = _schema_for(value_t, fn_name=fn_name, param=param, seen=seen)
+ return {"type": "object", "additionalProperties": value_schema}
+
+ if origin is not None:
+ raise fail(f"has unsupported annotation {_annotation_repr(hint)}")
+
+ # Bare (unparameterized) types.
+ if isinstance(hint, type):
+ if hint in _PRIMITIVES:
+ # NB: bool before int matters in isinstance checks, but here the
+ # dict lookup is exact, so bool maps to "boolean" correctly.
+ return {"type": _PRIMITIVES[hint]}
+ if hint in (list, tuple):
+ return {"type": "array"}
+ if hint in (set, frozenset):
+ return {"type": "array", "uniqueItems": True}
+ if hint is dict:
+ return {"type": "object"}
+
+ # Enum subclass -> enum of member values (values must be JSON).
+ if issubclass(hint, enum.Enum):
+ values = [member.value for member in hint]
+ for v in values:
+ if not (v is None or isinstance(v, (str, bool, int, float))):
+ raise fail(
+ f"uses Enum {hint.__name__!s} whose member value {v!r} "
+ "is not JSON-compatible"
+ )
+ return {"enum": values}
+
+ # TypedDict -> nested object (no $ref/recursion in v1).
+ if _is_typed_dict(hint):
+ if hint in seen:
+ raise fail(
+ f"has recursive TypedDict annotation {hint.__name__!s}; "
+ "recursive ($ref) schemas are not supported in v1"
+ )
+ try:
+ nested_hints = get_type_hints(hint, include_extras=True)
+ except Exception as exc:
+ raise fail(
+ f"has TypedDict annotation {hint.__name__!s} whose hints "
+ f"could not be resolved ({exc})"
+ ) from exc
+ nested_seen = seen | {hint}
+ properties: JsonObject = {}
+ for key, key_hint in nested_hints.items():
+ properties[key] = _schema_for(
+ key_hint, fn_name=fn_name, param=f"{param}.{key}", seen=nested_seen
+ )
+ required = [k for k in nested_hints if k in hint.__required_keys__]
+ schema = {"type": "object", "properties": properties}
+ if required:
+ schema["required"] = required
+ return schema
+
+ # @dataclass class -> nested object from its fields (same rules).
+ if dataclasses.is_dataclass(hint):
+ if hint in seen:
+ raise fail(
+ f"has recursive dataclass annotation {hint.__name__!s}; "
+ "recursive ($ref) schemas are not supported in v1"
+ )
+ try:
+ nested_hints = get_type_hints(hint, include_extras=True)
+ except Exception as exc:
+ raise fail(
+ f"has dataclass annotation {hint.__name__!s} whose hints "
+ f"could not be resolved ({exc})"
+ ) from exc
+ nested_seen = seen | {hint}
+ properties = {}
+ required = []
+ for f in dataclasses.fields(hint):
+ if not f.init:
+ continue
+ properties[f.name] = _schema_for(
+ nested_hints.get(f.name, f.type),
+ fn_name=fn_name,
+ param=f"{param}.{f.name}",
+ seen=nested_seen,
+ )
+ if (
+ f.default is dataclasses.MISSING
+ and f.default_factory is dataclasses.MISSING
+ ):
+ required.append(f.name)
+ schema = {"type": "object", "properties": properties}
+ if required:
+ schema["required"] = required
+ return schema
+
+ raise fail(
+ f"has unsupported annotation {_annotation_repr(hint)}; annotate with "
+ "a JSON-compatible type"
+ )
+
+
+def _abc_sequence() -> object:
+ return _collections_abc.Sequence
+
+
+def _abc_mapping() -> object:
+ return _collections_abc.Mapping
+
+
+def _annotation_repr(hint: object) -> str:
+ if isinstance(hint, type):
+ module = getattr(hint, "__module__", "")
+ if module and module != "builtins":
+ return f"{module}.{hint.__qualname__}"
+ return hint.__qualname__
+ return repr(hint)
+
+
+# ─── Docstring parsing (pragmatic line-marker detection, not a parser) ───
+
+def _docstring_summary(doc: str) -> str | None:
+ lines = doc.strip().splitlines()
+ summary: list[str] = []
+ for line in lines:
+ if not line.strip():
+ break
+ summary.append(line.strip())
+ return " ".join(summary) if summary else None
+
+
+def _parse_google(doc: str) -> dict[str, str] | None:
+ lines = doc.splitlines()
+ out: dict[str, str] = {}
+ in_args = False
+ current: str | None = None
+ section_indent = 0
+ for line in lines:
+ stripped = line.strip()
+ if stripped in ("Args:", "Arguments:", "Parameters:"):
+ in_args = True
+ current = None
+ continue
+ if not in_args:
+ continue
+ if not stripped:
+ current = None
+ continue
+ indent = len(line) - len(line.lstrip())
+ if stripped.endswith(":") and " " not in stripped and indent == 0:
+ break # next top-level section
+ if ":" in stripped:
+ name_part, _, desc = stripped.partition(":")
+ name = name_part.split("(")[0].strip()
+ if name.isidentifier():
+ out[name] = desc.strip()
+ current = name
+ section_indent = indent
+ continue
+ if current is not None and indent > section_indent:
+ out[current] = (out[current] + " " + stripped).strip()
+ return out or None
+
+
+def _parse_numpy(doc: str) -> dict[str, str] | None:
+ lines = doc.splitlines()
+ out: dict[str, str] = {}
+ in_params = False
+ current: str | None = None
+ i = 0
+ while i < len(lines):
+ stripped = lines[i].strip()
+ if stripped in ("Parameters", "Other Parameters") and i + 1 < len(lines) and set(
+ lines[i + 1].strip()
+ ) == {"-"}:
+ in_params = True
+ current = None
+ i += 2
+ continue
+ if in_params:
+ if stripped and i + 1 < len(lines) and set(lines[i + 1].strip() or ".") == {"-"}:
+ break # next underlined section
+ if not stripped:
+ current = None
+ else:
+ indent = len(lines[i]) - len(lines[i].lstrip())
+ name = stripped.split(":")[0].strip()
+ if indent == 0 and name.isidentifier():
+ out[name] = ""
+ current = name
+ elif current is not None:
+ out[current] = (out[current] + " " + stripped).strip()
+ i += 1
+ return {k: v for k, v in out.items()} or None
+
+
+def _parse_sphinx(doc: str) -> dict[str, str] | None:
+ out: dict[str, str] = {}
+ current: str | None = None
+ for line in doc.splitlines():
+ stripped = line.strip()
+ if stripped.startswith(":param "):
+ rest = stripped[len(":param "):]
+ name_part, _, desc = rest.partition(":")
+ name = name_part.split()[-1] if name_part.split() else ""
+ if name.isidentifier():
+ out[name] = desc.strip()
+ current = name
+ continue
+ if stripped.startswith(":"):
+ current = None
+ continue
+ if current is not None and stripped:
+ out[current] = (out[current] + " " + stripped).strip()
+ elif not stripped:
+ current = None
+ return out or None
+
+
+def _parse_docstring(
+ doc: str | None, style: str
+) -> tuple[dict[str, str], Literal["google", "numpy", "sphinx", "plain", "none"]]:
+ if not doc:
+ return {}, "none"
+ if style == "none":
+ return {}, "plain"
+ attempts: tuple[tuple[str, Callable[[str], dict[str, str] | None]], ...]
+ if style == "auto":
+ attempts = (
+ ("google", _parse_google),
+ ("numpy", _parse_numpy),
+ ("sphinx", _parse_sphinx),
+ )
+ else:
+ parser = {"google": _parse_google, "numpy": _parse_numpy, "sphinx": _parse_sphinx}[style]
+ attempts = ((style, parser),) # type: ignore[assignment]
+ for detected, parser in attempts:
+ result = parser(doc)
+ if result:
+ return result, detected # type: ignore[return-value]
+ return {}, "plain"
+
+
+# ─── Public API ──────────────────────────────────────────────────────
+
+def derive(
+ fn: Callable[..., Any],
+ *,
+ name: str | None = None,
+ description: str | None = None,
+ config: ToolConfig = ToolConfig(),
+) -> ToolDerivation:
+ """Derive a FunctionTool from *fn* with a full, typed account.
+
+ Like :func:`tool`, but returns the :class:`ToolDerivation` so users can
+ inspect exactly how each parameter was mapped (explainability parity
+ with the explain() ethos). ``tool(fn)`` is sugar for ``derive(fn).tool``.
+ """
+ if not callable(fn):
+ raise ToolDerivationError(
+ f"cannot derive tool from non-callable {fn!r}{_ESCAPE_HATCH}"
+ )
+
+ fn_name = name
+ if fn_name is None:
+ fn_name = getattr(fn, "__name__", None)
+ if fn_name is None:
+ raise ToolDerivationError(
+ f"cannot derive tool from {fn!r}: it has no __name__; "
+ f"pass name= explicitly{_ESCAPE_HATCH}"
+ )
+ if fn_name == "<lambda>":
+ raise ToolDerivationError(
+ "cannot derive tool from a lambda: '<lambda>' is not a usable "
+ f"tool name; pass name= explicitly{_ESCAPE_HATCH}"
+ )
+
+ try:
+ signature = inspect.signature(fn)
+ except (ValueError, TypeError) as exc:
+ raise _err(
+ fn_name,
+ f"its signature is not introspectable ({exc})",
+ ) from exc
+
+ try:
+ hints = get_type_hints(fn, include_extras=True)
+ except NameError as exc:
+ raise _err(
+ fn_name,
+ f"a type annotation could not be resolved ({exc}); forward "
+ "references must be importable at derivation time — define the "
+ "referenced type before calling derive(), or annotate with a "
+ "resolvable JSON-compatible type",
+ ) from exc
+ except Exception as exc:
+ raise _err(
+ fn_name, f"type hints could not be resolved ({exc})"
+ ) from exc
+
+ overrides = dict(config.overrides)
+ doc = inspect.getdoc(fn)
+ param_docs, detected = _parse_docstring(doc, config.docstring_style)
+
+ derived: list[DerivedParam] = []
+ properties: JsonObject = {}
+ required: list[str] = []
+
+ parameters = list(signature.parameters.values())
+ # Bound methods and classmethods already have self/cls stripped by
+ # inspect.signature; an explicit leading self/cls only remains on plain
+ # unbound functions, where it is treated as an ordinary parameter.
+
+ for p in parameters:
+ if p.kind is inspect.Parameter.VAR_POSITIONAL:
+ raise _err(
+ fn_name,
+ f"parameter '*{p.name}' is variadic; tool signatures must be "
+ "fully nameable — wrap the function",
+ )
+ if p.kind is inspect.Parameter.VAR_KEYWORD:
+ raise _err(
+ fn_name,
+ f"parameter '**{p.name}' is variadic; tool signatures must "
+ "be fully nameable — wrap the function",
+ )
+ if p.kind is inspect.Parameter.POSITIONAL_ONLY:
+ raise _err(
+ fn_name,
+ f"parameter '{p.name}' is positional-only; tool calls "
+ "dispatch by name — make it keyword-able",
+ )
+
+ doc_desc = param_docs.get(p.name)
+
+ if p.name in overrides:
+ schema = dict(overrides[p.name])
+ if doc_desc and "description" not in schema:
+ schema["description"] = doc_desc
+ source: Literal[
+ "hint", "hint+docstring", "override", "override+docstring"
+ ] = "override+docstring" if doc_desc else "override"
+ annotation_repr = (
+ _annotation_repr(hints[p.name]) if p.name in hints else "<override>"
+ )
+ else:
+ if p.name not in hints:
+ raise _err(
+ fn_name,
+ f"parameter '{p.name}' has no type annotation",
+ )
+ hint = hints[p.name]
+ schema = _schema_for(
+ hint, fn_name=fn_name, param=p.name, seen=frozenset()
+ )
+ schema = dict(schema)
+ if doc_desc and "description" not in schema:
+ schema["description"] = doc_desc
+ source = "hint+docstring" if doc_desc else "hint"
+ annotation_repr = _annotation_repr(hint)
+
+ is_required = p.default is inspect.Parameter.empty
+ if is_required:
+ required.append(p.name)
+ elif (
+ config.include_defaults
+ and "default" not in schema
+ and _is_json_value(p.default)
+ ):
+ schema["default"] = _json_default(p.default)
+
+ properties[p.name] = schema
+ derived.append(
+ DerivedParam(
+ name=p.name,
+ annotation=annotation_repr,
+ schema=schema,
+ required=is_required,
+ description=schema.get("description"), # type: ignore[arg-type]
+ source=source,
+ )
+ )
+
+ unknown_overrides = set(overrides) - set(signature.parameters)
+ if unknown_overrides:
+ raise _err(
+ fn_name,
+ "ToolConfig.overrides names parameters not in the signature: "
+ + ", ".join(sorted(unknown_overrides)),
+ )
+
+ schema_top: JsonObject = {"type": "object", "properties": properties}
+ if required:
+ schema_top["required"] = required
+ if config.additional_properties_false:
+ schema_top["additionalProperties"] = False
+
+ tool_description = description
+ if tool_description is None and doc:
+ tool_description = _docstring_summary(doc)
+
+ derived_tool = FunctionTool(
+ name=fn_name,
+ description=tool_description,
+ parameters=schema_top,
+ )
+
+ return ToolDerivation(
+ tool=derived_tool,
+ fn_qualname=getattr(fn, "__qualname__", fn_name),
+ params=tuple(derived),
+ docstring_style_detected=detected,
+ )
+
+
+def tool(
+ fn: Callable[..., Any],
+ *,
+ name: str | None = None,
+ description: str | None = None,
+ config: ToolConfig = ToolConfig(),
+) -> FunctionTool:
+ """Derive a FunctionTool from *fn*. Pure; returns a plain FunctionTool.
+
+ ``name``/``description`` override derivation (name falls back to
+ ``fn.__name__``, description to the docstring summary paragraph, else
+ None). A parameter is required iff it has no default; ``Optional[X]``
+ affects only value nullability (``anyOf`` with null), never
+ required-ness. See the module docstring for the full mapping table and
+ :class:`ToolConfig` for the knobs.
+
+ Deliberately not a decorator: a decorator would replace or wrap the
+ function — magic. Call ``tool(fn)`` and keep *fn* yourself; dispatch with
+ ``{f.__name__: f for f in (...)}``.
+ """
+ return derive(fn, name=name, description=description, config=config).tool
diff --git a/dspy/_vendor/lm15/transports/__init__.py b/dspy/_vendor/lm15/transports/__init__.py
new file mode 100644
index 000000000..99991dd27
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/__init__.py
@@ -0,0 +1,39 @@
+"""
+lm15.transports — Minimal stdlib-only HTTP/1.1 transports.
+
+Public API:
+ TransportRequest, TransportResponse — transport-level request/response models
+ StdlibTransport — sync transport (blocking, socket-based)
+ StdlibAsyncTransport — async transport (asyncio-native)
+ TransportError + subclasses
+"""
+
+from ._exceptions import (
+ ConnectError,
+ ConnectTimeout,
+ ProtocolError,
+ ReadError,
+ ReadTimeout,
+ TransportError,
+ WriteError,
+ WriteTimeout,
+)
+from ._types import TransportRequest, TransportResponse, AsyncTransportResponse
+from ._sync import StdlibTransport
+from ._async import StdlibAsyncTransport
+
+__all__ = [
+ "TransportRequest",
+ "TransportResponse",
+ "AsyncTransportResponse",
+ "StdlibTransport",
+ "StdlibAsyncTransport",
+ "TransportError",
+ "ConnectError",
+ "ConnectTimeout",
+ "ReadError",
+ "ReadTimeout",
+ "WriteError",
+ "WriteTimeout",
+ "ProtocolError",
+]
diff --git a/dspy/_vendor/lm15/transports/_async.py b/dspy/_vendor/lm15/transports/_async.py
new file mode 100644
index 000000000..747c16116
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_async.py
@@ -0,0 +1,563 @@
+"""
+Async transport built on `asyncio.open_connection`.
+
+Mirror of _sync.py but async end-to-end. Key differences:
+
+- `asyncio.open_connection` gives us a (reader, writer) pair, not a raw socket.
+- Stale-connection detection: we peek at the reader's transport socket with
+ select (fd-level), same trick as the sync side.
+- Cancellation correctness: if the caller's task is cancelled mid-stream,
+ we must close the writer (not return it to the pool), then re-raise
+ CancelledError without awaiting anything that could itself be cancelled.
+- Timeouts use `asyncio.wait_for`. We avoid `asyncio.timeout` (3.11+) to
+ stay Python 3.10-compatible.
+"""
+from __future__ import annotations
+
+import asyncio
+import select
+import socket
+import ssl
+from typing import AsyncIterator
+
+from ._exceptions import (
+ ConnectError,
+ ConnectTimeout,
+ ProtocolError,
+ ReadError,
+ ReadTimeout,
+ TransportError,
+ WriteError,
+ WriteTimeout,
+)
+from ._http11 import (
+ ResponseHeadParser,
+ build_request_head,
+)
+from ._proxy import ProxyRoute, connect_payload, proxy_route_for, route_origin
+from ._ssl import make_ssl_context
+from ._types import AsyncTransportResponse, TransportRequest
+from ._url import ParsedURL, parse_url
+
+
+_DEFAULT_CONNECT_TIMEOUT = 10.0
+_DEFAULT_READ_TIMEOUT = 60.0
+_DEFAULT_WRITE_TIMEOUT = 60.0
+_READ_CHUNK = 64 * 1024
+
+
+# ─── Async connection wrapper ────────────────────────────────────────
+
+
+class _AsyncConnection:
+ __slots__ = ("origin", "reader", "writer", "closed")
+
+ def __init__(
+ self,
+ origin: tuple[str, str, int],
+ reader: asyncio.StreamReader,
+ writer: asyncio.StreamWriter,
+ ) -> None:
+ self.origin = origin
+ self.reader = reader
+ self.writer = writer
+ self.closed = False
+
+ def is_stale(self) -> bool:
+ if self.closed:
+ return True
+ # Look at the underlying socket's FD for readability
+ try:
+ sock = self.writer.get_extra_info("socket")
+ except Exception:
+ return True
+ if sock is None:
+ return True
+ try:
+ r, _, _ = select.select([sock], [], [], 0)
+ if not r:
+ return False
+ # Readable on an idle keepalive means EOF/close_notify or
+ # unexpected unread bytes, so the connection is not safe to reuse.
+ # Avoid MSG_PEEK: TLS sockets/proxies may reject non-zero recv()
+ # flags, and peeking is unnecessary once select() reports readable.
+ return True
+ except (OSError, ValueError):
+ return True
+
+ def close(self) -> None:
+ if self.closed:
+ return
+ self.closed = True
+ try:
+ self.writer.close()
+ except Exception:
+ pass
+
+
+# ─── Async pool ──────────────────────────────────────────────────────
+
+
+class _AsyncConnectionPool:
+ def __init__(self, max_connections: int) -> None:
+ self._max = max_connections
+ self._idle: dict[tuple[str, str, int], list[_AsyncConnection]] = {}
+ self._in_use: set[_AsyncConnection] = set()
+ self._lock = asyncio.Lock()
+ self._slot = asyncio.Semaphore(max_connections)
+ self._total_opened = 0
+ self._closed = False
+
+ async def acquire_slot(self, timeout: float | None = None) -> None:
+ if self._closed:
+ raise TransportError("transport is closed")
+ if timeout is None:
+ await self._slot.acquire()
+ return
+ try:
+ await asyncio.wait_for(self._slot.acquire(), timeout=timeout)
+ except asyncio.TimeoutError:
+ raise TransportError("timed out waiting for connection pool slot")
+
+ def release_slot(self) -> None:
+ self._slot.release()
+
+ async def checkout(self, origin: tuple[str, str, int]) -> _AsyncConnection | None:
+ async with self._lock:
+ q = self._idle.get(origin)
+ while q:
+ conn = q.pop()
+ if conn.is_stale():
+ conn.close()
+ continue
+ self._in_use.add(conn)
+ return conn
+ return None
+
+ async def checkin(self, conn: _AsyncConnection) -> None:
+ async with self._lock:
+ self._in_use.discard(conn)
+ if self._closed or conn.closed:
+ conn.close()
+ return
+ self._idle.setdefault(conn.origin, []).append(conn)
+
+ async def discard(self, conn: _AsyncConnection) -> None:
+ async with self._lock:
+ self._in_use.discard(conn)
+ conn.close()
+
+ async def register_new(self, conn: _AsyncConnection) -> None:
+ async with self._lock:
+ self._in_use.add(conn)
+ self._total_opened += 1
+
+ def stats(self) -> dict:
+ return {
+ "idle": sum(len(q) for q in self._idle.values()),
+ "in_use": len(self._in_use),
+ "total_opened": self._total_opened,
+ }
+
+ async def close_all(self) -> None:
+ async with self._lock:
+ self._closed = True
+ for q in self._idle.values():
+ for conn in q:
+ conn.close()
+ self._idle.clear()
+ for conn in list(self._in_use):
+ conn.close()
+ self._in_use.clear()
+
+
+# ─── Transport ───────────────────────────────────────────────────────
+
+
+class StdlibAsyncTransport:
+ def __init__(
+ self,
+ *,
+ connect_timeout: float = _DEFAULT_CONNECT_TIMEOUT,
+ read_timeout: float = _DEFAULT_READ_TIMEOUT,
+ write_timeout: float = _DEFAULT_WRITE_TIMEOUT,
+ max_connections: int = 10,
+ verify: bool = True,
+ ca_bundle: str | None = None,
+ user_agent: str = "lm15/stdlib",
+ proxy: str | None = None,
+ trust_env: bool = True,
+ ) -> None:
+ self._connect_timeout = connect_timeout
+ self._read_timeout = read_timeout
+ self._write_timeout = write_timeout
+ self._user_agent = user_agent
+ self._verify = verify
+ self._ca_bundle = ca_bundle
+ self._proxy = proxy
+ self._trust_env = trust_env
+ self._ssl_ctx: ssl.SSLContext | None = None
+ self._pool = _AsyncConnectionPool(max_connections)
+ self._closed = False
+
+ def _get_ssl_ctx(self) -> ssl.SSLContext:
+ if self._ssl_ctx is None:
+ self._ssl_ctx = make_ssl_context(
+ verify=self._verify, ca_bundle=self._ca_bundle
+ )
+ return self._ssl_ctx
+
+ def pool_stats(self) -> dict:
+ return self._pool.stats()
+
+ async def aclose(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ await self._pool.close_all()
+
+ async def __aenter__(self) -> "StdlibAsyncTransport":
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb) -> None:
+ await self.aclose()
+
+ # ─── Main entry point ───
+
+ def stream(self, request: TransportRequest) -> "_AsyncStreamCM":
+ """Return an async context manager that produces an AsyncTransportResponse."""
+ return _AsyncStreamCM(self, request)
+
+ async def _do_stream(self, request: TransportRequest) -> AsyncTransportResponse:
+ if self._closed:
+ raise TransportError("transport is closed")
+
+ parsed = parse_url(request.url)
+ proxy = proxy_route_for(parsed, proxy=self._proxy, trust_env=self._trust_env)
+ origin = route_origin(parsed, proxy)
+ connect_timeout = request.connect_timeout or self._connect_timeout
+ read_timeout = request.read_timeout or self._read_timeout
+ write_timeout = request.write_timeout or self._write_timeout
+
+ await self._pool.acquire_slot(timeout=connect_timeout * 5)
+ slot_released = {"done": False}
+
+ def release_slot_once() -> None:
+ if not slot_released["done"]:
+ slot_released["done"] = True
+ self._pool.release_slot()
+
+ conn: _AsyncConnection | None = None
+ try:
+ attempt = 0
+ while True:
+ conn = (
+ await self._pool.checkout(origin) if attempt == 0 else None
+ )
+ reused = conn is not None
+ if conn is None:
+ conn = await self._open(
+ parsed, proxy=proxy, origin=origin, connect_timeout=connect_timeout
+ )
+ await self._pool.register_new(conn)
+
+ try:
+ await self._send_request(
+ conn, request, parsed, proxy=proxy, write_timeout=write_timeout
+ )
+ break
+ except (WriteError, ConnectionResetError, BrokenPipeError, OSError) as exc:
+ if not reused or attempt > 0:
+ await self._pool.discard(conn)
+ if isinstance(exc, WriteError):
+ raise
+ raise WriteError(str(exc)) from exc
+ await self._pool.discard(conn)
+ conn = None
+ attempt += 1
+ continue
+
+ head = await self._read_head(conn, read_timeout=read_timeout)
+ decoder = head.body_decoder(request.method)
+ keep_alive = head.keep_alive()
+
+ release_conn = self._make_release(conn, keep_alive)
+
+ async def chunks_gen() -> AsyncIterator[bytes]:
+ aborted = False
+ try:
+ if head.leftover:
+ for out in decoder.feed(head.leftover):
+ if out:
+ yield out
+ if decoder.complete:
+ return
+ while not decoder.complete:
+ try:
+ data = await asyncio.wait_for(
+ conn.reader.read(_READ_CHUNK),
+ timeout=read_timeout,
+ )
+ except asyncio.TimeoutError as exc:
+ aborted = True
+ raise ReadTimeout("read timed out mid-body") from exc
+ except asyncio.CancelledError:
+ aborted = True
+ raise
+ except OSError as exc:
+ aborted = True
+ raise ReadError(f"read failed: {exc}") from exc
+ if not data:
+ try:
+ decoder.eof()
+ except ProtocolError:
+ aborted = True
+ raise
+ break
+ try:
+ for out in decoder.feed(data):
+ if out:
+ yield out
+ except ProtocolError:
+ aborted = True
+ raise
+ finally:
+ if aborted:
+ release_slot_once()
+
+ async def release_with_slot(body_consumed: bool) -> None:
+ try:
+ await release_conn(body_consumed)
+ finally:
+ release_slot_once()
+
+ return AsyncTransportResponse(
+ status=head.status,
+ reason=head.reason,
+ headers=head.headers,
+ http_version=head.http_version,
+ chunks=chunks_gen(),
+ release=release_with_slot,
+ )
+ except BaseException:
+ if conn is not None:
+ await self._pool.discard(conn)
+ release_slot_once()
+ raise
+
+ # ─── Connection I/O ───
+
+ async def _open(
+ self,
+ parsed: ParsedURL,
+ *,
+ proxy: ProxyRoute | None,
+ origin: tuple[str, str, int],
+ connect_timeout: float,
+ ) -> _AsyncConnection:
+ ctx = self._get_ssl_ctx() if parsed.is_tls else None
+
+ if proxy is not None and parsed.is_tls:
+ # CONNECT over a raw socket, then hand it to open_connection
+ # for the end-to-end TLS handshake (works on 3.10; StreamWriter
+ # gained start_tls only in 3.11).
+ tunnel = await self._connect_tunnel(parsed, proxy, timeout=connect_timeout)
+ try:
+ reader, writer = await asyncio.wait_for(
+ asyncio.open_connection(
+ sock=tunnel, ssl=ctx, server_hostname=parsed.host
+ ),
+ timeout=connect_timeout,
+ )
+ except asyncio.TimeoutError as exc:
+ tunnel.close()
+ raise ConnectTimeout("TLS handshake through proxy timed out") from exc
+ except ssl.SSLError as exc:
+ tunnel.close()
+ raise ConnectError(f"TLS handshake failed: {exc}") from exc
+ except OSError as exc:
+ tunnel.close()
+ raise ConnectError(f"TLS handshake through proxy failed: {exc}") from exc
+ return _AsyncConnection(origin, reader, writer)
+
+ connect_host = proxy.host if proxy is not None else parsed.host
+ connect_port = proxy.port if proxy is not None else parsed.port
+ try:
+ reader, writer = await asyncio.wait_for(
+ asyncio.open_connection(
+ host=connect_host,
+ port=connect_port,
+ ssl=ctx,
+ server_hostname=parsed.host if ctx else None,
+ ),
+ timeout=connect_timeout,
+ )
+ except asyncio.TimeoutError as exc:
+ raise ConnectTimeout(
+ f"timed out connecting to {connect_host}:{connect_port}"
+ ) from exc
+ except ssl.SSLError as exc:
+ raise ConnectError(f"TLS handshake failed: {exc}") from exc
+ except OSError as exc:
+ raise ConnectError(
+ f"failed to connect to {connect_host}:{connect_port}: {exc}"
+ ) from exc
+
+ # TCP_NODELAY on the underlying socket
+ sock = writer.get_extra_info("socket")
+ if sock is not None:
+ try:
+ sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+ except OSError:
+ pass
+
+ return _AsyncConnection(origin, reader, writer)
+
+ async def _connect_tunnel(
+ self, parsed: ParsedURL, proxy: ProxyRoute, *, timeout: float
+ ) -> socket.socket:
+ """Open a raw socket to the proxy and CONNECT it to the TLS target."""
+ loop = asyncio.get_running_loop()
+ try:
+ sock = await asyncio.wait_for(
+ asyncio.to_thread(
+ socket.create_connection, (proxy.host, proxy.port), timeout
+ ),
+ timeout=timeout,
+ )
+ except asyncio.TimeoutError as exc:
+ raise ConnectTimeout(
+ f"timed out connecting to proxy {proxy.host}:{proxy.port}"
+ ) from exc
+ except OSError as exc:
+ raise ConnectError(
+ f"failed to connect to proxy {proxy.host}:{proxy.port}: {exc}"
+ ) from exc
+ sock.setblocking(False)
+ try:
+ try:
+ sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+ except OSError:
+ pass
+ await asyncio.wait_for(
+ loop.sock_sendall(sock, connect_payload(parsed, proxy)), timeout=timeout
+ )
+ parser = ResponseHeadParser()
+ while not parser.complete:
+ data = await asyncio.wait_for(
+ loop.sock_recv(sock, _READ_CHUNK), timeout=timeout
+ )
+ if not data:
+ raise ConnectError("proxy closed connection during CONNECT")
+ parser.feed(data)
+ if not (200 <= parser.status < 300):
+ raise ConnectError(
+ f"proxy refused CONNECT to {proxy.authority(parsed)}: "
+ f"{parser.status} {parser.reason}"
+ )
+ if parser.leftover:
+ raise ProtocolError("proxy sent unexpected bytes after the CONNECT response")
+ except asyncio.TimeoutError as exc:
+ sock.close()
+ raise ConnectTimeout(
+ f"CONNECT via {proxy.host}:{proxy.port} timed out"
+ ) from exc
+ except (ConnectError, ProtocolError):
+ sock.close()
+ raise
+ except OSError as exc:
+ sock.close()
+ raise ConnectError(f"CONNECT via {proxy.host}:{proxy.port} failed: {exc}") from exc
+ return sock
+
+ async def _send_request(
+ self,
+ conn: _AsyncConnection,
+ request: TransportRequest,
+ parsed: ParsedURL,
+ *,
+ proxy: ProxyRoute | None,
+ write_timeout: float,
+ ) -> None:
+ body = request.body or b""
+ has_body = request.method.upper() not in ("GET", "HEAD", "DELETE") or bool(body)
+ body_length = len(body) if has_body else None
+ target = parsed.target
+ headers = request.headers
+ if proxy is not None and not parsed.is_tls:
+ # Forward-proxy plain HTTP: absolute-URI request line; the
+ # Host header still names the target (build_request_head).
+ target = f"http://{parsed.host_header()}{parsed.target}"
+ if proxy.basic_auth is not None:
+ headers = [*headers, ("Proxy-Authorization", proxy.basic_auth)]
+ head = build_request_head(
+ method=request.method,
+ target=target,
+ host=parsed.host,
+ port=parsed.port,
+ is_tls=parsed.is_tls,
+ headers=headers,
+ body_length=body_length,
+ user_agent=self._user_agent,
+ )
+ try:
+ conn.writer.write(head)
+ if body_length is not None and body:
+ conn.writer.write(body)
+ await asyncio.wait_for(conn.writer.drain(), timeout=write_timeout)
+ except asyncio.TimeoutError as exc:
+ raise WriteTimeout(f"write timed out: {exc}") from exc
+ except (BrokenPipeError, ConnectionResetError):
+ raise
+ except OSError as exc:
+ raise WriteError(f"write failed: {exc}") from exc
+
+ async def _read_head(
+ self, conn: _AsyncConnection, *, read_timeout: float
+ ) -> ResponseHeadParser:
+ parser = ResponseHeadParser()
+ while not parser.complete:
+ try:
+ data = await asyncio.wait_for(
+ conn.reader.read(_READ_CHUNK), timeout=read_timeout
+ )
+ except asyncio.TimeoutError as exc:
+ raise ReadTimeout("read timed out waiting for headers") from exc
+ except OSError as exc:
+ raise ReadError(f"read failed: {exc}") from exc
+ if not data:
+ raise ReadError("server closed connection before sending response")
+ parser.feed(data)
+ return parser
+
+ def _make_release(self, conn: _AsyncConnection, keep_alive: bool):
+ async def release(body_consumed: bool) -> None:
+ if body_consumed and keep_alive and not conn.closed:
+ await self._pool.checkin(conn)
+ else:
+ await self._pool.discard(conn)
+ return release
+
+
+class _AsyncStreamCM:
+ """Async context manager wrapper so callers can write:
+
+ async with transport.stream(req) as resp:
+ async for chunk in resp: ...
+ """
+
+ def __init__(self, transport: StdlibAsyncTransport, request: TransportRequest) -> None:
+ self._transport = transport
+ self._request = request
+ self._response: AsyncTransportResponse | None = None
+
+ def __await__(self):
+ return self._transport._do_stream(self._request).__await__()
+
+ async def __aenter__(self) -> AsyncTransportResponse:
+ self._response = await self._transport._do_stream(self._request)
+ return self._response
+
+ async def __aexit__(self, exc_type, exc, tb) -> None:
+ if self._response is not None:
+ await self._response.aclose()
diff --git a/dspy/_vendor/lm15/transports/_exceptions.py b/dspy/_vendor/lm15/transports/_exceptions.py
new file mode 100644
index 000000000..1dd13d750
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_exceptions.py
@@ -0,0 +1,40 @@
+"""
+Transport-level exceptions.
+
+These are distinct from lm15.errors (which are provider-level error taxonomy).
+Provider LMs wrap these lower-level errors into lm15.errors.TransportError.
+They are not provider HTTP/API errors.
+"""
+from __future__ import annotations
+
+
+class TransportError(Exception):
+ """Base transport error — network or protocol failure below the LM layer."""
+
+
+class ConnectError(TransportError):
+ """Failed to establish a TCP (or TLS) connection."""
+
+
+class ConnectTimeout(ConnectError):
+ """Connection establishment timed out."""
+
+
+class ReadError(TransportError):
+ """Failed to read from an open socket (EOF, reset, etc.)."""
+
+
+class ReadTimeout(ReadError):
+ """Reading from the socket timed out."""
+
+
+class WriteError(TransportError):
+ """Failed to write to an open socket."""
+
+
+class WriteTimeout(WriteError):
+ """Writing to the socket timed out."""
+
+
+class ProtocolError(TransportError):
+ """The server sent something that isn't valid HTTP/1.1."""
diff --git a/dspy/_vendor/lm15/transports/_http11.py b/dspy/_vendor/lm15/transports/_http11.py
new file mode 100644
index 000000000..43713b3f7
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_http11.py
@@ -0,0 +1,416 @@
+"""
+HTTP/1.1 codec — pure functions over bytes.
+
+Used by both the sync and async transports. All state is in small helper
+objects (ResponseHeadParser, ContentLengthDecoder, ChunkedDecoder, EOFDecoder);
+none of them do any I/O. The transport feeds them bytes and reads back
+decoded body chunks + a completion flag.
+
+This is deliberately minimal:
+ - HTTP/1.1 only (no HTTP/2, no HTTP/1.0 write side)
+ - No Content-Encoding handling (gzip/deflate/br/zstd) — LLM APIs don't
+ compress responses in practice, and we'd rather not pull in zlib paths
+ until we need them. Set Accept-Encoding: identity to be explicit.
+ - No trailers, no pipelining, no 100-continue.
+ - Chunk extensions (RFC 7230 §4.1.1) are parsed and discarded.
+"""
+from __future__ import annotations
+
+from typing import Iterator
+
+from ._exceptions import ProtocolError
+
+
+# ─── Request serialization ───────────────────────────────────────────
+
+
+_FORBIDDEN_BYTES = {ord("\r"), ord("\n"), 0}
+
+
+def _validate_field(kind: str, value: str) -> None:
+ """Reject header values / targets containing CR/LF/NUL (CRLF injection)."""
+ for ch in value.encode("iso-8859-1", errors="replace"):
+ if ch in _FORBIDDEN_BYTES:
+ raise ProtocolError(f"forbidden byte in HTTP {kind}: {value!r}")
+
+
+def build_request_head(
+ *,
+ method: str,
+ target: str,
+ host: str,
+ port: int,
+ is_tls: bool,
+ headers: list[tuple[str, str]],
+ body_length: int | None,
+ user_agent: str = "lm15/stdlib",
+) -> bytes:
+ """Serialize the request line + headers (NOT the body).
+
+ `body_length=None` means no body at all (e.g. GET). `body_length=0` means
+ the request has an empty body (POST with no payload). Any other value
+ becomes the Content-Length header.
+ """
+ _validate_field("method", method)
+ _validate_field("target", target)
+ _validate_field("host", host)
+ for k, v in headers:
+ _validate_field(f"header name ({k})", k)
+ _validate_field(f"header value ({k})", v)
+
+ lines = [f"{method} {target} HTTP/1.1"]
+
+ # Track which headers the caller provided so we don't duplicate them
+ lower_names = {k.lower() for k, _ in headers}
+
+ if "host" not in lower_names:
+ is_default = (is_tls and port == 443) or (not is_tls and port == 80)
+ host_hdr = _bracketed_if_v6(host) if is_default else f"{_bracketed_if_v6(host)}:{port}"
+ lines.append(f"Host: {host_hdr}")
+
+ if "user-agent" not in lower_names:
+ lines.append(f"User-Agent: {user_agent}")
+
+ if "accept" not in lower_names:
+ lines.append("Accept: */*")
+
+ # Be explicit about no compression — we don't implement Content-Encoding.
+ if "accept-encoding" not in lower_names:
+ lines.append("Accept-Encoding: identity")
+
+ if body_length is not None and "content-length" not in lower_names:
+ lines.append(f"Content-Length: {body_length}")
+
+ for k, v in headers:
+ lines.append(f"{k}: {v}")
+
+ lines.append("") # end of headers
+ lines.append("") # blank line terminator
+
+ return "\r\n".join(lines).encode("iso-8859-1")
+
+
+def _bracketed_if_v6(host: str) -> str:
+ return f"[{host}]" if ":" in host else host
+
+
+# ─── Response head parser ────────────────────────────────────────────
+
+
+class ResponseHeadParser:
+ """Incrementally parses status line + headers up to the blank line.
+
+ Feed bytes via `.feed(data)`. Once `.complete` is True the status,
+ reason, http_version, and headers are populated, and `.leftover` holds
+ any bytes that arrived past the \\r\\n\\r\\n terminator (start of body).
+ """
+
+ def __init__(self, max_head_bytes: int = 64 * 1024) -> None:
+ self._buf = bytearray()
+ self._max = max_head_bytes
+ self.complete = False
+ self.http_version: str = ""
+ self.status: int = 0
+ self.reason: str = ""
+ # Preserve order + duplicates
+ self.headers: list[tuple[str, str]] = []
+ self.leftover: bytes = b""
+
+ def feed(self, data: bytes) -> None:
+ if self.complete:
+ # Anything after completion belongs to the body; we shouldn't be called.
+ self.leftover += bytes(data)
+ return
+ self._buf.extend(data)
+ if len(self._buf) > self._max:
+ raise ProtocolError(
+ f"response head exceeded limit ({len(self._buf)} > {self._max} bytes)"
+ )
+ end = self._buf.find(b"\r\n\r\n")
+ if end == -1:
+ # Also accept bare \n\n (spec requires \r\n\r\n but be lenient)
+ return
+ head = bytes(self._buf[:end])
+ self.leftover = bytes(self._buf[end + 4:])
+ self._buf.clear()
+ self._parse_head(head)
+ self.complete = True
+
+ def _parse_head(self, head: bytes) -> None:
+ # Accept \r\n or \n line terminators inside head
+ lines = head.replace(b"\r\n", b"\n").split(b"\n")
+ if not lines:
+ raise ProtocolError("empty response head")
+ status_line = lines[0].decode("iso-8859-1")
+ parts = status_line.split(" ", 2)
+ if len(parts) < 2:
+ raise ProtocolError(f"malformed status line: {status_line!r}")
+ version = parts[0]
+ if not version.startswith("HTTP/"):
+ raise ProtocolError(f"malformed status line: {status_line!r}")
+ self.http_version = version
+ try:
+ self.status = int(parts[1])
+ except ValueError:
+ raise ProtocolError(f"malformed status code: {status_line!r}")
+ self.reason = parts[2] if len(parts) == 3 else ""
+
+ for line in lines[1:]:
+ if not line:
+ continue
+ s = line.decode("iso-8859-1")
+ if ":" not in s:
+ raise ProtocolError(f"malformed header line: {s!r}")
+ name, _, value = s.partition(":")
+ self.headers.append((name.strip(), value.strip()))
+
+ # ─── Convenience accessors ───
+
+ def header(self, name: str) -> str | None:
+ lname = name.lower()
+ for k, v in self.headers:
+ if k.lower() == lname:
+ return v
+ return None
+
+ def headers_all(self, name: str) -> list[str]:
+ lname = name.lower()
+ return [v for k, v in self.headers if k.lower() == lname]
+
+ # ─── Framing decision ───
+
+ def body_decoder(self, request_method: str) -> "_BodyDecoder":
+ """Pick the right decoder based on headers (RFC 7230 §3.3.3)."""
+ # No body on 1xx, 204, 304, or HEAD
+ if (
+ self.status // 100 == 1
+ or self.status in (204, 304)
+ or request_method.upper() == "HEAD"
+ ):
+ return NoBodyDecoder()
+
+ te = self.header("transfer-encoding")
+ if te:
+ # "chunked" may be the last (or only) coding
+ codings = [c.strip().lower() for c in te.split(",")]
+ if codings and codings[-1] == "chunked":
+ # We don't support inner codings (gzip,chunked etc.)
+ if len(codings) > 1:
+ raise ProtocolError(
+ f"unsupported Transfer-Encoding stacking: {te!r}"
+ )
+ return ChunkedDecoder()
+ # Non-chunked TE (deprecated) — treat as identity-to-EOF
+ return EOFDecoder()
+
+ cl = self.header("content-length")
+ if cl is not None:
+ try:
+ n = int(cl)
+ except ValueError:
+ raise ProtocolError(f"malformed Content-Length: {cl!r}")
+ if n < 0:
+ raise ProtocolError(f"negative Content-Length: {cl!r}")
+ return ContentLengthDecoder(n)
+
+ # No framing headers — HTTP/1.1 should have used Content-Length,
+ # but in practice responses without either exist; read until close.
+ return EOFDecoder()
+
+ def keep_alive(self) -> bool:
+ """Whether the connection may be reused after this response."""
+ conn = (self.header("connection") or "").lower()
+ # HTTP/1.1 default is keep-alive; HTTP/1.0 default is close.
+ if self.http_version == "HTTP/1.0":
+ return "keep-alive" in conn
+ return "close" not in conn
+
+
+# ─── Body decoders ───────────────────────────────────────────────────
+
+
+class _BodyDecoder:
+ """Interface: feed(data) -> iter of decoded chunks, eof() to signal close."""
+ complete: bool
+ leftover: bytes
+
+ def feed(self, data: bytes) -> Iterator[bytes]:
+ raise NotImplementedError
+
+ def eof(self) -> None:
+ raise NotImplementedError
+
+
+class NoBodyDecoder(_BodyDecoder):
+ def __init__(self) -> None:
+ self.complete = True
+ self.leftover = b""
+
+ def feed(self, data: bytes) -> Iterator[bytes]:
+ if data:
+ self.leftover += bytes(data)
+ return iter(())
+
+ def eof(self) -> None:
+ self.complete = True
+
+
+class ContentLengthDecoder(_BodyDecoder):
+ def __init__(self, length: int) -> None:
+ self._remaining = length
+ self.complete = length == 0
+ self.leftover = b""
+
+ def feed(self, data: bytes) -> Iterator[bytes]:
+ if self.complete:
+ if data:
+ raise ProtocolError("received data after Content-Length reached")
+ return
+ if not data:
+ return
+ take = min(len(data), self._remaining)
+ out = bytes(data[:take])
+ self._remaining -= take
+ if take < len(data):
+ self.leftover = bytes(data[take:])
+ if self._remaining == 0:
+ self.complete = True
+ yield out
+
+ def eof(self) -> None:
+ if not self.complete:
+ raise ProtocolError(
+ f"connection closed with {self._remaining} body bytes outstanding"
+ )
+
+
+class ChunkedDecoder(_BodyDecoder):
+ """Decodes Transfer-Encoding: chunked.
+
+ States:
+ SIZE — reading the chunk size line (hex + optional extensions)
+ DATA — reading chunk data
+ DATA_CRLF — reading the CRLF after chunk data
+ TRAILER — reading trailer headers + terminating blank line
+ """
+
+ SIZE = 0
+ DATA = 1
+ DATA_CRLF = 2
+ TRAILER = 3
+
+ def __init__(self, max_line_bytes: int = 16 * 1024) -> None:
+ self._buf = bytearray()
+ self._state = self.SIZE
+ self._remaining = 0
+ self._max_line = max_line_bytes
+ self.complete = False
+ self.leftover = b""
+
+ def feed(self, data: bytes) -> Iterator[bytes]:
+ if data:
+ self._buf.extend(data)
+ while True:
+ if self._state == self.SIZE:
+ line, rest = self._extract_line()
+ if line is None:
+ return
+ assert rest is not None
+ self._buf = rest
+ size = self._parse_chunk_size(line)
+ if size == 0:
+ self._state = self.TRAILER
+ continue
+ self._remaining = size
+ self._state = self.DATA
+ continue
+
+ if self._state == self.DATA:
+ if not self._buf:
+ return
+ take = min(len(self._buf), self._remaining)
+ out = bytes(self._buf[:take])
+ self._buf = self._buf[take:]
+ self._remaining -= take
+ if out:
+ yield out
+ if self._remaining == 0:
+ self._state = self.DATA_CRLF
+ continue
+ return
+
+ if self._state == self.DATA_CRLF:
+ if len(self._buf) < 2:
+ return
+ if bytes(self._buf[:2]) != b"\r\n":
+ # Be lenient: accept bare \n as terminator
+ if self._buf[:1] == b"\n":
+ self._buf = self._buf[1:]
+ else:
+ raise ProtocolError("missing CRLF after chunk data")
+ else:
+ self._buf = self._buf[2:]
+ self._state = self.SIZE
+ continue
+
+ if self._state == self.TRAILER:
+ # Lines until blank line
+ line, rest = self._extract_line()
+ if line is None:
+ return
+ assert rest is not None
+ self._buf = rest
+ if line == b"":
+ self.complete = True
+ self.leftover = bytes(self._buf)
+ self._buf.clear()
+ return
+ # Trailer header — ignored (we don't surface them)
+ continue
+ return # unreachable
+
+ def _extract_line(self) -> tuple[bytes, bytearray] | tuple[None, None]:
+ # Find \r\n or bare \n
+ idx = self._buf.find(b"\r\n")
+ if idx == -1:
+ bare = self._buf.find(b"\n")
+ if bare == -1:
+ if len(self._buf) > self._max_line:
+ raise ProtocolError("chunk line exceeds limit")
+ return None, None
+ line = bytes(self._buf[:bare])
+ return line, self._buf[bare + 1:]
+ line = bytes(self._buf[:idx])
+ if idx > self._max_line:
+ raise ProtocolError("chunk line exceeds limit")
+ return line, self._buf[idx + 2:]
+
+ @staticmethod
+ def _parse_chunk_size(line: bytes) -> int:
+ # Discard chunk extensions after ';'
+ size_part = line.split(b";", 1)[0].strip()
+ if not size_part:
+ raise ProtocolError(f"empty chunk size line: {line!r}")
+ try:
+ return int(size_part, 16)
+ except ValueError:
+ raise ProtocolError(f"malformed chunk size: {line!r}")
+
+ def eof(self) -> None:
+ if not self.complete:
+ raise ProtocolError("connection closed mid-chunk")
+
+
+class EOFDecoder(_BodyDecoder):
+ """Body ends when the connection closes (HTTP/1.0 style)."""
+
+ def __init__(self) -> None:
+ self.complete = False
+ self.leftover = b""
+
+ def feed(self, data: bytes) -> Iterator[bytes]:
+ if data:
+ yield bytes(data)
+
+ def eof(self) -> None:
+ self.complete = True
diff --git a/dspy/_vendor/lm15/transports/_proxy.py b/dspy/_vendor/lm15/transports/_proxy.py
new file mode 100644
index 000000000..fff82027b
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_proxy.py
@@ -0,0 +1,98 @@
+"""
+Proxy route resolution.
+
+An explicit ``proxy=`` on the transport always wins; otherwise, with
+``trust_env=True`` (the default), the standard environment variables
+(``HTTP_PROXY`` / ``HTTPS_PROXY`` / ``ALL_PROXY``, minus ``NO_PROXY``)
+are consulted per request — the platform contract every HTTP client
+honors, and the mechanism egress brokers and corporate proxies rely on.
+``trust_env=False`` makes the transport hermetic.
+
+Only plain-HTTP proxies are supported (``http://`` proxy URLs). Plain
+targets are forwarded with an absolute-URI request line; TLS targets are
+tunneled with CONNECT and the TLS handshake runs end-to-end to the
+origin — the proxy never sees inside the tunnel.
+"""
+from __future__ import annotations
+
+import base64
+from dataclasses import dataclass
+from urllib.parse import unquote
+from urllib.request import getproxies, proxy_bypass
+
+from ._url import ParsedURL, parse_url
+
+
+@dataclass(frozen=True, slots=True)
+class ProxyRoute:
+ """Where to connect, and what Proxy-Authorization to present (if any)."""
+
+ host: str
+ port: int
+ basic_auth: str | None = None # full header value, e.g. "Basic dXNlcjpwdw=="
+
+ def authority(self, parsed: ParsedURL) -> str:
+ """The target's host:port authority-form, as CONNECT wants it."""
+ host = f"[{parsed.host}]" if ":" in parsed.host else parsed.host
+ return f"{host}:{parsed.port}"
+
+
+def parse_proxy_url(url: str) -> ProxyRoute:
+ """Parse a proxy URL into a ProxyRoute. Raises ValueError on anything unsupported."""
+ if "://" not in url:
+ url = "http://" + url
+ scheme, _, rest = url.partition("://")
+ if scheme.lower() != "http":
+ raise ValueError(
+ f"unsupported proxy scheme {scheme!r} in {url!r}: lm15 speaks to plain-HTTP proxies only"
+ )
+ auth: str | None = None
+ authority = rest.split("/", 1)[0]
+ if "@" in authority:
+ userinfo, _, hostpart = authority.rpartition("@")
+ rest = hostpart + rest[len(authority):]
+ auth = "Basic " + base64.b64encode(unquote(userinfo).encode("utf-8")).decode("ascii")
+ parsed = parse_url("http://" + rest)
+ return ProxyRoute(host=parsed.host, port=parsed.port, basic_auth=auth)
+
+
+def proxy_route_for(parsed: ParsedURL, *, proxy: str | None, trust_env: bool) -> ProxyRoute | None:
+ """Resolve the proxy for one target URL, or None for a direct connection."""
+ if proxy is not None:
+ return parse_proxy_url(proxy)
+ if not trust_env:
+ return None
+ proxies = getproxies()
+ url = proxies.get(parsed.scheme) or proxies.get("all")
+ if not url:
+ return None
+ try:
+ if proxy_bypass(parsed.host): # honors NO_PROXY, including "*"
+ return None
+ except Exception: # pragma: no cover — platform lookup quirks bypass nothing
+ pass
+ return parse_proxy_url(url)
+
+
+def route_origin(parsed: ParsedURL, proxy: ProxyRoute | None) -> tuple[str, str, int]:
+ """The connection-pool key for this (target, proxy) pair.
+
+ Direct: the target origin, as before. Plain HTTP via proxy: one pool
+ per proxy — the proxy multiplexes targets on a single connection.
+ TLS via proxy: one pool per (proxy, target) — a CONNECT tunnel is
+ welded to its target and cannot be reused for another host.
+ """
+ if proxy is None:
+ return parsed.origin()
+ if parsed.is_tls:
+ return (f"https@{proxy.host}:{proxy.port}", parsed.host, parsed.port)
+ return ("http-proxy", proxy.host, proxy.port)
+
+
+def connect_payload(parsed: ParsedURL, proxy: ProxyRoute) -> bytes:
+ """Serialize the CONNECT request that opens a tunnel to the target."""
+ authority = proxy.authority(parsed)
+ lines = [f"CONNECT {authority} HTTP/1.1", f"Host: {authority}"]
+ if proxy.basic_auth is not None:
+ lines.append(f"Proxy-Authorization: {proxy.basic_auth}")
+ return ("\r\n".join(lines) + "\r\n\r\n").encode("ascii")
diff --git a/dspy/_vendor/lm15/transports/_ssl.py b/dspy/_vendor/lm15/transports/_ssl.py
new file mode 100644
index 000000000..4b213015b
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_ssl.py
@@ -0,0 +1,22 @@
+"""SSL context factory.
+
+We rely on the stdlib `ssl` module's `create_default_context`, which on
+Python 3.10+ loads the system trust store correctly on Linux/macOS/Windows.
+No certifi bundle is shipped — set SSL_CERT_FILE if your system store is
+broken, or pass an explicit ca_bundle= to the transport.
+"""
+from __future__ import annotations
+
+import ssl
+
+
+def make_ssl_context(
+ *, verify: bool = True, ca_bundle: str | None = None
+) -> ssl.SSLContext:
+ if not verify:
+ ctx = ssl._create_unverified_context()
+ return ctx
+ ctx = ssl.create_default_context()
+ if ca_bundle:
+ ctx.load_verify_locations(cafile=ca_bundle)
+ return ctx
diff --git a/dspy/_vendor/lm15/transports/_sync.py b/dspy/_vendor/lm15/transports/_sync.py
new file mode 100644
index 000000000..d943453f3
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_sync.py
@@ -0,0 +1,534 @@
+"""
+Sync transport built on the stdlib `socket` + `ssl` modules.
+
+Design:
+
+- A single transport owns a connection pool keyed by origin (scheme, host,
+ port). Up to `max_connections` concurrent connections per pool total (not
+ per origin — keeping it simple for lm15's workload).
+- `stream(request)` takes a connection (new or reused), writes the request,
+ reads the response head, and returns a `TransportResponse` whose iteration yields
+ body bytes. The response's `__exit__`/generator teardown releases the
+ connection (to the pool if reusable, otherwise closed).
+- Staleness detection: before reusing an idle connection, we peek with
+ `select` to see if the socket has readable bytes. For an idle HTTP keepalive
+ socket, readable means the server sent EOF — so we drop it and open fresh.
+- If the server sent `Connection: close`, or the body is still outstanding
+ when the response closes, the connection is closed rather than reused.
+- Proxies: `proxy=` pins one explicitly; otherwise `trust_env=True` (default)
+ honors HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY. Plain-HTTP targets
+ are forwarded absolute-URI; TLS targets are tunneled with CONNECT and the
+ handshake runs end-to-end to the origin (see `_proxy.py`).
+"""
+from __future__ import annotations
+
+import select
+import socket
+import ssl
+import threading
+from typing import Iterator
+
+from ._exceptions import (
+ ConnectError,
+ ConnectTimeout,
+ ProtocolError,
+ ReadError,
+ ReadTimeout,
+ TransportError,
+ WriteError,
+ WriteTimeout,
+)
+from ._http11 import (
+ ChunkedDecoder,
+ ContentLengthDecoder,
+ EOFDecoder,
+ ResponseHeadParser,
+ build_request_head,
+)
+from ._proxy import ProxyRoute, connect_payload, proxy_route_for, route_origin
+from ._ssl import make_ssl_context
+from ._types import TransportRequest, TransportResponse
+from ._url import ParsedURL, parse_url
+
+
+_DEFAULT_CONNECT_TIMEOUT = 10.0
+_DEFAULT_READ_TIMEOUT = 60.0
+_DEFAULT_WRITE_TIMEOUT = 60.0
+_READ_CHUNK = 64 * 1024
+
+
+# ─── Connection wrapper ──────────────────────────────────────────────
+
+
+class _SyncConnection:
+ """Owns a single TCP/TLS socket keyed by an origin."""
+
+ __slots__ = ("origin", "sock", "in_use", "closed")
+
+ def __init__(self, origin: tuple[str, str, int], sock: socket.socket) -> None:
+ self.origin = origin
+ self.sock = sock
+ self.in_use = False
+ self.closed = False
+
+ def is_stale(self) -> bool:
+ """Return True if the peer has closed the connection while it was idle."""
+ if self.closed:
+ return True
+ try:
+ r, _, _ = select.select([self.sock], [], [], 0)
+ if not r:
+ return False
+ # Readable on an idle socket means the peer sent EOF/close_notify,
+ # or that unexpected bytes were left unread. Either way this
+ # connection is not safe to reuse. Do not probe with MSG_PEEK here:
+ # ssl.SSLSocket.recv(..., flags) raises ValueError for non-zero
+ # flags, and peeking is unnecessary once select() says an idle
+ # socket is readable.
+ return True
+ except (OSError, ValueError):
+ return True
+
+ def close(self) -> None:
+ if self.closed:
+ return
+ self.closed = True
+ try:
+ self.sock.close()
+ except Exception:
+ pass
+
+
+# ─── Connection pool ─────────────────────────────────────────────────
+
+
+class _ConnectionPool:
+ """Small LIFO pool. LIFO (not FIFO) minimizes chance of reusing stale
+ keepalive connections, since the most recently used is the most likely
+ to still be alive."""
+
+ def __init__(self, max_connections: int) -> None:
+ self._max = max_connections
+ self._idle: dict[tuple[str, str, int], list[_SyncConnection]] = {}
+ self._in_use: set[_SyncConnection] = set()
+ self._lock = threading.Lock()
+ self._slot = threading.Semaphore(max_connections)
+ self._total_opened = 0
+ self._closed = False
+
+ def acquire_slot(self, timeout: float | None = None) -> None:
+ if self._closed:
+ raise TransportError("transport is closed")
+ ok = self._slot.acquire(timeout=timeout)
+ if not ok:
+ raise TransportError("timed out waiting for connection pool slot")
+
+ def release_slot(self) -> None:
+ self._slot.release()
+
+ def checkout(self, origin: tuple[str, str, int]) -> _SyncConnection | None:
+ """Return an idle connection for this origin, or None if none usable."""
+ with self._lock:
+ q = self._idle.get(origin)
+ while q:
+ conn = q.pop()
+ if conn.is_stale():
+ conn.close()
+ continue
+ conn.in_use = True
+ self._in_use.add(conn)
+ return conn
+ return None
+
+ def checkin(self, conn: _SyncConnection) -> None:
+ """Return a connection to the idle pool."""
+ with self._lock:
+ self._in_use.discard(conn)
+ if self._closed or conn.closed:
+ conn.close()
+ return
+ conn.in_use = False
+ self._idle.setdefault(conn.origin, []).append(conn)
+
+ def discard(self, conn: _SyncConnection) -> None:
+ """Close a connection and remove it from all tracking."""
+ with self._lock:
+ self._in_use.discard(conn)
+ conn.close()
+
+ def register_new(self, conn: _SyncConnection) -> None:
+ with self._lock:
+ self._in_use.add(conn)
+ self._total_opened += 1
+
+ def stats(self) -> dict:
+ with self._lock:
+ return {
+ "idle": sum(len(q) for q in self._idle.values()),
+ "in_use": len(self._in_use),
+ "total_opened": self._total_opened,
+ }
+
+ def close_all(self) -> None:
+ with self._lock:
+ self._closed = True
+ for q in self._idle.values():
+ for conn in q:
+ conn.close()
+ self._idle.clear()
+ for conn in list(self._in_use):
+ conn.close()
+ self._in_use.clear()
+
+
+# ─── Transport ───────────────────────────────────────────────────────
+
+
+class StdlibTransport:
+ """Sync HTTP/1.1 transport using only the Python standard library."""
+
+ def __init__(
+ self,
+ *,
+ connect_timeout: float = _DEFAULT_CONNECT_TIMEOUT,
+ read_timeout: float = _DEFAULT_READ_TIMEOUT,
+ write_timeout: float = _DEFAULT_WRITE_TIMEOUT,
+ max_connections: int = 10,
+ verify: bool = True,
+ ca_bundle: str | None = None,
+ user_agent: str = "lm15/stdlib",
+ proxy: str | None = None,
+ trust_env: bool = True,
+ ) -> None:
+ self._connect_timeout = connect_timeout
+ self._read_timeout = read_timeout
+ self._write_timeout = write_timeout
+ self._user_agent = user_agent
+ self._verify = verify
+ self._ca_bundle = ca_bundle
+ self._proxy = proxy
+ self._trust_env = trust_env
+ self._ssl_ctx: ssl.SSLContext | None = None
+ self._ssl_lock = threading.Lock()
+ self._pool = _ConnectionPool(max_connections)
+ self._closed = False
+
+ def _get_ssl_ctx(self) -> ssl.SSLContext:
+ with self._ssl_lock:
+ if self._ssl_ctx is None:
+ self._ssl_ctx = make_ssl_context(
+ verify=self._verify, ca_bundle=self._ca_bundle
+ )
+ return self._ssl_ctx
+
+ def pool_stats(self) -> dict:
+ return self._pool.stats()
+
+ def close(self) -> None:
+ if self._closed:
+ return
+ self._closed = True
+ self._pool.close_all()
+
+ def __enter__(self) -> "StdlibTransport":
+ return self
+
+ def __exit__(self, exc_type, exc, tb) -> None:
+ self.close()
+
+ # ─── Main entry point ───
+
+ def stream(self, request: TransportRequest) -> TransportResponse:
+ """Open a stream to the URL, returning a TransportResponse whose iteration
+ yields body bytes.
+
+ The response MUST be used as a context manager (or have `.close()`
+ called) — otherwise the underlying connection leaks.
+ """
+ if self._closed:
+ raise TransportError("transport is closed")
+
+ parsed = parse_url(request.url)
+ proxy = proxy_route_for(parsed, proxy=self._proxy, trust_env=self._trust_env)
+ origin = route_origin(parsed, proxy)
+ connect_timeout = request.connect_timeout or self._connect_timeout
+ read_timeout = request.read_timeout or self._read_timeout
+ write_timeout = request.write_timeout or self._write_timeout
+
+ # Acquire a pool slot FIRST (may block if we're at max_connections)
+ self._pool.acquire_slot(timeout=connect_timeout * 5)
+ slot_released = False
+
+ def release_slot_once() -> None:
+ nonlocal slot_released
+ if not slot_released:
+ slot_released = True
+ self._pool.release_slot()
+
+ conn: _SyncConnection | None = None
+ try:
+ # Try to reuse an idle connection. If the write fails because the
+ # connection went stale between stale-check and write, open fresh
+ # and retry once.
+ attempt = 0
+ while True:
+ conn = self._pool.checkout(origin) if attempt == 0 else None
+ reused = conn is not None
+ if conn is None:
+ conn = self._open(
+ parsed, proxy=proxy, origin=origin, connect_timeout=connect_timeout
+ )
+ self._pool.register_new(conn)
+
+ try:
+ self._send_request(
+ conn, request, parsed, proxy=proxy, write_timeout=write_timeout
+ )
+ break
+ except (WriteError, ConnectionResetError, BrokenPipeError, OSError) as exc:
+ if not reused or attempt > 0:
+ self._pool.discard(conn)
+ if isinstance(exc, WriteError):
+ raise
+ raise WriteError(str(exc)) from exc
+ # Reused connection was stale — close it and retry fresh
+ self._pool.discard(conn)
+ conn = None
+ attempt += 1
+ continue
+
+ # Receive response head
+ head = self._read_head(conn, read_timeout=read_timeout)
+ decoder = head.body_decoder(request.method)
+ keep_alive = head.keep_alive()
+
+ release_conn = self._make_release(conn, keep_alive)
+ # Transfer ownership of the pool slot to the TransportResponse
+ # (TransportResponse.close will trigger release_slot via _release)
+ chunks = self._iter_body(
+ conn, decoder, initial=head.leftover,
+ read_timeout=read_timeout, on_finish=release_slot_once,
+ on_abort=release_slot_once,
+ )
+ return TransportResponse(
+ status=head.status,
+ reason=head.reason,
+ headers=head.headers,
+ http_version=head.http_version,
+ chunks=chunks,
+ release=release_conn,
+ )
+ except BaseException:
+ release_slot_once()
+ if conn is not None and conn not in self._pool._in_use:
+ # never happens — register_new or checkout put it in_use
+ pass
+ if conn is not None:
+ self._pool.discard(conn)
+ raise
+
+ # ─── Connection I/O ───
+
+ def _open(
+ self,
+ parsed: ParsedURL,
+ *,
+ proxy: ProxyRoute | None,
+ origin: tuple[str, str, int],
+ connect_timeout: float,
+ ) -> _SyncConnection:
+ connect_host = proxy.host if proxy is not None else parsed.host
+ connect_port = proxy.port if proxy is not None else parsed.port
+ try:
+ sock = socket.create_connection(
+ (connect_host, connect_port), timeout=connect_timeout,
+ )
+ except socket.timeout as exc:
+ raise ConnectTimeout(
+ f"timed out connecting to {connect_host}:{connect_port}"
+ ) from exc
+ except OSError as exc:
+ raise ConnectError(
+ f"failed to connect to {connect_host}:{connect_port}: {exc}"
+ ) from exc
+
+ try:
+ sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+ except OSError:
+ pass
+
+ if proxy is not None and parsed.is_tls:
+ try:
+ self._connect_tunnel(sock, parsed, proxy, timeout=connect_timeout)
+ except BaseException:
+ try:
+ sock.close()
+ except Exception:
+ pass
+ raise
+
+ if parsed.is_tls:
+ try:
+ ctx = self._get_ssl_ctx()
+ sock.settimeout(connect_timeout)
+ sock = ctx.wrap_socket(sock, server_hostname=parsed.host)
+ except (ssl.SSLError, OSError) as exc:
+ try:
+ sock.close()
+ except Exception:
+ pass
+ raise ConnectError(f"TLS handshake failed: {exc}") from exc
+
+ return _SyncConnection(origin, sock)
+
+ def _connect_tunnel(
+ self, sock: socket.socket, parsed: ParsedURL, proxy: ProxyRoute, *, timeout: float
+ ) -> None:
+ """Ask the proxy to open a CONNECT tunnel to the TLS target."""
+ sock.settimeout(timeout)
+ try:
+ sock.sendall(connect_payload(parsed, proxy))
+ except socket.timeout as exc:
+ raise ConnectTimeout(f"CONNECT to proxy timed out: {exc}") from exc
+ except OSError as exc:
+ raise ConnectError(f"CONNECT write to proxy failed: {exc}") from exc
+
+ parser = ResponseHeadParser()
+ while not parser.complete:
+ try:
+ data = sock.recv(_READ_CHUNK)
+ except socket.timeout as exc:
+ raise ConnectTimeout(f"timed out waiting for CONNECT response: {exc}") from exc
+ except OSError as exc:
+ raise ConnectError(f"read of CONNECT response failed: {exc}") from exc
+ if not data:
+ raise ConnectError("proxy closed connection during CONNECT")
+ parser.feed(data)
+ if not (200 <= parser.status < 300):
+ raise ConnectError(
+ f"proxy refused CONNECT to {proxy.authority(parsed)}: "
+ f"{parser.status} {parser.reason}"
+ )
+ if parser.leftover:
+ raise ProtocolError("proxy sent unexpected bytes after the CONNECT response")
+
+ def _send_request(
+ self,
+ conn: _SyncConnection,
+ request: TransportRequest,
+ parsed: ParsedURL,
+ *,
+ proxy: ProxyRoute | None,
+ write_timeout: float,
+ ) -> None:
+ body = request.body or b""
+ has_body = request.method.upper() not in ("GET", "HEAD", "DELETE") or bool(body)
+ body_length = len(body) if has_body else None
+ target = parsed.target
+ headers = request.headers
+ if proxy is not None and not parsed.is_tls:
+ # Forward-proxy plain HTTP: absolute-URI request line; the
+ # Host header still names the target (build_request_head).
+ target = f"http://{parsed.host_header()}{parsed.target}"
+ if proxy.basic_auth is not None:
+ headers = [*headers, ("Proxy-Authorization", proxy.basic_auth)]
+ head = build_request_head(
+ method=request.method,
+ target=target,
+ host=parsed.host,
+ port=parsed.port,
+ is_tls=parsed.is_tls,
+ headers=headers,
+ body_length=body_length,
+ user_agent=self._user_agent,
+ )
+ conn.sock.settimeout(write_timeout)
+ try:
+ conn.sock.sendall(head)
+ if body_length is not None and body:
+ conn.sock.sendall(body)
+ except socket.timeout as exc:
+ raise WriteTimeout(f"write timed out: {exc}") from exc
+ except (BrokenPipeError, ConnectionResetError):
+ raise # caller retries reused-but-stale connections
+ except OSError as exc:
+ raise WriteError(f"write failed: {exc}") from exc
+
+ def _read_head(
+ self, conn: _SyncConnection, *, read_timeout: float
+ ) -> ResponseHeadParser:
+ parser = ResponseHeadParser()
+ conn.sock.settimeout(read_timeout)
+ while not parser.complete:
+ try:
+ data = conn.sock.recv(_READ_CHUNK)
+ except socket.timeout as exc:
+ raise ReadTimeout(f"read timed out waiting for headers: {exc}") from exc
+ except OSError as exc:
+ raise ReadError(f"read failed: {exc}") from exc
+ if not data:
+ raise ReadError("server closed connection before sending response")
+ parser.feed(data)
+ return parser
+
+ def _iter_body(
+ self,
+ conn: _SyncConnection,
+ decoder,
+ *,
+ initial: bytes,
+ read_timeout: float,
+ on_finish,
+ on_abort,
+ ) -> Iterator[bytes]:
+ """Generator that yields decoded body chunks.
+
+ Calls on_finish() on clean completion, on_abort() on exception.
+ """
+ aborted = False
+ try:
+ if initial:
+ for out in decoder.feed(initial):
+ if out:
+ yield out
+ if decoder.complete:
+ return
+ conn.sock.settimeout(read_timeout)
+ while not decoder.complete:
+ try:
+ data = conn.sock.recv(_READ_CHUNK)
+ except socket.timeout as exc:
+ aborted = True
+ raise ReadTimeout(f"read timed out mid-body: {exc}") from exc
+ except OSError as exc:
+ aborted = True
+ raise ReadError(f"read failed: {exc}") from exc
+ if not data:
+ # EOF
+ try:
+ decoder.eof()
+ except ProtocolError:
+ aborted = True
+ raise
+ break
+ try:
+ for out in decoder.feed(data):
+ if out:
+ yield out
+ except ProtocolError:
+ aborted = True
+ raise
+ finally:
+ if aborted:
+ on_abort()
+ else:
+ on_finish()
+
+ def _make_release(self, conn: _SyncConnection, keep_alive: bool):
+ """Create the release callback the TransportResponse invokes on close."""
+ def release(body_consumed: bool) -> None:
+ if body_consumed and keep_alive and not conn.closed:
+ self._pool.checkin(conn)
+ else:
+ self._pool.discard(conn)
+ return release
diff --git a/dspy/_vendor/lm15/transports/_types.py b/dspy/_vendor/lm15/transports/_types.py
new file mode 100644
index 000000000..c5ee42428
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_types.py
@@ -0,0 +1,206 @@
+"""
+Transport-level request/response models.
+
+These are intentionally minimal — they're the bytes-in/bytes-out interface
+between the LM layer (which speaks the lm15 type system) and the
+HTTP transport.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import AsyncIterator, Iterator
+
+
+@dataclass(slots=True)
+class TransportRequest:
+ method: str
+ url: str = field(repr=False)
+ headers: list[tuple[str, str]] = field(default_factory=list, repr=False)
+ body: bytes = field(default=b"", repr=False)
+ # Per-request timeout overrides (None = use transport default)
+ connect_timeout: float | None = None
+ read_timeout: float | None = None
+ write_timeout: float | None = None
+
+
+class TransportResponse:
+ """Sync streaming response.
+
+ Iterating yields body chunks as bytes. Must be used as a context manager
+ so the connection is properly returned to the pool (or closed) even on
+ early exit.
+ """
+
+ status: int
+ reason: str
+ headers: list[tuple[str, str]]
+ http_version: str
+
+ def __init__(
+ self,
+ *,
+ status: int,
+ reason: str,
+ headers: list[tuple[str, str]],
+ http_version: str,
+ chunks: Iterator[bytes],
+ release: "callable",
+ ) -> None:
+ self.status = status
+ self.reason = reason
+ self.headers = headers
+ self.http_version = http_version
+ self._chunks = chunks
+ self._release = release
+ self._released = False
+ self._complete = False
+
+ def header(self, name: str) -> str | None:
+ lname = name.lower()
+ for k, v in self.headers:
+ if k.lower() == lname:
+ return v
+ return None
+
+ def headers_all(self, name: str) -> list[str]:
+ lname = name.lower()
+ return [v for k, v in self.headers if k.lower() == lname]
+
+ def __iter__(self) -> Iterator[bytes]:
+ try:
+ for chunk in self._chunks:
+ if chunk:
+ yield chunk
+ self._complete = True
+ finally:
+ self._release_once(body_consumed=self._complete)
+
+ def read(self) -> bytes:
+ return b"".join(self)
+
+ def iter_lines(self) -> Iterator[bytes]:
+ """Yield newline-terminated byte lines from arbitrary body chunks."""
+ buf = bytearray()
+ for chunk in self:
+ if not chunk:
+ continue
+ buf.extend(chunk)
+ while True:
+ idx = buf.find(b"\n")
+ if idx < 0:
+ break
+ line = bytes(buf[: idx + 1])
+ del buf[: idx + 1]
+ yield line
+ if buf:
+ yield bytes(buf)
+
+ def close(self) -> None:
+ self._release_once(body_consumed=self._complete)
+
+ def _release_once(self, *, body_consumed: bool) -> None:
+ if self._released:
+ return
+ self._released = True
+ try:
+ self._release(body_consumed)
+ except Exception:
+ pass
+
+ def __enter__(self) -> "TransportResponse":
+ return self
+
+ def __exit__(self, exc_type, exc, tb) -> None:
+ self.close()
+
+
+class AsyncTransportResponse:
+ """Async streaming response. Async-iterate to get body chunks."""
+
+ status: int
+ reason: str
+ headers: list[tuple[str, str]]
+ http_version: str
+
+ def __init__(
+ self,
+ *,
+ status: int,
+ reason: str,
+ headers: list[tuple[str, str]],
+ http_version: str,
+ chunks: AsyncIterator[bytes],
+ release: "callable",
+ ) -> None:
+ self.status = status
+ self.reason = reason
+ self.headers = headers
+ self.http_version = http_version
+ self._chunks = chunks
+ self._release = release # async callable(body_consumed: bool)
+ self._released = False
+ self._complete = False
+
+ def header(self, name: str) -> str | None:
+ lname = name.lower()
+ for k, v in self.headers:
+ if k.lower() == lname:
+ return v
+ return None
+
+ def headers_all(self, name: str) -> list[str]:
+ lname = name.lower()
+ return [v for k, v in self.headers if k.lower() == lname]
+
+ def __aiter__(self) -> AsyncIterator[bytes]:
+ return self._iter()
+
+ async def _iter(self) -> AsyncIterator[bytes]:
+ try:
+ async for chunk in self._chunks:
+ if chunk:
+ yield chunk
+ self._complete = True
+ finally:
+ await self._release_once(body_consumed=self._complete)
+
+ async def read(self) -> bytes:
+ buf = bytearray()
+ async for c in self:
+ buf.extend(c)
+ return bytes(buf)
+
+ async def aiter_lines(self) -> AsyncIterator[bytes]:
+ """Yield newline-terminated byte lines from arbitrary body chunks."""
+ buf = bytearray()
+ async for chunk in self:
+ if not chunk:
+ continue
+ buf.extend(chunk)
+ while True:
+ idx = buf.find(b"\n")
+ if idx < 0:
+ break
+ line = bytes(buf[: idx + 1])
+ del buf[: idx + 1]
+ yield line
+ if buf:
+ yield bytes(buf)
+
+ async def aclose(self) -> None:
+ await self._release_once(body_consumed=self._complete)
+
+ async def _release_once(self, *, body_consumed: bool) -> None:
+ if self._released:
+ return
+ self._released = True
+ try:
+ await self._release(body_consumed)
+ except Exception:
+ pass
+
+ async def __aenter__(self) -> "AsyncTransportResponse":
+ return self
+
+ async def __aexit__(self, exc_type, exc, tb) -> None:
+ await self.aclose()
diff --git a/dspy/_vendor/lm15/transports/_url.py b/dspy/_vendor/lm15/transports/_url.py
new file mode 100644
index 000000000..b5b28ed5b
--- /dev/null
+++ b/dspy/_vendor/lm15/transports/_url.py
@@ -0,0 +1,103 @@
+"""
+Minimal URL parser.
+
+We only need to parse `http://` and `https://` URLs into the four bits a
+transport actually uses: scheme, host, port, and request-target. Full RFC 3986
+parsing is unnecessary — provider URLs are well-formed.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedURL:
+ scheme: str # "http" or "https"
+ host: str # hostname or IP literal (no brackets for IPv6)
+ port: int # always set (default 80 or 443)
+ target: str # request-target: "/path?query"
+ is_tls: bool
+
+ def origin(self) -> tuple[str, str, int]:
+ """Pool key — two URLs with the same origin share connections."""
+ return (self.scheme, self.host, self.port)
+
+ def host_header(self) -> str:
+ """The value to put in the Host: header."""
+ is_default = (self.is_tls and self.port == 443) or (not self.is_tls and self.port == 80)
+ if is_default:
+ return _bracketed_if_v6(self.host)
+ return f"{_bracketed_if_v6(self.host)}:{self.port}"
+
+
+def _bracketed_if_v6(host: str) -> str:
+ return f"[{host}]" if ":" in host else host
+
+
+def parse_url(url: str) -> ParsedURL:
+ """Parse an http(s) URL. Raises ValueError on anything unsupported."""
+ # Scheme
+ if "://" not in url:
+ raise ValueError(f"URL missing scheme: {url!r}")
+ scheme, _, rest = url.partition("://")
+ scheme = scheme.lower()
+ if scheme not in ("http", "https"):
+ raise ValueError(f"unsupported scheme {scheme!r} in {url!r}")
+ is_tls = scheme == "https"
+
+ # Strip fragment (never sent to server)
+ rest, _, _fragment = rest.partition("#")
+
+ # Split authority from path
+ slash = rest.find("/")
+ qmark = rest.find("?")
+ # First separator, if any
+ cut = min((i for i in (slash, qmark) if i != -1), default=-1)
+ if cut == -1:
+ authority = rest
+ target = "/"
+ else:
+ authority = rest[:cut]
+ target = rest[cut:]
+ # If the first char of target is '?', prepend '/'
+ if target.startswith("?"):
+ target = "/" + target
+
+ if not authority:
+ raise ValueError(f"URL missing host: {url!r}")
+
+ host, port = _split_authority(authority, is_tls)
+
+ return ParsedURL(
+ scheme=scheme,
+ host=host,
+ port=port,
+ target=target,
+ is_tls=is_tls,
+ )
+
+
+def _split_authority(authority: str, is_tls: bool) -> tuple[str, int]:
+ # Handle IPv6 literal: [::1]:8080 or [::1]
+ if authority.startswith("["):
+ end = authority.find("]")
+ if end == -1:
+ raise ValueError(f"malformed IPv6 literal in authority: {authority!r}")
+ host = authority[1:end]
+ rest = authority[end + 1:]
+ if rest.startswith(":"):
+ port_s = rest[1:]
+ if not port_s.isdigit():
+ raise ValueError(f"bad port in authority: {authority!r}")
+ return host, int(port_s)
+ if rest == "":
+ return host, 443 if is_tls else 80
+ raise ValueError(f"unexpected trailing chars in authority: {authority!r}")
+
+ # Hostname or IPv4
+ if ":" in authority:
+ host, _, port_s = authority.rpartition(":")
+ if not port_s.isdigit():
+ raise ValueError(f"bad port in authority: {authority!r}")
+ return host, int(port_s)
+ return authority, 443 if is_tls else 80
diff --git a/dspy/_vendor/lm15/types.py b/dspy/_vendor/lm15/types.py
new file mode 100644
index 000000000..42da49327
--- /dev/null
+++ b/dspy/_vendor/lm15/types.py
@@ -0,0 +1,3056 @@
+"""
+lm15.types — Core vocabulary for foundation model interaction.
+
+The fundamental unit is the Part: an atomic, typed block of content.
+Parts compose into Messages (attributed to a speaker).
+Messages compose into Requests (sent to a model).
+Models produce Responses (containing a Message).
+
+Streams reveal Responses incrementally through Deltas — typed fragments
+of streamable response parts. Not every Part is streamable; use
+StreamablePart / NonStreamablePart to make that boundary explicit.
+
+Design principles:
+
+1. Parts, Deltas, and Events are proper discriminated unions. Each
+ variant is an independent frozen dataclass. Fields that don't belong
+ to a variant don't exist on it — accessing them raises AttributeError.
+ Check .type or use isinstance() before accessing variant-specific fields.
+
+2. One representation per concept. A Delta is always a typed Delta
+ object, never a dict. Tool call arguments are called "input"
+ everywhere — in memory, in deltas, in serialization.
+
+3. Frozen + slotted dataclasses throughout. Dataclass attributes are
+ shallowly immutable after construction: fields cannot be rebound, while
+ caller-provided JSON containers remain ordinary mutable Python containers.
+
+4. Universal structure, provider-specific values. The shape of a
+ Request is universal. Provider-specific configuration flows
+ through Config.extensions — clearly separated from universal knobs.
+ Provider-specific response metadata lives in Response.provider_data.
+
+5. Runtime validation is deliberately narrow. Constructors enforce the
+ invariants that make objects meaningful (required identities, one media
+ source, non-negative token counts, JSON-serializable extension fields)
+ while LMs remain responsible for normalizing provider quirks before
+ constructing these types.
+"""
+
+from __future__ import annotations
+
+import base64 as _base64
+import binascii as _binascii
+import json as _json
+import math as _math
+import mimetypes as _mimetypes
+import re as _re
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from os import PathLike
+from pathlib import Path
+from typing import Any, Literal, TypeAlias, TypeVar, get_args
+
+
+# ─── Literal vocabularies ────────────────────────────────────────────
+
+Role = Literal["user", "assistant", "tool", "developer"]
+
+PartType = Literal[
+ "text",
+ "image",
+ "audio",
+ "video",
+ "document",
+ "binary",
+ "tool_call",
+ "tool_result",
+ "thinking",
+ "refusal",
+ "citation",
+]
+
+ContinuationKind: TypeAlias = str
+
+# FinishReason values are a separate namespace from PartType values even when
+# a token such as "tool_call" appears in both.
+FinishReason = Literal["stop", "length", "tool_call", "content_filter", "error"]
+
+ReasoningEffort = Literal[
+ "off", "minimal", "low", "medium", "high", "xhigh", "max"
+]
+ReasoningSummary = Literal["auto", "concise", "detailed"]
+
+ErrorCode = Literal[
+ "auth",
+ "billing",
+ "rate_limit",
+ "invalid_request",
+ "context_length",
+ "timeout",
+ "server",
+ "unsupported_model",
+ "unsupported_feature",
+ "not_configured",
+ "unknown_model",
+ "ambiguous_model",
+ "transport",
+ "lock_timeout",
+ "stream_assembly",
+ "provider",
+]
+ERROR_CODES = frozenset(get_args(ErrorCode))
+
+StreamEventType = Literal["start", "delta", "end", "error"]
+BatchStatus = Literal["queued", "running", "cancelling", "completed", "failed", "cancelled", "expired"]
+VideoStatus = Literal["queued", "running", "completed", "failed", "cancelled"]
+BatchOutcome = Literal["succeeded", "errored", "cancelled", "expired"]
+FileReadiness = Literal["pending", "ready", "failed"]
+AudioEncoding = Literal["pcm16", "opus", "mp3", "aac"]
+ToolChoiceMode = Literal["auto", "required", "none"]
+LiveClientEventType = Literal["turn", "audio", "image", "text", "tool_result", "interrupt", "end_audio"]
+LiveServerEventType = Literal["audio", "text", "tool_call", "tool_call_delta", "interrupted", "turn_end", "usage", "error"]
+
+ROLE_VALUES = frozenset(get_args(Role))
+FINISH_REASONS = frozenset(get_args(FinishReason))
+REASONING_EFFORTS = frozenset(get_args(ReasoningEffort))
+REASONING_SUMMARIES = frozenset(get_args(ReasoningSummary))
+BATCH_STATUSES = frozenset(get_args(BatchStatus))
+BATCH_OUTCOMES = frozenset(get_args(BatchOutcome))
+# Job statuses in which a batch will make no further progress.
+BATCH_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled", "expired"})
+VIDEO_STATUSES = frozenset(get_args(VideoStatus))
+# Job statuses in which a video job will make no further progress.
+VIDEO_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
+FILE_READINESS_VALUES = frozenset(get_args(FileReadiness))
+AUDIO_ENCODINGS = frozenset(get_args(AudioEncoding))
+TOOL_CHOICE_MODES = frozenset(get_args(ToolChoiceMode))
+
+_P = TypeVar("_P")
+_MISSING: Any = object()
+
+# JSON-compatible values used for model inputs, tool schemas, provider
+# extensions, and provider metadata. Keep these small and boring: the
+# LM layer can map richer Python objects into this vocabulary before
+# they enter the core model.
+JsonPrimitive: TypeAlias = None | bool | int | float | str
+JsonValue: TypeAlias = JsonPrimitive | list["JsonValue"] | dict[str, "JsonValue"]
+JsonArray: TypeAlias = list[JsonValue]
+JsonObject: TypeAlias = dict[str, JsonValue]
+
+
+def _is_json_value(value: Any) -> bool:
+ """Return True if value is made only of strict JSON containers.
+
+ Complete JSON validation is necessarily proportional to payload size, so
+ keep it iterative and simple: no recursion, no copying, and no coercion of
+ tuples or non-string dict keys into something different on the wire.
+ """
+ stack = [value]
+ while stack:
+ item = stack.pop()
+ kind = type(item)
+ if item is None or kind is bool or kind is int or kind is str:
+ continue
+ if kind is float:
+ if not _math.isfinite(item):
+ return False
+ continue
+ if kind is list:
+ stack.extend(item)
+ continue
+ if kind is dict:
+ for key, child in item.items():
+ if not isinstance(key, str):
+ return False
+ stack.append(child)
+ continue
+ # Keep compatibility with scalar subclasses without paying
+ # ``isinstance`` costs for the common exact built-in types above.
+ if isinstance(item, (int, str)):
+ continue
+ if isinstance(item, float):
+ if not _math.isfinite(item):
+ return False
+ continue
+ return False
+ return True
+
+
+def _check_json_object(value: Any, *, field_name: str, required: bool = False) -> None:
+ """Validate a JSON object field without copying or wrapping it."""
+ if value is None:
+ if required:
+ raise TypeError(f"{field_name} must be a JSON object")
+ return
+ if not isinstance(value, dict):
+ raise TypeError(f"{field_name} must be a JSON object")
+ if not _is_json_value(value):
+ raise TypeError(f"{field_name} must contain only JSON-compatible values")
+
+
+def _validate_json_field(obj: object, field_name: str, *, required: bool = False) -> None:
+ """Validate a JSON object field on a dataclass."""
+ _check_json_object(getattr(obj, field_name), field_name=field_name, required=required)
+
+
+def _validate_extensions_field(obj: object) -> None:
+ """Validate extensions, normalizing an empty mapping to None."""
+ if getattr(obj, "extensions") == {}:
+ object.__setattr__(obj, "extensions", None)
+ return
+ _validate_json_field(obj, "extensions")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class ContinuationState:
+ """Opaque provider-owned state needed to continue/replay a transcript.
+
+ Continuation state is not visible model content. It travels with the
+ Message or Part it describes so provider adapters can reconstruct future
+ provider requests without relying on detached response metadata.
+ """
+
+ provider: str
+ kind: ContinuationKind
+ data: JsonObject = field(default_factory=dict)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.provider, field_name="ContinuationState.provider", allow_empty=False)
+ _validate_text(self.kind, field_name="ContinuationState.kind", allow_empty=False)
+ _validate_json_field(self, "data", required=True)
+
+ def __repr__(self) -> str:
+ return (
+ "ContinuationState("
+ f"provider={self.provider!r}, "
+ f"kind={self.kind!r}, "
+ f"data=<dict: {len(self.data)} keys>)"
+ )
+
+
+def _normalize_continuation(value: Any, *, field_name: str = "continuation") -> tuple[ContinuationState, ...]:
+ if value is None:
+ return ()
+ if isinstance(value, ContinuationState):
+ return (value,)
+ if isinstance(value, str):
+ raise TypeError(f"{field_name} must contain ContinuationState objects")
+ try:
+ states = tuple(value)
+ except TypeError as exc:
+ raise TypeError(f"{field_name} must be a sequence of ContinuationState objects") from exc
+ if not all(isinstance(item, ContinuationState) for item in states):
+ raise TypeError(f"{field_name} must contain ContinuationState objects")
+ return states
+
+
+def _validate_continuation_field(obj: object, field_name: str = "continuation") -> None:
+ object.__setattr__(
+ obj,
+ field_name,
+ _normalize_continuation(getattr(obj, field_name), field_name=field_name),
+ )
+
+
+def _continuation_repr(value: tuple[ContinuationState, ...]) -> str | None:
+ if not value:
+ return None
+ return f"<{len(value)} continuation state{'s' if len(value) != 1 else ''}>"
+
+
+def _continuation_by_kind(
+ value: tuple[ContinuationState, ...], provider: str, kind: str
+) -> JsonObject | None:
+ for state in value:
+ if state.provider == provider and state.kind == kind:
+ return state.data
+ return None
+
+
+def continuation_data(
+ value: Message | Part | tuple[ContinuationState, ...], provider: str, kind: str
+) -> JsonObject | None:
+ """Return provider-owned continuation data from a Message or Part.
+
+ This is a convenience helper for provider adapters and advanced callers.
+ It returns the opaque JSON object attached to the first matching
+ ContinuationState, or None when no match exists.
+ """
+ if isinstance(value, tuple):
+ states = value
+ else:
+ states = getattr(value, "continuation", ())
+ return _continuation_by_kind(states, provider, kind)
+
+
+def _coerce_int_field(obj: object, field_name: str) -> None:
+ """Number rule (docs/serde-rules.md): int fields have ONE wire form.
+
+ Same-valued float input is coerced (2.0 -> 2); non-integral floats are
+ rejected; bool never coerces (``type is float`` excludes bool, and the
+ int validators reject bool downstream).
+ """
+ value = getattr(obj, field_name)
+ if type(value) is float:
+ if not value.is_integer():
+ raise TypeError(f"{field_name} must be an int")
+ object.__setattr__(obj, field_name, int(value))
+
+
+def _coerce_float_field(obj: object, field_name: str) -> None:
+ """Number rule (docs/serde-rules.md): float fields have ONE wire form.
+
+ Same-valued int input is coerced (1 -> 1.0); bool never coerces
+ (``type is int`` excludes bool, leaving it for downstream rejection).
+ """
+ value = getattr(obj, field_name)
+ if type(value) is int:
+ object.__setattr__(obj, field_name, float(value))
+
+
+def _validate_int(value: Any, *, field_name: str) -> None:
+ """Reject non-int values, including bool (which subclasses int)."""
+ if value is None:
+ return
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise TypeError(f"{field_name} must be an int")
+
+
+def _validate_positive(value: int | None, *, field_name: str) -> None:
+ _validate_int(value, field_name=field_name)
+ if value is not None and value <= 0:
+ raise ValueError(f"{field_name} must be > 0")
+
+
+def _validate_non_negative(value: int | None, *, field_name: str) -> None:
+ _validate_int(value, field_name=field_name)
+ if value is not None and value < 0:
+ raise ValueError(f"{field_name} must be >= 0")
+
+
+def _validate_part_index(part_index: int) -> None:
+ _validate_int(part_index, field_name="part_index")
+ if part_index < 0:
+ raise ValueError("part_index must be >= 0")
+
+
+def _validate_text(value: Any, *, field_name: str, allow_empty: bool = True) -> None:
+ """Validate that value is a string (and optionally non-empty)."""
+ if not isinstance(value, str):
+ raise TypeError(f"{field_name} must be a string")
+ if not allow_empty and value == "":
+ raise ValueError(f"{field_name} cannot be empty")
+
+
+def _validate_optional_text(
+ value: Any, *, field_name: str, allow_empty: bool = True
+) -> None:
+ """Validate that an optional value is either None or a string."""
+ if value is not None:
+ _validate_text(value, field_name=field_name, allow_empty=allow_empty)
+
+
+def _validate_bool(value: Any, *, field_name: str) -> None:
+ """Validate that value is exactly a bool."""
+ if not isinstance(value, bool):
+ raise TypeError(f"{field_name} must be a bool")
+
+
+def _validate_optional_bool(value: Any, *, field_name: str) -> None:
+ """Validate that an optional value is either None or exactly a bool."""
+ if value is not None:
+ _validate_bool(value, field_name=field_name)
+
+
+# ─── Media helpers ────────────────────────────────────────────────────
+
+
+def _validate_media(
+ part_type: str,
+ data: str | None,
+ url: str | None,
+ file_id: str | None,
+ path: Path | None,
+) -> None:
+ """Validate that exactly one non-empty media source is set."""
+ count = (
+ (data is not None)
+ + (url is not None)
+ + (file_id is not None)
+ + (path is not None)
+ )
+ if count != 1:
+ raise ValueError(f"{part_type} requires exactly one of data, url, file_id, or path")
+ if path is not None:
+ if not isinstance(path, Path):
+ raise TypeError(f"{part_type} path must be a pathlib.Path")
+ return
+ name, value = (
+ ("data", data)
+ if data is not None
+ else ("url", url)
+ if url is not None
+ else ("file_id", file_id)
+ )
+ if not isinstance(value, str):
+ raise TypeError(f"{part_type} {name} must be a string")
+ if value == "":
+ raise ValueError(f"{part_type} {name} cannot be empty")
+
+
+def _validate_media_delta_addresses(
+ part_type: str, data: str | None, url: str | None, file_id: str | None
+) -> None:
+ """Validate media-delta address shape without requiring a final address."""
+ if (data is not None) + (url is not None) + (file_id is not None) > 1:
+ raise ValueError(f"{part_type} can include at most one of data, url, or file_id")
+
+
+_BASE64_RE = _re.compile(r"^[A-Za-z0-9+/]*={0,2}$")
+
+
+def _base64_payload(part_type: str, data: str | None) -> str:
+ """Return the base64 payload from a raw base64 string or data URI."""
+ if data is None:
+ raise ValueError(
+ f"{part_type} has no inline data; fetch url/file_id-addressed media before decoding"
+ )
+ if not isinstance(data, str):
+ raise TypeError(f"{part_type}.data must be a base64 string")
+ if data == "":
+ raise ValueError(f"{part_type}.data cannot be empty")
+ if data.startswith("data:") and ";base64," in data:
+ data = data.split(";base64,", 1)[1]
+ stripped = data.strip()
+ if (
+ stripped != data
+ or " " in stripped
+ or "\n" in stripped
+ or "\r" in stripped
+ or "\t" in stripped
+ or "\v" in stripped
+ or "\f" in stripped
+ ):
+ return "".join(stripped.split())
+ return data
+
+
+def _validate_base64_data(part_type: str, data: str | None) -> None:
+ """Validate base64 shape without eagerly decoding large payloads."""
+ payload = _base64_payload(part_type, data)
+ if len(payload) % 4 != 0 or not _BASE64_RE.fullmatch(payload):
+ raise ValueError(f"{part_type}.data must be a valid base64 string")
+
+
+def _decode_data(part_type: str, data: str | None) -> bytes:
+ """Decode base64 data to bytes."""
+ payload = _base64_payload(part_type, data)
+ try:
+ return _base64.b64decode(payload, validate=True)
+ except (_binascii.Error, ValueError) as e:
+ raise ValueError(f"{part_type}.data must be a valid base64 string") from e
+
+
+def _base64_summary(data: str | None) -> str | None:
+ """Return a short repr-safe summary for base64 data."""
+ if data is None:
+ return None
+ payload = _base64_payload("media", data)
+ return f"<base64: {len(payload)} chars>"
+
+
+def _base64_chunk_summary(data: str | None) -> str | None:
+ """Return a repr-safe summary for a possibly partial base64 chunk."""
+ if data is None:
+ return None
+ if data.startswith("data:") and ";base64," in data:
+ data = data.split(";base64,", 1)[1]
+ stripped = data.strip()
+ if (
+ stripped != data
+ or " " in stripped
+ or "\n" in stripped
+ or "\r" in stripped
+ or "\t" in stripped
+ or "\v" in stripped
+ or "\f" in stripped
+ ):
+ stripped = "".join(stripped.split())
+ return f"<base64: {len(stripped)} chars>"
+
+
+def _bytes_summary(data: bytes | bytearray | None) -> str | None:
+ """Return a short repr-safe summary for raw bytes."""
+ if data is None:
+ return None
+ return f"<bytes: {len(data)} bytes>"
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class _MediaMixin:
+ """Shared fields, validation, repr, and byte access for media parts."""
+
+ media_type: str
+ data: str | None = None
+ url: str | None = None
+ file_id: str | None = None
+ path: Path | None = None
+ continuation: tuple[ContinuationState, ...] = ()
+
+ def __post_init__(self) -> None:
+ if self.path is not None and not isinstance(self.path, Path):
+ if str(self.path) == "":
+ raise ValueError(f"{self.__class__.__name__} path cannot be empty")
+ object.__setattr__(self, "path", Path(self.path))
+ if not isinstance(self.media_type, str) or self.media_type == "":
+ raise ValueError(f"{self.__class__.__name__} requires media_type")
+ _validate_media(self.__class__.__name__, self.data, self.url, self.file_id, self.path)
+ if self.data is not None:
+ _validate_base64_data(self.__class__.__name__, self.data)
+ _validate_continuation_field(self)
+
+ def __repr__(self) -> str:
+ fields = [
+ ("media_type", self.media_type),
+ ("data", _base64_summary(self.data)),
+ ("url", self.url),
+ ("file_id", self.file_id),
+ ("path", self.path),
+ ]
+ detail = getattr(self, "detail", None)
+ if detail is not None:
+ fields.append(("detail", detail))
+ continuation = _continuation_repr(self.continuation)
+ if continuation is not None:
+ fields.append(("continuation", continuation))
+ args = ", ".join(f"{name}={value!r}" for name, value in fields)
+ return f"{self.__class__.__name__}({args})"
+
+ @property
+ def bytes(self) -> bytes:
+ if self.data is not None:
+ return _decode_data(self.__class__.__name__, self.data)
+ if self.path is not None:
+ return self.path.read_bytes()
+ raise ValueError(
+ f"{self.__class__.__name__} has no inline data or path; "
+ "fetch url/file_id-addressed media before decoding"
+ )
+
+
+# ─── Parts ───────────────────────────────────────────────────────────
+#
+# The atoms of content. A discriminated union — check .type or use
+# isinstance(), then access the fields that belong to that variant.
+
+
+@dataclass(frozen=True, slots=True)
+class TextPart:
+ """A block of text content."""
+
+ text: str
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["text"] = field(default="text", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.text, field_name="TextPart.text")
+ _validate_continuation_field(self)
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class ImagePart(_MediaMixin):
+ """An image, addressed by exactly one of data/url/file_id/path."""
+
+ media_type: str = "image/png"
+ detail: Literal["low", "high", "auto"] | None = None
+ type: Literal["image"] = field(default="image", init=False)
+
+ def __post_init__(self) -> None:
+ _MediaMixin.__post_init__(self)
+ _validate_optional_text(self.detail, field_name="ImagePart.detail", allow_empty=False)
+ if self.detail is not None and self.detail not in {"low", "high", "auto"}:
+ raise ValueError(f"unsupported ImagePart.detail: {self.detail}")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class AudioPart(_MediaMixin):
+ """Audio content, addressed by exactly one of data/url/file_id/path."""
+
+ media_type: str = "audio/wav"
+ type: Literal["audio"] = field(default="audio", init=False)
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class VideoPart(_MediaMixin):
+ """Video content, addressed by exactly one of data/url/file_id/path."""
+
+ media_type: str = "video/mp4"
+ type: Literal["video"] = field(default="video", init=False)
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class DocumentPart(_MediaMixin):
+ """A document (PDF, etc.), addressed by exactly one of data/url/file_id/path."""
+
+ media_type: str = "application/pdf"
+ type: Literal["document"] = field(default="document", init=False)
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class BinaryPart(_MediaMixin):
+ """Arbitrary binary content, addressed by exactly one media source."""
+
+ media_type: str = "application/octet-stream"
+ type: Literal["binary"] = field(default="binary", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallPart:
+ """The model requests an external computation."""
+
+ id: str
+ name: str
+ input: JsonObject
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["tool_call"] = field(default="tool_call", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="ToolCallPart.id", allow_empty=False)
+ _validate_text(self.name, field_name="ToolCallPart.name", allow_empty=False)
+ _validate_json_field(self, "input", required=True)
+ _validate_continuation_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ToolResultPart:
+ """The result of an external computation, sent back to the model."""
+
+ id: str
+ content: tuple[ToolResultContentPart, ...]
+ name: str | None = None
+ is_error: bool = False
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["tool_result"] = field(default="tool_result", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="ToolResultPart.id", allow_empty=False)
+ _validate_optional_text(self.name, field_name="ToolResultPart.name", allow_empty=False)
+ object.__setattr__(self, "content", tuple(self.content))
+ if not self.content:
+ raise ValueError("ToolResultPart requires content")
+ if not all(_is_part(p) for p in self.content):
+ raise TypeError("ToolResultPart.content must contain Part objects")
+ _validate_bool(self.is_error, field_name="ToolResultPart.is_error")
+ # Tool results may not contain protocol parts: tool calls, nested
+ # tool results, model reasoning traces, or refusals. Only the
+ # presentational variants from ToolResultContentPart are allowed.
+ if any(isinstance(p, _TOOL_RESULT_FORBIDDEN_PARTS) for p in self.content):
+ raise TypeError(
+ "ToolResultPart.content cannot contain tool calls, nested tool "
+ "results, thinking parts, or refusals"
+ )
+ _validate_continuation_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingPart:
+ """Model reasoning trace.
+
+ Hidden thinking (Anthropic ``redacted_thinking``, an OpenAI reasoning
+ item with no summary) is a ThinkingPart with empty ``text`` and its
+ replay state in ``continuation``. There is no flag and no placeholder
+ text (MAP-7 rule 11, ratified 2026-09-06).
+ """
+
+ text: str
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["thinking"] = field(default="thinking", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.text, field_name="ThinkingPart.text")
+ _validate_continuation_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class RefusalPart:
+ """Model explicitly refused to respond.
+
+ Refusals require non-empty text because they are final semantic content;
+ empty ``TextPart``/``ThinkingPart`` values remain allowed for streaming
+ reassembly and provider redaction edge cases.
+ """
+
+ text: str
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["refusal"] = field(default="refusal", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.text, field_name="RefusalPart.text", allow_empty=False)
+ _validate_continuation_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class CitationPart:
+ """A reference to source material."""
+
+ url: str | None = None
+ title: str | None = None
+ text: str | None = None
+ continuation: tuple[ContinuationState, ...] = ()
+ type: Literal["citation"] = field(default="citation", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_optional_text(self.url, field_name="CitationPart.url", allow_empty=False)
+ _validate_optional_text(self.title, field_name="CitationPart.title", allow_empty=False)
+ _validate_optional_text(self.text, field_name="CitationPart.text", allow_empty=False)
+ if self.url is None and self.title is None and self.text is None:
+ raise ValueError("CitationPart requires at least one of url, title, or text")
+ _validate_continuation_field(self)
+
+
+_TOOL_RESULT_FORBIDDEN_PARTS: tuple[type, ...] = (
+ ToolCallPart,
+ ToolResultPart,
+ ThinkingPart,
+ RefusalPart,
+)
+
+
+# The union type. This IS the vocabulary of content.
+Part: TypeAlias = (
+ TextPart
+ | ImagePart
+ | AudioPart
+ | VideoPart
+ | DocumentPart
+ | BinaryPart
+ | ToolCallPart
+ | ToolResultPart
+ | ThinkingPart
+ | RefusalPart
+ | CitationPart
+)
+
+# Runtime dispatch table, derived from the union so adding a Part variant has
+# one source of truth: the variant class plus the Part union.
+def _variant_type(cls: type) -> str:
+ return cls.__dataclass_fields__["type"].default # type: ignore[attr-defined]
+
+
+PART_CLASSES: tuple[type, ...] = get_args(Part)
+PART_TYPES: dict[str, type] = {_variant_type(cls): cls for cls in PART_CLASSES}
+
+
+def _is_part(value: object) -> bool:
+ """Return True if value is one of lm15's concrete Part variants."""
+ return isinstance(value, PART_CLASSES)
+
+
+MediaPart: TypeAlias = ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart
+MEDIA_TYPES: tuple[type, ...] = get_args(MediaPart)
+
+# Shared endpoint metadata/content aliases
+Extensions: TypeAlias = JsonObject
+ProviderData: TypeAlias = JsonObject
+
+# Parts allowed in tool result content: presentational variants only.
+# (ToolCallPart, ToolResultPart, ThinkingPart, and RefusalPart are excluded
+# both at the type level and in ``ToolResultPart.__post_init__``.)
+ToolResultContentPart: TypeAlias = (
+ TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart | CitationPart
+)
+ToolResultContent: TypeAlias = str | ToolResultContentPart | Sequence[str | ToolResultContentPart]
+
+# Parts allowed in prompts (user/developer messages and system content).
+# Excludes model/tool protocol parts which are produced by the model or
+# tool runtime, never authored by the caller.
+PromptPart: TypeAlias = (
+ TextPart | ImagePart | AudioPart | VideoPart | DocumentPart | BinaryPart
+)
+PromptContent: TypeAlias = str | PromptPart | Sequence[str | PromptPart]
+SystemContent: TypeAlias = PromptContent
+
+# Parts allowed in assistant messages. This intentionally includes
+# model-emitted protocol/artifact parts while still excluding ToolResultPart,
+# which belongs only in tool messages.
+AssistantPart: TypeAlias = (
+ TextPart
+ | ImagePart
+ | AudioPart
+ | VideoPart
+ | DocumentPart
+ | BinaryPart
+ | ToolCallPart
+ | ThinkingPart
+ | RefusalPart
+ | CitationPart
+)
+AssistantContent: TypeAlias = str | AssistantPart | Sequence[str | AssistantPart]
+
+# Broad content alias used internally by the normalizer; role-specific
+# constructors expose narrower aliases above.
+PartInput: TypeAlias = str | Part | Sequence[str | Part]
+
+# Parts forbidden in prompts (user/developer messages and system content).
+# Defined once and reused by every prompt-side validator.
+_PROMPT_FORBIDDEN_PARTS: tuple[type, ...] = (
+ ToolCallPart,
+ ToolResultPart,
+ ThinkingPart,
+ RefusalPart,
+ CitationPart,
+)
+
+
+# ─── Part constructors ───────────────────────────────────────────────
+#
+# Factory functions for the common construction patterns. These live
+# at module level — there's no base class to hang them on.
+
+
+def text(content: str, *, continuation: Sequence[ContinuationState] | ContinuationState | None = None) -> TextPart:
+ """Create a text part."""
+ return TextPart(text=content, continuation=_normalize_continuation(continuation))
+
+
+def thinking(
+ content: str,
+ *,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> ThinkingPart:
+ return ThinkingPart(text=content, continuation=_normalize_continuation(continuation))
+
+
+def refusal(content: str, *, continuation: Sequence[ContinuationState] | ContinuationState | None = None) -> RefusalPart:
+ return RefusalPart(text=content, continuation=_normalize_continuation(continuation))
+
+
+def citation(
+ *,
+ url: str | None = None,
+ title: str | None = None,
+ text: str | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> CitationPart:
+ return CitationPart(url=url, title=title, text=text, continuation=_normalize_continuation(continuation))
+
+
+def _encode_data(data: bytes | str) -> str:
+ """Ensure data is a base64 string."""
+ if isinstance(data, bytes):
+ return _base64.b64encode(data).decode("ascii")
+ return data
+
+
+def _prepare_media_factory_input(
+ part_type: str,
+ *,
+ url: str | None,
+ data: bytes | str | None,
+ file_id: str | None,
+ path: str | PathLike[str] | None,
+ media_type: str | None,
+ default_media_type: str,
+) -> tuple[str | None, Path | None, str]:
+ count = (
+ (data is not None)
+ + (url is not None)
+ + (file_id is not None)
+ + (path is not None)
+ )
+ if count != 1:
+ raise ValueError(
+ f"{part_type} requires exactly one of data, url, file_id, or path"
+ )
+ media_path: Path | None = None
+ if path is not None:
+ if str(path) == "":
+ raise ValueError(f"{part_type} path cannot be empty")
+ media_path = Path(path)
+ media_type = media_type or _mimetypes.guess_type(str(media_path))[0]
+ encoded = _encode_data(data) if data is not None else None
+ return encoded, media_path, media_type or default_media_type
+
+
+def image(
+ *,
+ url: str | None = None,
+ data: bytes | str | None = None,
+ path: str | PathLike[str] | None = None,
+ file_id: str | None = None,
+ media_type: str | None = None,
+ detail: Literal["low", "high", "auto"] | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> ImagePart:
+ encoded_data, media_path, resolved_media_type = _prepare_media_factory_input(
+ "ImagePart",
+ url=url,
+ data=data,
+ file_id=file_id,
+ path=path,
+ media_type=media_type,
+ default_media_type="image/png",
+ )
+ return ImagePart(
+ media_type=resolved_media_type,
+ data=encoded_data,
+ url=url,
+ file_id=file_id,
+ path=media_path,
+ detail=detail,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+def audio(
+ *,
+ url: str | None = None,
+ data: bytes | str | None = None,
+ path: str | PathLike[str] | None = None,
+ file_id: str | None = None,
+ media_type: str | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> AudioPart:
+ encoded_data, media_path, resolved_media_type = _prepare_media_factory_input(
+ "AudioPart",
+ url=url,
+ data=data,
+ file_id=file_id,
+ path=path,
+ media_type=media_type,
+ default_media_type="audio/wav",
+ )
+ return AudioPart(
+ media_type=resolved_media_type,
+ data=encoded_data,
+ url=url,
+ file_id=file_id,
+ path=media_path,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+def video(
+ *,
+ url: str | None = None,
+ data: bytes | str | None = None,
+ path: str | PathLike[str] | None = None,
+ file_id: str | None = None,
+ media_type: str | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> VideoPart:
+ encoded_data, media_path, resolved_media_type = _prepare_media_factory_input(
+ "VideoPart",
+ url=url,
+ data=data,
+ file_id=file_id,
+ path=path,
+ media_type=media_type,
+ default_media_type="video/mp4",
+ )
+ return VideoPart(
+ media_type=resolved_media_type,
+ data=encoded_data,
+ url=url,
+ file_id=file_id,
+ path=media_path,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+def document(
+ *,
+ url: str | None = None,
+ data: bytes | str | None = None,
+ path: str | PathLike[str] | None = None,
+ file_id: str | None = None,
+ media_type: str | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> DocumentPart:
+ encoded_data, media_path, resolved_media_type = _prepare_media_factory_input(
+ "DocumentPart",
+ url=url,
+ data=data,
+ file_id=file_id,
+ path=path,
+ media_type=media_type,
+ default_media_type="application/pdf",
+ )
+ return DocumentPart(
+ media_type=resolved_media_type,
+ data=encoded_data,
+ url=url,
+ file_id=file_id,
+ path=media_path,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+def binary(
+ *,
+ url: str | None = None,
+ data: bytes | str | None = None,
+ path: str | PathLike[str] | None = None,
+ file_id: str | None = None,
+ media_type: str | None = None,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> BinaryPart:
+ encoded_data, media_path, resolved_media_type = _prepare_media_factory_input(
+ "BinaryPart",
+ url=url,
+ data=data,
+ file_id=file_id,
+ path=path,
+ media_type=media_type,
+ default_media_type="application/octet-stream",
+ )
+ return BinaryPart(
+ media_type=resolved_media_type,
+ data=encoded_data,
+ url=url,
+ file_id=file_id,
+ path=media_path,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+def tool_call(
+ id: str,
+ name: str,
+ input: JsonObject,
+ *,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> ToolCallPart:
+ return ToolCallPart(id=id, name=name, input=input, continuation=_normalize_continuation(continuation))
+
+
+def tool_result(
+ id: str,
+ content: ToolResultContent,
+ *,
+ name: str | None = None,
+ is_error: bool = False,
+ continuation: Sequence[ContinuationState] | ContinuationState | None = None,
+) -> ToolResultPart:
+ """Create a tool result part.
+
+ content can be a sequence of parts, a single part, or a string
+ (which becomes a TextPart). Raw bytes should be wrapped in a media part;
+ use BinaryPart for arbitrary bytes that are not image/audio/video/document.
+ """
+ parts = _normalize_parts(content) # type: ignore[arg-type]
+ return ToolResultPart(
+ id=id,
+ content=parts,
+ name=name,
+ is_error=is_error,
+ continuation=_normalize_continuation(continuation),
+ )
+
+
+# ─── Messages ────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Message:
+ """A contribution to a conversation, attributed to a speaker.
+
+ A message is a sequence of typed Parts. Roles:
+
+ - ``user`` — end-user input
+ - ``assistant`` — model output
+ - ``tool`` — tool execution results
+ - ``developer`` — high-authority instructions from the application
+ developer. Can appear mid-conversation to inject
+ new instructions without invalidating the KV-cache
+ prefix. On OpenAI this maps to the native
+ ``developer`` role; on other providers the LM
+ converts it to a user message with a clear prefix.
+ """
+
+ role: Role
+ parts: tuple[Part, ...]
+ continuation: tuple[ContinuationState, ...] = ()
+
+ def __post_init__(self) -> None:
+ if self.role not in ROLE_VALUES:
+ raise ValueError(f"unsupported role: {self.role}")
+ if isinstance(self.parts, str):
+ raise TypeError("Message.parts must be Part objects; use Message.user('text') for strings")
+ parts = (self.parts,) if _is_part(self.parts) else tuple(self.parts)
+ object.__setattr__(self, "parts", parts)
+ if not self.parts:
+ raise ValueError("Message requires at least one part")
+ if not all(_is_part(p) for p in self.parts):
+ raise TypeError("Message.parts must contain Part objects")
+ _validate_continuation_field(self)
+ _validate_message_parts(self.role, self.parts)
+
+ @staticmethod
+ def user(content: PromptContent) -> "Message":
+ return Message(role="user", parts=_normalize_parts(content))
+
+ @staticmethod
+ def assistant(content: AssistantContent) -> "Message":
+ return Message(role="assistant", parts=_normalize_parts(content))
+
+ @staticmethod
+ def developer(content: PromptContent) -> "Message":
+ """Create a developer message.
+
+ Developer messages carry instructions with higher authority than
+ user messages (equivalent to OpenAI's ``developer`` role). They
+ can appear anywhere in the conversation — including mid-conversation
+ — which is useful for injecting new instructions without
+ invalidating the KV-cache prefix built from earlier turns.
+
+ On providers that don't natively support a developer role
+ (Anthropic, Gemini), the LM converts these to user messages
+ with a clear ``[developer]`` prefix so the model still sees the
+ instruction boundary.
+ """
+ return Message(role="developer", parts=_normalize_parts(content))
+
+ @staticmethod
+ def tool(
+ results: "str | ToolResultPart | Sequence[ToolResultPart] | dict[str, ToolResultContent]",
+ output: "ToolResultContent | None" = None,
+ *,
+ is_error: bool = False,
+ ) -> "Message":
+ """Create a tool message. Three spellings:
+
+ - ``Message.tool(call_id, output, is_error=False)`` — one result.
+ - ``Message.tool({call_id: output, ...})`` — answer several calls
+ at once (cannot express is_error; use the other forms).
+ - ``Message.tool(part_or_parts)`` — explicit ToolResultPart(s),
+ e.g. from :func:`lm15.tool_result`.
+ """
+ if isinstance(results, str):
+ if output is None:
+ raise TypeError(
+ "Message.tool(call_id) is missing the output. Accepted "
+ "spellings: Message.tool(call_id, output, is_error=...), "
+ "Message.tool({call_id: output, ...}), or "
+ "Message.tool(ToolResultPart(...))."
+ )
+ return Message(
+ role="tool",
+ parts=(tool_result(results, output, is_error=is_error),),
+ )
+ if output is not None:
+ raise TypeError(
+ "Message.tool() takes an output only with a call-id string: "
+ "Message.tool(call_id, output, is_error=...)."
+ )
+ if is_error:
+ raise TypeError(
+ "Message.tool({...}, is_error=True) is ambiguous — the dict "
+ "form cannot say which result errored. Use "
+ "Message.tool(call_id, output, is_error=True) or "
+ "lm15.tool_result(call_id, output, is_error=True)."
+ )
+ if isinstance(results, dict):
+ parts: list[Part] = []
+ for call_id, value in results.items():
+ parts.append(tool_result(call_id, value))
+ return Message(role="tool", parts=tuple(parts))
+ parts = (results,) if isinstance(results, ToolResultPart) else tuple(results)
+ if not all(isinstance(p, ToolResultPart) for p in parts):
+ raise TypeError(
+ "Message.tool() requires ToolResultPart objects. Accepted "
+ "spellings: Message.tool(call_id, output, is_error=...), "
+ "Message.tool({call_id: output, ...}), or "
+ "Message.tool(ToolResultPart(...))."
+ )
+ return Message(role="tool", parts=parts)
+
+ def parts_of(self, cls: type[_P]) -> list[_P]:
+ """Return all parts that are instances of ``cls``."""
+ return [p for p in self.parts if isinstance(p, cls)]
+
+ def first(self, cls: type[_P]) -> _P | None:
+ """Return the first part that is an instance of ``cls``, if any."""
+ return next((p for p in self.parts if isinstance(p, cls)), None)
+
+ @property
+ def text(self) -> str | None:
+ """Text only when the message contains text and nothing else."""
+ if not all(isinstance(p, TextPart) for p in self.parts):
+ return None
+ return "\n".join(p.text for p in self.parts)
+
+
+def _normalize_parts(content: PartInput) -> tuple[Part, ...]:
+ if isinstance(content, str):
+ return (TextPart(text=content),)
+ if _is_part(content):
+ return (content,)
+ if isinstance(content, Sequence):
+ raw_parts = tuple(content)
+ if not raw_parts:
+ raise ValueError("content sequence cannot be empty")
+ parts: list[Part] = []
+ for part in raw_parts:
+ if isinstance(part, str):
+ parts.append(TextPart(text=part))
+ elif _is_part(part):
+ parts.append(part)
+ else:
+ raise TypeError("content sequence must contain strings or Part objects")
+ return tuple(parts)
+ raise TypeError("content must be a string, Part, or sequence of Parts")
+
+
+def _validate_message_parts(role: Role, parts: tuple[Part, ...]) -> None:
+ if role == "tool":
+ if not all(isinstance(p, ToolResultPart) for p in parts):
+ raise TypeError("tool messages may only contain ToolResultPart objects")
+ return
+ if role == "assistant":
+ if any(isinstance(p, ToolResultPart) for p in parts):
+ raise TypeError(
+ "assistant messages cannot contain ToolResultPart objects"
+ )
+ return
+ # User and developer messages carry prompts/instructions, not model/tool
+ # protocol parts and not model-emitted artifacts like citations.
+ if any(isinstance(p, _PROMPT_FORBIDDEN_PARTS) for p in parts):
+ raise TypeError(f"{role} messages cannot contain model/tool protocol parts")
+
+
+def _normalize_system(system: SystemContent | None) -> str | tuple[PromptPart, ...] | None:
+ if system is None:
+ return None
+ if isinstance(system, str):
+ if system == "":
+ raise ValueError("system cannot be empty")
+ return system
+ parts = _normalize_parts(system)
+ if any(isinstance(p, _PROMPT_FORBIDDEN_PARTS) for p in parts):
+ raise TypeError("system parts cannot contain model/tool protocol parts")
+ return parts
+
+
+# ─── Deltas ──────────────────────────────────────────────────────────
+#
+# A Delta is a typed fragment of a Part being assembled during
+# streaming. Like Part, Delta is a discriminated union: fields that
+# don't belong to a variant don't exist on it.
+
+DeltaType = Literal["text", "thinking", "audio", "image", "tool_call", "citation", "continuation"]
+
+
+@dataclass(frozen=True, slots=True)
+class TextDelta:
+ """A text fragment arriving during streaming.
+
+ ``logprobs`` carries the token logprobs for exactly the tokens in this
+ fragment, when the request asked for them (``Config.logprobs``) and the
+ provider streams them per chunk (verified live for OpenAI Responses,
+ 2026-09-01). Materialization concatenates fragment logprobs in arrival
+ order into ``Response.logprobs``.
+ """
+
+ text: str
+ part_index: int = 0
+ logprobs: tuple[TokenLogprob, ...] = ()
+ type: Literal["text"] = field(default="text", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_text(self.text, field_name="TextDelta.text")
+ _validate_logprobs_field(self, "logprobs", allow_none=False)
+
+
+@dataclass(frozen=True, slots=True)
+class ThinkingDelta:
+ """A reasoning/thinking fragment arriving during streaming."""
+
+ text: str
+ part_index: int = 0
+ type: Literal["thinking"] = field(default="thinking", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_text(self.text, field_name="ThinkingDelta.text")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class AudioDelta:
+ """An audio fragment arriving during streaming.
+
+ Media deltas are partial stream chunks, not final media parts. They may
+ carry unaligned base64 data, a URL/file id update, or metadata only; final
+ media validation happens when the stream is assembled into an AudioPart.
+ """
+
+ data: str | None = None
+ url: str | None = None
+ file_id: str | None = None
+ part_index: int = 0
+ media_type: str | None = None
+ type: Literal["audio"] = field(default="audio", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_optional_text(self.data, field_name="AudioDelta.data")
+ _validate_optional_text(self.url, field_name="AudioDelta.url")
+ _validate_optional_text(self.file_id, field_name="AudioDelta.file_id")
+ _validate_media_delta_addresses("AudioDelta", self.data, self.url, self.file_id)
+ _validate_optional_text(self.media_type, field_name="AudioDelta.media_type", allow_empty=False)
+
+ def __repr__(self) -> str:
+ return (
+ "AudioDelta("
+ f"data={_base64_chunk_summary(self.data)!r}, "
+ f"url={self.url!r}, "
+ f"file_id={self.file_id!r}, "
+ f"part_index={self.part_index!r}, "
+ f"media_type={self.media_type!r})"
+ )
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class ImageDelta:
+ """An image fragment, addressed by exactly one of data/url/file_id."""
+
+ data: str | None = None
+ url: str | None = None
+ file_id: str | None = None
+ part_index: int = 0
+ media_type: str | None = None
+ type: Literal["image"] = field(default="image", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_optional_text(self.data, field_name="ImageDelta.data")
+ _validate_optional_text(self.url, field_name="ImageDelta.url")
+ _validate_optional_text(self.file_id, field_name="ImageDelta.file_id")
+ _validate_media_delta_addresses("ImageDelta", self.data, self.url, self.file_id)
+ _validate_optional_text(self.media_type, field_name="ImageDelta.media_type", allow_empty=False)
+
+ def __repr__(self) -> str:
+ return (
+ "ImageDelta("
+ f"data={_base64_chunk_summary(self.data)!r}, "
+ f"url={self.url!r}, "
+ f"file_id={self.file_id!r}, "
+ f"part_index={self.part_index!r}, "
+ f"media_type={self.media_type!r})"
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallDelta:
+ """A tool-call input fragment, optionally carrying call identity."""
+
+ input: str
+ part_index: int = 0
+ id: str | None = None
+ name: str | None = None
+ type: Literal["tool_call"] = field(default="tool_call", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_text(self.input, field_name="ToolCallDelta.input")
+ _validate_optional_text(self.id, field_name="ToolCallDelta.id", allow_empty=False)
+ _validate_optional_text(self.name, field_name="ToolCallDelta.name", allow_empty=False)
+
+
+@dataclass(frozen=True, slots=True)
+class CitationDelta:
+ """A citation fragment arriving during streaming."""
+
+ text: str | None = None
+ url: str | None = None
+ title: str | None = None
+ part_index: int = 0
+ type: Literal["citation"] = field(default="citation", init=False)
+
+ def __post_init__(self) -> None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+ _validate_optional_text(self.text, field_name="CitationDelta.text")
+ _validate_optional_text(self.url, field_name="CitationDelta.url")
+ _validate_optional_text(self.title, field_name="CitationDelta.title")
+ if self.text is None and self.url is None and self.title is None:
+ raise ValueError("CitationDelta requires at least one of text, url, or title")
+
+
+@dataclass(frozen=True, slots=True)
+class ContinuationDelta:
+ """Opaque provider continuation state arriving during streaming.
+
+ part_index=None attaches the state to the assistant message; otherwise it
+ attaches to the completed part with that index.
+ """
+
+ provider: str
+ kind: ContinuationKind
+ data: JsonObject = field(default_factory=dict)
+ part_index: int | None = None
+ type: Literal["continuation"] = field(default="continuation", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.provider, field_name="ContinuationDelta.provider", allow_empty=False)
+ _validate_text(self.kind, field_name="ContinuationDelta.kind", allow_empty=False)
+ _validate_json_field(self, "data", required=True)
+ if self.part_index is not None:
+ _coerce_int_field(self, "part_index")
+ _validate_part_index(self.part_index)
+
+ def to_state(self) -> ContinuationState:
+ return ContinuationState(provider=self.provider, kind=self.kind, data=self.data)
+
+
+Delta: TypeAlias = (
+ TextDelta
+ | ThinkingDelta
+ | AudioDelta
+ | ImageDelta
+ | ToolCallDelta
+ | CitationDelta
+ | ContinuationDelta
+)
+
+DELTA_CLASSES: tuple[type, ...] = get_args(Delta)
+DELTA_TYPES: dict[str, type] = {_variant_type(cls): cls for cls in DELTA_CLASSES}
+
+# Streaming boundary: content Delta variants assemble into Parts. Some Delta
+# variants (currently ContinuationDelta) carry stream metadata that attaches to
+# a Message or Part rather than materializing as content.
+StreamablePart: TypeAlias = TextPart | ThinkingPart | ImagePart | AudioPart | ToolCallPart | CitationPart
+NonStreamablePart: TypeAlias = VideoPart | DocumentPart | BinaryPart | ToolResultPart | RefusalPart
+
+_STREAMABLE_PART_CLASSES: tuple[type, ...] = get_args(StreamablePart)
+_NON_STREAMABLE_PART_CLASSES: tuple[type, ...] = get_args(NonStreamablePart)
+_STATE_DELTA_TYPES = frozenset({"continuation"})
+
+
+def _check_streamable_partition() -> None:
+ streamable = {_variant_type(cls) for cls in _STREAMABLE_PART_CLASSES}
+ non_streamable = {_variant_type(cls) for cls in _NON_STREAMABLE_PART_CLASSES}
+ delta_types = set(DELTA_TYPES) - set(_STATE_DELTA_TYPES)
+ part_types = set(PART_TYPES)
+
+ overlap = streamable & non_streamable
+ if overlap:
+ raise RuntimeError(
+ f"StreamablePart and NonStreamablePart overlap on: {sorted(overlap)}"
+ )
+ union = streamable | non_streamable
+ if union != part_types:
+ missing = part_types - union
+ extra = union - part_types
+ raise RuntimeError(
+ "StreamablePart ∪ NonStreamablePart must equal Part. "
+ f"missing={sorted(missing)} extra={sorted(extra)}"
+ )
+ if delta_types != streamable:
+ raise RuntimeError(
+ "Delta variants must match StreamablePart. "
+ f"delta_types={sorted(delta_types)} streamable={sorted(streamable)}"
+ )
+
+
+_check_streamable_partition()
+
+
+# ─── Stream Events ───────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorDetail:
+ """Structured error information. A dataclass, not a dict."""
+
+ code: ErrorCode
+ message: str
+ provider_code: str | None = None
+
+ def __post_init__(self) -> None:
+ if self.code not in ERROR_CODES:
+ raise ValueError(f"unsupported error code: {self.code}")
+ _validate_text(self.message, field_name="ErrorDetail.message")
+ _validate_optional_text(self.provider_code, field_name="ErrorDetail.provider_code", allow_empty=False)
+
+
+@dataclass(frozen=True, slots=True)
+class StreamStartEvent:
+ """The response stream has started."""
+
+ id: str | None = None
+ model: str | None = None
+ type: Literal["start"] = field(default="start", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_optional_text(self.id, field_name="StreamStartEvent.id", allow_empty=False)
+ _validate_optional_text(self.model, field_name="StreamStartEvent.model", allow_empty=False)
+
+
+@dataclass(frozen=True, slots=True)
+class StreamDeltaEvent:
+ """A typed content delta arrived."""
+
+ delta: Delta
+ type: Literal["delta"] = field(default="delta", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.delta, DELTA_CLASSES):
+ raise TypeError("StreamDeltaEvent.delta must be a Delta")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class StreamEndEvent:
+ """The response stream completed."""
+
+ finish_reason: FinishReason | None = None
+ usage: "Usage | None" = None
+ provider_data: ProviderData | None = None
+ type: Literal["end"] = field(default="end", init=False)
+
+ def __post_init__(self) -> None:
+ if self.finish_reason is not None and self.finish_reason not in FINISH_REASONS:
+ raise ValueError(f"unsupported finish reason: {self.finish_reason}")
+ if self.usage is not None and not isinstance(self.usage, Usage):
+ raise TypeError("StreamEndEvent.usage must be a Usage")
+ _validate_json_field(self, "provider_data")
+
+ def __repr__(self) -> str:
+ fields = []
+ if self.finish_reason is not None:
+ fields.append(("finish_reason", repr(self.finish_reason)))
+ if self.usage is not None:
+ fields.append(("usage", repr(self.usage)))
+ if self.provider_data is not None:
+ if isinstance(self.provider_data, dict):
+ fields.append(("provider_data", f"<dict: {len(self.provider_data)} keys>"))
+ else:
+ fields.append(("provider_data", "<present>"))
+ fields.append(("type", repr(self.type)))
+
+ body = ",\n".join(f" {name}={value}" for name, value in fields)
+ return f"StreamEndEvent(\n{body},\n)"
+
+
+@dataclass(frozen=True, slots=True)
+class StreamErrorEvent:
+ """The stream failed."""
+
+ error: ErrorDetail
+ type: Literal["error"] = field(default="error", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.error, ErrorDetail):
+ raise TypeError("StreamErrorEvent.error must be an ErrorDetail")
+
+
+StreamEvent: TypeAlias = StreamStartEvent | StreamDeltaEvent | StreamEndEvent | StreamErrorEvent
+STREAM_EVENT_CLASSES: tuple[type, ...] = get_args(StreamEvent)
+
+
+# ─── Tools ───────────────────────────────────────────────────────────
+
+@dataclass(frozen=True, slots=True)
+class FunctionTool:
+ """Serializable function tool specification sent to the model."""
+
+ name: str
+ description: str | None = None
+ parameters: JsonObject = field(
+ default_factory=lambda: {"type": "object", "properties": {}}
+ )
+ type: Literal["function"] = field(default="function", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.name, field_name="FunctionTool.name", allow_empty=False)
+ _validate_optional_text(self.description, field_name="FunctionTool.description")
+ _validate_json_field(self, "parameters", required=True)
+
+@dataclass(frozen=True, slots=True)
+class BuiltinTool:
+ """A provider-native tool (web search, code execution, etc.)."""
+
+ name: str
+ config: JsonObject | None = None
+ type: Literal["builtin"] = field(default="builtin", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.name, field_name="BuiltinTool.name", allow_empty=False)
+ _validate_json_field(self, "config")
+
+
+Tool: TypeAlias = FunctionTool | BuiltinTool
+
+
+# ─── Configuration ───────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Reasoning:
+ """How much hidden thinking the model does before it answers (MAP-7).
+
+ ``effort`` is the one dial and is required. Vocabulary: ``off``,
+ ``minimal``, ``low``, ``medium``, ``high``, ``xhigh``, ``max``. Every
+ provider has this dial with these words; each model accepts a subset
+ and rejects the rest loudly. Adapters send the word verbatim where
+ the provider has levels; budget-only model classes (Anthropic 4.5 and
+ earlier, Gemini 2.5) express it through one documented grading table.
+ Words with no native level on a provider RAISE rather than downgrade.
+
+ There is no "adaptive" value: leaving ``config.reasoning`` unset is
+ how you let the model decide, on every provider. ``effort="off"``
+ reaches the wire as the provider's disable or fails loudly where the
+ provider cannot disable (MAP-5).
+
+ ``thinking_budget`` is a token cap on providers that count thinking
+ separately (Anthropic manual class, Gemini); it RAISES where the wire
+ has no budget. On budget-only classes the budget is the spelling on
+ the wire and ``effort`` is the intent. ``total_budget`` was removed
+ 2026-09-02: ``Config.max_tokens`` is the ceiling.
+
+ ``summary`` is visibility: ``None`` = provider default, ``"auto"`` =
+ show the thinking where a knob exists (satisfied silently where the
+ provider always shows it), ``"concise"``/``"detailed"`` = OpenAI's
+ detail levels (RAISE elsewhere).
+ """
+
+ effort: ReasoningEffort
+ thinking_budget: int | None = None
+ summary: ReasoningSummary | None = None
+
+ def __post_init__(self) -> None:
+ if self.effort not in REASONING_EFFORTS:
+ raise ValueError(f"unsupported reasoning effort: {self.effort}")
+ if self.summary is not None and self.summary not in REASONING_SUMMARIES:
+ raise ValueError(f"unsupported reasoning summary: {self.summary}")
+ _coerce_int_field(self, "thinking_budget")
+ _validate_positive(self.thinking_budget, field_name="thinking_budget")
+ if self.effort == "off" and (self.thinking_budget is not None or self.summary is not None):
+ raise ValueError(
+ "Reasoning(effort='off') cannot specify thinking_budget or summary"
+ )
+
+ @property
+ def is_off(self) -> bool:
+ return self.effort == "off"
+
+
+# ─── Cache / Prompt Caching ──────────────────────────────────
+
+CacheRetention = Literal["short", "long"]
+CacheMode = Literal["auto", "off"]
+CachePrefix = Literal["stable", "history"]
+CACHE_MODES = frozenset(get_args(CacheMode))
+CACHE_RETENTIONS = frozenset(get_args(CacheRetention))
+CACHE_PREFIXES = frozenset(get_args(CachePrefix))
+
+
+@dataclass(frozen=True, slots=True)
+class CacheConfig:
+ """
+ Universal prompt cache configuration (MAP-6, docs/mapping-rules.md).
+
+ Every provider caches in up to three tiers: automatic (nothing to
+ send, best-effort), breakpoint (a mark on a block, guaranteed above a
+ per-model minimum), resource (a stored, named, billed object). The
+ fields name INTENTS; each adapter maps an intent to the best tier it
+ has, and the result is always visible in ``Usage.cache_read_tokens``.
+
+ - mode="auto": the cheapest safe instruction (a mark on the stable
+ beginning where marks exist; nothing elsewhere).
+ - mode="off": send nothing; where a provider has a real off switch
+ for cache WRITES, send it.
+ - prefix="stable": mark the end of system + tools.
+ prefix="history": mark the end of the last message (a growing
+ chat). Providers without marks fall back to the automatic tier:
+ that fallback spends nothing and its outcome is observable, the
+ two conditions that permit it.
+ - prefix_until_index: the same intent with a precise position (the
+ last block of that message). Mutually exclusive with ``prefix``.
+ - retention: "long" asks for the longer lifetime at extra cost;
+ providers without one RAISE.
+ - key: a best-effort routing/affinity hint; providers without one RAISE.
+ - resource: the id of a stored cache object (``CacheInfo.id``) to
+ reference; providers without the resource tier RAISE.
+ """
+
+ mode: CacheMode = "auto"
+ retention: CacheRetention | None = None
+ key: str | None = None
+ prefix_until_index: int | None = None
+ prefix: CachePrefix | None = None
+ resource: str | None = None
+
+ def __post_init__(self) -> None:
+ if self.mode not in CACHE_MODES:
+ raise ValueError(f"unsupported cache mode: {self.mode}")
+ if self.retention is not None and self.retention not in CACHE_RETENTIONS:
+ raise ValueError(f"unsupported cache retention: {self.retention}")
+ if self.prefix is not None and self.prefix not in CACHE_PREFIXES:
+ raise ValueError(f"unsupported cache prefix: {self.prefix}")
+ _validate_optional_text(self.key, field_name="CacheConfig.key", allow_empty=False)
+ _validate_optional_text(self.resource, field_name="CacheConfig.resource", allow_empty=False)
+ if self.mode == "off" and (
+ self.retention is not None or self.key is not None
+ or self.prefix is not None or self.prefix_until_index is not None or self.resource is not None
+ ):
+ raise ValueError("CacheConfig(mode='off') cannot specify retention, key, prefix, prefix_until_index, or resource")
+ if self.prefix is not None and self.prefix_until_index is not None:
+ raise ValueError("CacheConfig cannot specify both prefix and prefix_until_index")
+ if self.prefix_until_index is not None:
+ _coerce_int_field(self, "prefix_until_index")
+ _validate_non_negative(self.prefix_until_index, field_name="prefix_until_index")
+
+
+# ─── Tool Choice ───────────────────────────────────────────────────────
+
+@dataclass(frozen=True, slots=True)
+class ToolChoice:
+ """How the model should use tools."""
+
+ mode: ToolChoiceMode = "auto"
+ allowed: tuple[str, ...] = ()
+ parallel: bool | None = None
+
+ def __post_init__(self) -> None:
+ if self.mode not in TOOL_CHOICE_MODES:
+ raise ValueError(f"unsupported tool choice mode: {self.mode}")
+ allowed = (self.allowed,) if isinstance(self.allowed, str) else tuple(self.allowed)
+ object.__setattr__(self, "allowed", allowed)
+ if any(not isinstance(name, str) or not name for name in self.allowed):
+ raise ValueError("ToolChoice.allowed must contain non-empty tool names")
+ _validate_optional_bool(self.parallel, field_name="ToolChoice.parallel")
+ if self.mode == "none" and (self.allowed or self.parallel is not None):
+ raise ValueError("ToolChoice(mode='none') cannot specify allowed or parallel")
+
+ @classmethod
+ def from_tools(
+ cls,
+ allowed: Tool | Sequence[Tool | str],
+ *,
+ mode: ToolChoiceMode = "auto",
+ parallel: bool | None = None,
+ ) -> "ToolChoice":
+ """Create a choice by explicitly converting Tool objects to names."""
+ if isinstance(allowed, str):
+ names = (allowed,)
+ elif isinstance(allowed, (FunctionTool, BuiltinTool)):
+ names = (allowed.name,)
+ else:
+ names = tuple(item.name if isinstance(item, (FunctionTool, BuiltinTool)) else item for item in allowed)
+ return cls(mode=mode, allowed=names, parallel=parallel)
+
+
+@dataclass(frozen=True, slots=True)
+class Config:
+ """Generation parameters.
+
+ Universal fields are typed. Provider-specific settings go in
+ `extensions` — a clearly-separated namespace that never pretends
+ to be part of the universal schema.
+ """
+
+ max_tokens: int | None = None
+ temperature: float | None = None
+ top_p: float | None = None
+ top_k: int | None = None
+ stop: tuple[str, ...] = ()
+ response_format: JsonObject | None = None
+ tool_choice: ToolChoice | None = None
+ reasoning: Reasoning | None = None
+ cache: CacheConfig | None = None
+ # Cross-provider knobs promoted from extensions (2026-09-01 burn-down):
+ # service_tier is an OPEN string namespace — the tier concept is shared
+ # (OpenAI, Anthropic), the value vocabulary is provider-owned, like
+ # `voice`. user_id is an opaque end-user identifier for abuse
+ # attribution (OpenAI safety_identifier, Anthropic metadata.user_id).
+ # store opts a request out of (or into) provider-side response storage
+ # (OpenAI and Gemini, same wire key). Providers whose wire cannot carry
+ # a set knob RAISE — never silently drop.
+ service_tier: str | None = None
+ user_id: str | None = None
+ store: bool | None = None
+ # logprobs: request token log probabilities. None = do not request;
+ # 0 = chosen tokens only; n > 0 = also the top-n alternatives per
+ # position. Provider caps (currently 0–20) are provider-owned — lm15
+ # does not hard-code them; an over-cap value maps to the provider's
+ # own InvalidRequestError. Providers without logprobs (Anthropic)
+ # RAISE — never silently drop.
+ logprobs: int | None = None
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ stop = (self.stop,) if isinstance(self.stop, str) else tuple(self.stop or ())
+ object.__setattr__(self, "stop", stop)
+ _coerce_int_field(self, "max_tokens")
+ _coerce_int_field(self, "top_k")
+ _validate_positive(self.max_tokens, field_name="max_tokens")
+ _validate_positive(self.top_k, field_name="top_k")
+ for field_name in ("temperature", "top_p"):
+ value = getattr(self, field_name)
+ if value is not None and (
+ isinstance(value, bool) or not isinstance(value, (int, float))
+ ):
+ raise TypeError(f"{field_name} must be numeric")
+ _coerce_float_field(self, field_name)
+ if self.temperature is not None and self.temperature < 0:
+ raise ValueError("temperature must be >= 0")
+ if self.top_p is not None and not (0 <= self.top_p <= 1):
+ raise ValueError("top_p must be in [0, 1]")
+ if any(not isinstance(s, str) or not s for s in self.stop):
+ raise ValueError("stop must contain non-empty strings")
+ if self.tool_choice is not None and not isinstance(self.tool_choice, ToolChoice):
+ raise TypeError("tool_choice must be a ToolChoice")
+ if self.reasoning is not None and not isinstance(self.reasoning, Reasoning):
+ raise TypeError("reasoning must be a Reasoning")
+ if self.cache is not None and not isinstance(self.cache, CacheConfig):
+ raise TypeError("cache must be a CacheConfig")
+ _validate_optional_text(self.service_tier, field_name="Config.service_tier", allow_empty=False)
+ _validate_optional_text(self.user_id, field_name="Config.user_id", allow_empty=False)
+ if self.store is not None and not isinstance(self.store, bool):
+ raise TypeError("Config.store must be a bool or None")
+ _coerce_int_field(self, "logprobs")
+ _validate_non_negative(self.logprobs, field_name="logprobs")
+ _validate_json_field(self, "response_format")
+ _validate_response_format_shape(self.response_format)
+ _validate_extensions_field(self)
+
+
+_RESPONSE_FORMAT_TYPES = ("json_object", "json_schema")
+
+
+def _validate_response_format_shape(value: JsonObject | None) -> None:
+ """INV-050 (MAP-8, 2026-09-02): response_format has exactly two shapes.
+
+ ``{"type": "json_object"}`` — any valid JSON;
+ ``{"type": "json_schema", "schema": <JSON Schema>, "name"?: str,
+ "strict"?: bool}`` — this schema. Provider-native spellings
+ (``{"format": ...}``, ``{"response_mime_type": ...}``,
+ ``{"json_schema": {...}}``, a bare schema) belong in ``extensions``.
+ ``schema`` is opaque and verbatim: lm15 never rewrites a keyword to
+ make a request pass; the provider's 400 is the contract.
+ """
+ if value is None:
+ return
+ fmt = value.get("type")
+ if fmt not in _RESPONSE_FORMAT_TYPES:
+ raise ValueError(
+ "response_format must be {'type': 'json_object'} or {'type': 'json_schema', "
+ "'schema': {...}, 'name'?: str, 'strict'?: bool}; provider-native shapes go in "
+ f"Config.extensions (got keys {sorted(value)})"
+ )
+ allowed = {"type"} if fmt == "json_object" else {"type", "schema", "name", "strict"}
+ extra = set(value) - allowed
+ if extra:
+ raise ValueError(f"response_format {fmt!r} does not take keys {sorted(extra)}; provider-native shapes go in Config.extensions")
+ if fmt == "json_schema":
+ if not isinstance(value.get("schema"), dict):
+ raise ValueError("response_format json_schema requires a 'schema' object")
+ if "name" in value and (not isinstance(value["name"], str) or not value["name"]):
+ raise ValueError("response_format name must be a non-empty string")
+ if "strict" in value and not isinstance(value["strict"], bool):
+ raise TypeError("response_format strict must be a bool")
+
+
+# ─── Request ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class _ModelRequest:
+ """Base for endpoint requests/configs that require a model."""
+
+ model: str
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.model, str) or not self.model:
+ raise ValueError("model is required")
+
+
+@dataclass(frozen=True, slots=True)
+class Request(_ModelRequest):
+ """A complete request to a foundation model.
+
+ The composed artifact sent to the model — conversation history,
+ system instructions, available tools, and generation config.
+ """
+
+ messages: tuple[Message, ...]
+ system: str | tuple[PromptPart, ...] | None = None
+ tools: tuple[Tool, ...] = ()
+ config: Config = field(default_factory=Config)
+
+ def __post_init__(self) -> None:
+ _ModelRequest.__post_init__(self)
+ messages = (self.messages,) if isinstance(self.messages, Message) else tuple(self.messages)
+ object.__setattr__(self, "messages", messages)
+ tools = (self.tools,) if isinstance(self.tools, (FunctionTool, BuiltinTool)) else tuple(self.tools)
+ object.__setattr__(self, "tools", tools)
+ object.__setattr__(self, "system", _normalize_system(self.system))
+ if not self.messages:
+ raise ValueError("at least one message is required")
+ if not all(isinstance(m, Message) for m in self.messages):
+ raise TypeError(
+ 'Request.messages must contain Message objects — wrap plain '
+ 'text with Message.user("...").'
+ )
+ if not all(isinstance(t, (FunctionTool, BuiltinTool)) for t in self.tools):
+ raise TypeError("Request.tools must contain Tool objects")
+ tool_names = [t.name for t in self.tools]
+ if len(set(tool_names)) != len(tool_names):
+ raise ValueError("Request.tools cannot contain duplicate tool names")
+ if not isinstance(self.config, Config):
+ raise TypeError("Request.config must be a Config")
+ if self.config.tool_choice is not None and self.config.tool_choice.allowed:
+ missing = set(self.config.tool_choice.allowed) - set(tool_names)
+ if missing:
+ raise ValueError(
+ f"ToolChoice.allowed contains tools not present in Request.tools: {sorted(missing)}"
+ )
+
+
+# ─── Logprobs ────────────────────────────────────────────────────────
+#
+# Decoding telemetry: for each generated token, the chosen token's log
+# probability plus a ranked list of top alternative candidates. Two flat
+# types instead of one recursive type — the wire never nests alternatives
+# inside alternatives, and the type system should say so.
+
+
+@dataclass(frozen=True, slots=True)
+class TopLogprob:
+ """One scored alternative token at a decoding step.
+
+ ``bytes`` is the token's UTF-8 byte sequence when the provider reports
+ it (OpenAI); ``token_id`` is the vocabulary id when the provider
+ reports it (Gemini). Absence means "not reported", never zero.
+ """
+
+ token: str
+ logprob: float
+ bytes: tuple[int, ...] | None = None
+ token_id: int | None = None
+
+ def __post_init__(self) -> None:
+ _validate_text(self.token, field_name="token")
+ _coerce_float_field(self, "logprob")
+ if not isinstance(self.logprob, float):
+ raise TypeError("logprob must be a float")
+ _validate_logprob_bytes(self)
+ _coerce_int_field(self, "token_id")
+ _validate_int(self.token_id, field_name="token_id")
+
+
+@dataclass(frozen=True, slots=True)
+class TokenLogprob:
+ """The chosen token at one decoding step, with ranked alternatives.
+
+ ``top`` is the provider-reported ranked candidate list (descending
+ logprob). Providers differ on whether the chosen token appears in
+ ``top`` — no guarantee either way, and providers also differ on
+ whether the requested alternative count includes the chosen token
+ (Gemini documents that it does; OpenAI counts alternatives only).
+ lm15 preserves the provider-reported list as-is.
+ """
+
+ token: str
+ logprob: float
+ bytes: tuple[int, ...] | None = None
+ token_id: int | None = None
+ top: tuple[TopLogprob, ...] = ()
+
+ def __post_init__(self) -> None:
+ _validate_text(self.token, field_name="token")
+ _coerce_float_field(self, "logprob")
+ if not isinstance(self.logprob, float):
+ raise TypeError("logprob must be a float")
+ _validate_logprob_bytes(self)
+ _coerce_int_field(self, "token_id")
+ _validate_int(self.token_id, field_name="token_id")
+ top = (self.top,) if isinstance(self.top, TopLogprob) else tuple(self.top)
+ object.__setattr__(self, "top", top)
+ if not all(isinstance(t, TopLogprob) for t in self.top):
+ raise TypeError("TokenLogprob.top must contain TopLogprob objects")
+
+
+def _validate_logprob_bytes(obj: object) -> None:
+ value = getattr(obj, "bytes")
+ if value is None:
+ return
+ coerced = tuple(value)
+ for b in coerced:
+ if isinstance(b, bool) or not isinstance(b, int) or b < 0:
+ raise TypeError("bytes must contain non-negative ints")
+ object.__setattr__(obj, "bytes", coerced)
+
+
+def _validate_logprobs_field(obj: object, field_name: str, *, allow_none: bool) -> None:
+ value = getattr(obj, field_name)
+ if value is None:
+ if allow_none:
+ return
+ raise TypeError(f"{type(obj).__name__}.{field_name} must be a tuple, not None")
+ coerced = (value,) if isinstance(value, TokenLogprob) else tuple(value)
+ object.__setattr__(obj, field_name, coerced)
+ if not all(isinstance(t, TokenLogprob) for t in coerced):
+ raise TypeError(f"{type(obj).__name__}.{field_name} must contain TokenLogprob objects")
+
+
+# ─── Usage ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Usage:
+ """Token usage.
+
+ ``input_tokens`` and ``output_tokens`` are common dimensions.
+ ``total_tokens`` is the provider-reported or billed total when present;
+ providers may include reasoning, audio, cache, or future token classes in
+ totals differently, so it is not forced to equal input + output.
+
+ ``reasoning_tokens`` is populated only when the provider reports an exact
+ separate reasoning/thinking token count. Some providers, notably Anthropic,
+ can return ``ThinkingPart`` content while reporting only combined
+ ``output_tokens``; in that case ``reasoning_tokens`` remains ``None``.
+
+ Every counter is ``int | None``: ``None`` means "the provider did not
+ report this dimension", which is distinct from a reported ``0``.
+ ``Usage()`` with no arguments therefore means "nothing reported" and
+ serializes to ``{}`` (omitted entirely by enclosing serializers, per
+ docs/serde-rules.md).
+
+ ``total_tokens``: an explicit value is preserved as provider telemetry.
+ When omitted, it auto-computes as ``input_tokens + output_tokens`` only
+ when BOTH are present; if either is ``None`` the total stays ``None``.
+
+ Arithmetic over usage (e.g. ``InferencePricing.estimate``) must treat
+ ``None`` as "unknown", never as zero.
+
+ Counters are provider-verbatim (spec/types.md, Usage, 2026-09-02): the
+ same field means different things across providers. ``input_tokens``
+ includes cached tokens on OpenAI, Gemini, and xAI but not on Anthropic
+ (whose cache counters are disjoint); ``output_tokens`` includes
+ reasoning on OpenAI and Anthropic but not on Gemini and xAI. lm15 does
+ not normalise: that is what a bill reconciles against. A consumer
+ comparing across providers must apply the provider's rule from the
+ table in the spec; ``Response.provider_data`` and the router's
+ resolution say which provider answered.
+ """
+
+ input_tokens: int | None = None
+ output_tokens: int | None = None
+ total_tokens: int | None = None
+ cache_read_tokens: int | None = None
+ cache_write_tokens: int | None = None
+ reasoning_tokens: int | None = None
+ input_audio_tokens: int | None = None
+ output_audio_tokens: int | None = None
+
+ def __post_init__(self) -> None:
+ for field_name in (
+ "input_tokens",
+ "output_tokens",
+ "cache_read_tokens",
+ "cache_write_tokens",
+ "reasoning_tokens",
+ "input_audio_tokens",
+ "output_audio_tokens",
+ ):
+ _coerce_int_field(self, field_name)
+ _validate_non_negative(getattr(self, field_name), field_name=field_name)
+ _coerce_int_field(self, "total_tokens")
+ _validate_non_negative(self.total_tokens, field_name="total_tokens")
+ if (
+ self.total_tokens is None
+ and self.input_tokens is not None
+ and self.output_tokens is not None
+ ):
+ object.__setattr__(self, "total_tokens", self.input_tokens + self.output_tokens)
+
+
+# ─── Response ────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class Response:
+ """The composed artifact returned by a foundation model.
+
+ ``Response`` keeps only minimal convenience properties. Use
+ ``response.message.first(...)`` and ``response.message.parts_of(...)``
+ for variant-specific content access.
+ """
+
+ id: str | None
+ model: str
+ message: Message
+ finish_reason: FinishReason
+ usage: Usage
+ # Decoding telemetry, same category as usage/finish_reason. None =
+ # provider did not report logprobs (the Usage convention). When a
+ # response holds several text blocks, per-block lists concatenate in
+ # document order — the block boundary survives in the stream
+ # (TextDelta.part_index) and in provider_data, not here.
+ logprobs: tuple[TokenLogprob, ...] | None = None
+ provider_data: ProviderData | None = None
+
+ def __post_init__(self) -> None:
+ _validate_optional_text(self.id, field_name="Response.id", allow_empty=False)
+ _validate_text(self.model, field_name="Response.model", allow_empty=False)
+ if not isinstance(self.message, Message):
+ raise TypeError("Response.message must be a Message")
+ if self.message.role != "assistant":
+ raise ValueError("Response.message must have role 'assistant'")
+ if self.finish_reason not in FINISH_REASONS:
+ raise ValueError(f"unsupported finish reason: {self.finish_reason}")
+ if not isinstance(self.usage, Usage):
+ raise TypeError("Response.usage must be a Usage")
+ _validate_logprobs_field(self, "logprobs", allow_none=True)
+ _validate_json_field(self, "provider_data")
+
+ def __repr__(self) -> str:
+ display_text = self.text
+ citations = self.citations
+
+ fields = [
+ ("text", repr(display_text)) if display_text is not None else ("message", repr(self.message)),
+ ("model", repr(self.model)),
+ ("finish_reason", repr(self.finish_reason)),
+ ("usage", repr(self.usage)),
+ ]
+ if citations:
+ fields.append(("citations", repr(citations)))
+ if self.logprobs is not None:
+ fields.append(("logprobs", f"<{len(self.logprobs)} tokens>"))
+ if self.id is not None:
+ fields.append(("id", repr(self.id)))
+ if self.provider_data is not None:
+ if isinstance(self.provider_data, dict):
+ fields.append(("provider_data", f"<dict: {len(self.provider_data)} keys>"))
+ else:
+ fields.append(("provider_data", "<present>"))
+
+ body = ",\n".join(f" {name}={value}" for name, value in fields)
+ return f"Response(\n{body},\n)"
+
+ @property
+ def text(self) -> str | None:
+ """Concatenated assistant text, when the response has text.
+
+ ``Message.text`` is intentionally strict and only returns text for
+ pure-text messages. For model responses, citation and thinking parts
+ are metadata around the visible answer, so they do not make
+ ``Response.text`` unavailable.
+ """
+ text = self.message.text
+ if text is not None:
+ return text
+
+ if all(isinstance(p, (TextPart, CitationPart, ThinkingPart)) for p in self.message.parts):
+ text_parts = [p.text for p in self.message.parts if isinstance(p, TextPart)]
+ if text_parts:
+ return "\n".join(text_parts)
+ return None
+
+ @property
+ def tool_calls(self) -> list[ToolCallPart]:
+ return self.message.parts_of(ToolCallPart)
+
+ @property
+ def citations(self) -> list[CitationPart]:
+ return self.message.parts_of(CitationPart)
+
+ def parse_json(self, *, default: Any = _MISSING) -> Any:
+ """Parse the response text as exact JSON."""
+ t = self.text
+ if t is None:
+ if default is not _MISSING:
+ return default
+ raise ValueError(
+ "Cannot parse response as JSON: response is not pure text. "
+ f"Parts: {[p.type for p in self.message.parts]}"
+ )
+ stripped = t.strip()
+ try:
+ return _json.loads(stripped)
+ except _json.JSONDecodeError as e:
+ if default is not _MISSING:
+ return default
+ preview = stripped[:200] + ("..." if len(stripped) > 200 else "")
+ raise ValueError(
+ f"Cannot parse response as JSON: {e}\nRaw text: {preview}"
+ ) from e
+
+ @property
+ def json(self) -> Any:
+ """Parsed exact JSON text, or ``None`` when parsing fails.
+
+ Valid JSON ``null`` also returns ``None``; use ``parse_json()`` when
+ parse failures should be reported distinctly.
+ """
+ return self.parse_json(default=None)
+
+
+# ─── File Upload ─────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class FileUploadRequest:
+ """A file upload request.
+
+ Files are an ACCOUNT-scoped resource on every provider, so there is
+ no ``model`` field. Uploads can be backed by in-memory bytes or by a
+ local path. Path-backed uploads are lazy: LMs can stream from disk
+ instead of forcing the whole file into memory at construction time,
+ and they are runtime-only — the canonical serializer rejects them
+ because a local path is meaningless off this machine.
+ """
+
+ filename: str
+ bytes_data: bytes | None = None
+ media_type: str = "application/octet-stream"
+ extensions: Extensions | None = None
+ path: Path | None = None
+
+ def __post_init__(self) -> None:
+ _validate_text(self.filename, field_name="FileUploadRequest.filename", allow_empty=False)
+ if self.path is not None and not isinstance(self.path, Path):
+ if str(self.path) == "":
+ raise ValueError("path cannot be empty")
+ object.__setattr__(self, "path", Path(self.path))
+ if self.bytes_data is None and self.path is None:
+ raise TypeError("FileUploadRequest requires bytes_data or path")
+ if self.bytes_data is not None and self.path is not None:
+ raise ValueError("FileUploadRequest requires exactly one of bytes_data or path")
+ if self.bytes_data is not None:
+ if not isinstance(self.bytes_data, (bytes, bytearray)):
+ raise TypeError("bytes_data must be bytes")
+ if not self.bytes_data:
+ raise ValueError("bytes_data is required")
+ if isinstance(self.bytes_data, bytearray):
+ object.__setattr__(self, "bytes_data", bytes(self.bytes_data))
+ if self.path is not None and str(self.path) == "":
+ raise ValueError("path cannot be empty")
+ _validate_text(self.media_type, field_name="FileUploadRequest.media_type", allow_empty=False)
+ _validate_extensions_field(self)
+
+ def __repr__(self) -> str:
+ return (
+ "FileUploadRequest("
+ f"filename={self.filename!r}, "
+ f"bytes_data={_bytes_summary(self.bytes_data)!r}, "
+ f"media_type={self.media_type!r}, "
+ f"extensions={self.extensions!r}, "
+ f"path={self.path!r})"
+ )
+
+ @property
+ def bytes(self) -> bytes:
+ if self.bytes_data is not None:
+ return self.bytes_data
+ if self.path is not None:
+ return self.path.read_bytes()
+ raise ValueError("FileUploadRequest has neither bytes_data nor path")
+
+
+@dataclass(frozen=True, slots=True)
+class FileInfo:
+ """A snapshot of one provider-side stored file.
+
+ ``id`` is the canonical reference for this provider: paste it into a
+ media Part's ``file_id`` and the chat mapping places it on the wire
+ (OpenAI/Anthropic file ids verbatim; Gemini the file URI, because
+ Gemini requests address files by URI, not resource name).
+
+ Optional fields stay ``None`` when the provider does not report the
+ value (OpenAI reports no MIME type; only Gemini reports expiry).
+ ``downloadable`` is tri-state: ``True``/``False`` when the provider
+ states the capability, ``None`` when it does not say.
+ """
+
+ id: str
+ filename: str | None = None
+ media_type: str | None = None
+ size_bytes: int | None = None
+ created_at: str | None = None
+ expires_at: str | None = None
+ readiness: FileReadiness = "ready"
+ downloadable: bool | None = None
+ provider_data: ProviderData | None = None
+
+ @property
+ def ready(self) -> bool:
+ return self.readiness == "ready"
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="FileInfo.id", allow_empty=False)
+ _validate_optional_text(self.filename, field_name="FileInfo.filename", allow_empty=False)
+ _validate_optional_text(self.media_type, field_name="FileInfo.media_type", allow_empty=False)
+ _coerce_int_field(self, "size_bytes")
+ _validate_non_negative(self.size_bytes, field_name="FileInfo.size_bytes")
+ _validate_optional_text(self.created_at, field_name="FileInfo.created_at", allow_empty=False)
+ _validate_optional_text(self.expires_at, field_name="FileInfo.expires_at", allow_empty=False)
+ if self.readiness not in FILE_READINESS_VALUES:
+ raise ValueError(f"unsupported file readiness: {self.readiness}")
+ if self.downloadable is not None and not isinstance(self.downloadable, bool):
+ raise TypeError("FileInfo.downloadable must be a bool or None")
+ _validate_json_field(self, "provider_data")
+
+
+@dataclass(frozen=True, slots=True)
+class FilePage:
+ """One page of stored files plus an opaque continuation cursor.
+
+ ``next_cursor`` is provider-issued and opaque: pass it back to
+ ``file_list`` to fetch the next page; ``None`` means the listing is
+ complete.
+ """
+
+ items: tuple[FileInfo, ...] = ()
+ next_cursor: str | None = None
+
+ def __post_init__(self) -> None:
+ object.__setattr__(self, "items", tuple(self.items))
+ if not all(isinstance(item, FileInfo) for item in self.items):
+ raise TypeError("FilePage.items must contain FileInfo objects")
+ _validate_optional_text(self.next_cursor, field_name="FilePage.next_cursor", allow_empty=False)
+
+
+# ─── Cache resources (the stored tier of MAP-6) ──────────────────────
+#
+# A stored cache object belongs to one model on every provider that has
+# the tier (a KV state is model-specific by nature). ``CacheInfo`` is the
+# snapshot; ``CachedPrefix`` is the ergonomic that pairs a prefix Request
+# with its optional object and builds requests against it. Nothing here
+# names a provider: id formats, TTL spellings, and what the wire does with
+# ``CacheConfig.resource`` are the adapter's business.
+
+
+@dataclass(frozen=True, slots=True)
+class CacheInfo:
+ """A snapshot of one provider-side stored cache object.
+
+ ``id`` is the provider's reference verbatim; place it in
+ ``CacheConfig.resource``. ``tokens`` is the stored token count when
+ reported (storage cost = tokens x hours x the provider's rate).
+ ``expires_at`` is ISO-8601 UTC, normalized from the provider's form.
+ """
+
+ id: str
+ model: str
+ tokens: int | None = None
+ created_at: str | None = None
+ expires_at: str | None = None
+ label: str | None = None
+ provider_data: ProviderData | None = None
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="CacheInfo.id", allow_empty=False)
+ _validate_text(self.model, field_name="CacheInfo.model", allow_empty=False)
+ _coerce_int_field(self, "tokens")
+ _validate_non_negative(self.tokens, field_name="CacheInfo.tokens")
+ _validate_optional_text(self.created_at, field_name="CacheInfo.created_at", allow_empty=False)
+ _validate_optional_text(self.expires_at, field_name="CacheInfo.expires_at", allow_empty=False)
+ _validate_optional_text(self.label, field_name="CacheInfo.label", allow_empty=False)
+ _validate_json_field(self, "provider_data")
+
+
+@dataclass(frozen=True, slots=True)
+class CachePage:
+ """One page of stored cache objects plus an opaque continuation cursor."""
+
+ items: tuple[CacheInfo, ...] = ()
+ next_cursor: str | None = None
+
+ def __post_init__(self) -> None:
+ object.__setattr__(self, "items", tuple(self.items))
+ if not all(isinstance(item, CacheInfo) for item in self.items):
+ raise TypeError("CachePage.items must contain CacheInfo objects")
+ _validate_optional_text(self.next_cursor, field_name="CachePage.next_cursor", allow_empty=False)
+
+
+@dataclass(frozen=True, slots=True)
+class CachedPrefix:
+ """A reusable prompt beginning: ``cached = lm.cache(prefix)``.
+
+ ``prefix`` is a Request whose model, system, tools, and messages form
+ the reusable part (its config must be default: a cached object has no
+ temperature). ``resource`` is the stored object on providers with
+ that tier, ``None`` on providers that mark blocks or cache
+ automatically. ``request(messages)`` builds a Request that appends
+ ``messages`` and sets the cache boundary at the seam; ``cached +
+ messages`` is Python sugar for it. The built Request and its wire
+ bytes are what the contract pins; the sugar is per-language.
+ """
+
+ prefix: Request
+ resource: CacheInfo | None = None
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.prefix, Request):
+ raise TypeError("CachedPrefix.prefix must be a Request")
+ if self.prefix.config != Config():
+ raise ValueError("CachedPrefix.prefix must carry a default Config: a cached object has no generation settings")
+ if self.resource is not None:
+ if not isinstance(self.resource, CacheInfo):
+ raise TypeError("CachedPrefix.resource must be a CacheInfo")
+ if self.resource.model != self.prefix.model:
+ raise ValueError("CachedPrefix.resource.model must equal the prefix model (a stored cache belongs to one model)")
+
+ @property
+ def id(self) -> str | None:
+ return self.resource.id if self.resource is not None else None
+
+ @property
+ def expires_at(self) -> str | None:
+ return self.resource.expires_at if self.resource is not None else None
+
+ def cache_config(self) -> CacheConfig:
+ """The CacheConfig that marks the seam between prefix and suffix."""
+ return CacheConfig(
+ prefix_until_index=len(self.prefix.messages) - 1,
+ resource=self.id,
+ )
+
+ def request(
+ self,
+ messages: "str | Message | Sequence[Message] | Request",
+ *,
+ config: Config | None = None,
+ ) -> Request:
+ """Append ``messages`` to the prefix and set the cache boundary.
+
+ ``messages`` may be a string (one user message), a Message, a
+ sequence of Messages, or a Request (same model, no system, no
+ tools: the prefix owns those). ``config`` supplies generation
+ settings; its ``cache`` must be unset (the prefix decides).
+ """
+ suffix: tuple[Message, ...]
+ if isinstance(messages, Request):
+ if messages.model != self.prefix.model:
+ raise ValueError("suffix Request model must equal the prefix model")
+ if messages.system is not None or messages.tools:
+ raise ValueError("suffix Request cannot redefine system or tools: the prefix owns them")
+ if config is None and messages.config != Config():
+ config = messages.config
+ suffix = messages.messages
+ elif isinstance(messages, str):
+ suffix = (Message.user(messages),)
+ elif isinstance(messages, Message):
+ suffix = (messages,)
+ else:
+ suffix = tuple(messages)
+ if not suffix or not all(isinstance(m, Message) for m in suffix):
+ raise TypeError("messages must be a Message or a non-empty sequence of Messages")
+ base = config if config is not None else Config()
+ if base.cache is not None:
+ raise ValueError("config.cache is decided by the CachedPrefix; leave it unset")
+ from dataclasses import replace as _replace
+
+ return Request(
+ model=self.prefix.model,
+ system=self.prefix.system,
+ tools=self.prefix.tools,
+ messages=self.prefix.messages + suffix,
+ config=_replace(base, cache=self.cache_config()),
+ )
+
+ def __add__(self, messages: "str | Message | Sequence[Message] | Request") -> Request:
+ return self.request(messages)
+
+
+# ─── Batch ───────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class BatchRequest:
+ """A batch of model requests.
+
+ Each nested Request carries its own model. The optional top-level model is
+ only a routing/default convenience; when omitted, it is inferred from the
+ first nested request and does not constrain the rest of the batch.
+ """
+
+ model: str | None = None
+ requests: tuple[Request, ...] = ()
+ label: str | None = None
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ object.__setattr__(self, "requests", tuple(self.requests))
+ if not self.requests:
+ raise ValueError("requests cannot be empty")
+ if not all(isinstance(r, Request) for r in self.requests):
+ raise TypeError("BatchRequest.requests must contain Request objects")
+ _validate_optional_text(self.model, field_name="BatchRequest.model", allow_empty=False)
+ if self.model is None:
+ object.__setattr__(self, "model", self.requests[0].model)
+ _validate_optional_text(self.label, field_name="BatchRequest.label", allow_empty=False)
+ _validate_extensions_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class BatchJobInfo:
+ """A snapshot of a provider-side batch job — the ticket.
+
+ ``id`` is the provider's job id, a plain string; store it anywhere.
+ ``created_at`` is normalized to an ISO-8601 UTC string when the
+ provider reports a creation time. Raw job state stays verbatim in
+ ``provider_data``.
+ """
+
+ id: str
+ status: BatchStatus
+ label: str | None = None
+ created_at: str | None = None
+ provider_data: ProviderData | None = None
+
+ @property
+ def done(self) -> bool:
+ return self.status in BATCH_TERMINAL_STATUSES
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="BatchJobInfo.id", allow_empty=False)
+ if self.status not in BATCH_STATUSES:
+ raise ValueError(f"unsupported batch status: {self.status}")
+ _validate_optional_text(self.label, field_name="BatchJobInfo.label", allow_empty=False)
+ _validate_optional_text(self.created_at, field_name="BatchJobInfo.created_at", allow_empty=False)
+ _validate_json_field(self, "provider_data")
+
+
+@dataclass(frozen=True, slots=True)
+class BatchEntry:
+ """The fate of one request in a batch, in submission order.
+
+ Partial failure is a first-class outcome: a ``completed`` job may mix
+ ``succeeded`` and ``errored`` entries. ``succeeded`` carries a full
+ canonical Response; ``errored`` carries a canonical ErrorDetail;
+ ``cancelled`` and ``expired`` carry neither.
+ """
+
+ index: int
+ outcome: BatchOutcome
+ response: Response | None = None
+ error: ErrorDetail | None = None
+
+ @property
+ def ok(self) -> bool:
+ return self.outcome == "succeeded"
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.index, int) or isinstance(self.index, bool) or self.index < 0:
+ raise ValueError("BatchEntry.index must be a non-negative int")
+ if self.outcome not in BATCH_OUTCOMES:
+ raise ValueError(f"unsupported batch outcome: {self.outcome}")
+ if self.outcome == "succeeded":
+ if not isinstance(self.response, Response) or self.error is not None:
+ raise ValueError("succeeded entries carry a Response and no error")
+ elif self.outcome == "errored":
+ if not isinstance(self.error, ErrorDetail) or self.response is not None:
+ raise ValueError("errored entries carry an ErrorDetail and no response")
+ elif self.response is not None or self.error is not None:
+ raise ValueError(f"{self.outcome} entries carry neither response nor error")
+
+
+@dataclass(frozen=True, slots=True)
+class _PromptRequest(_ModelRequest):
+ """Base for endpoint requests that require a non-empty text prompt."""
+
+ prompt: str
+
+ def __post_init__(self) -> None:
+ _ModelRequest.__post_init__(self)
+ if not isinstance(self.prompt, str):
+ raise TypeError("prompt must be a string")
+ if self.prompt == "":
+ raise ValueError("prompt is required")
+
+
+# ─── Image Generation ────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ImageGenerationRequest(_PromptRequest):
+ """Text (and optionally input images, for edits) in; images out.
+
+ ``size`` takes the provider's own sizing vocabulary — like ``model``
+ and ``voice``, the field is portable but the values are not (OpenAI:
+ pixels; Gemini: aspect ratios). ``images`` are ordinary ImageParts
+ (inline data / url / file_id / path); adapters route them to the
+ provider's real edit door and raise where the wire has none.
+ """
+
+ size: str | None = None
+ images: tuple[ImagePart, ...] = ()
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ _PromptRequest.__post_init__(self)
+ _validate_optional_text(self.size, field_name="size", allow_empty=False)
+ object.__setattr__(self, "images", tuple(self.images))
+ if not all(isinstance(img, ImagePart) for img in self.images):
+ raise TypeError("ImageGenerationRequest.images must contain ImagePart objects")
+ _validate_extensions_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class ImageGenerationResponse:
+ """Generated images, plus any text the model said while drawing
+ (Gemini routinely narrates; dropping it would be silent data loss)."""
+
+ images: tuple[ImagePart, ...]
+ text: str | None = None
+ id: str | None = None
+ model: str | None = None
+ usage: Usage = field(default_factory=Usage)
+ provider_data: ProviderData | None = None
+
+ def __post_init__(self) -> None:
+ _validate_optional_text(self.text, field_name="ImageGenerationResponse.text", allow_empty=False)
+ _validate_optional_text(self.id, field_name="ImageGenerationResponse.id", allow_empty=False)
+ _validate_optional_text(self.model, field_name="ImageGenerationResponse.model", allow_empty=False)
+ if not isinstance(self.usage, Usage):
+ raise TypeError("ImageGenerationResponse.usage must be a Usage")
+ object.__setattr__(self, "images", tuple(self.images))
+ if not self.images:
+ raise ValueError("ImageGenerationResponse requires at least one image")
+ if not all(isinstance(img, ImagePart) for img in self.images):
+ raise TypeError("images must contain ImagePart objects")
+ _validate_json_field(self, "provider_data")
+
+
+# ─── Speech Generation ────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class SpeechGenerationRequest(_PromptRequest):
+ """Text-to-speech. Named for what every wire actually sells: speech.
+
+ ``voice`` and ``format`` take the provider's own vocabularies. An
+ omitted field means the SERVER decides (OpenAI's real default format
+ is MP3); lm15 injects no defaults of its own. ``format`` raises on
+ providers whose wire has no slot for it (Gemini: always PCM).
+ """
+
+ voice: str | None = None
+ format: str | None = None
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ _PromptRequest.__post_init__(self)
+ _validate_optional_text(self.voice, field_name="voice", allow_empty=False)
+ _validate_optional_text(self.format, field_name="format", allow_empty=False)
+ _validate_extensions_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class SpeechGenerationResponse:
+ audio: AudioPart
+ id: str | None = None
+ model: str | None = None
+ usage: Usage = field(default_factory=Usage)
+ provider_data: ProviderData | None = None
+
+ def __post_init__(self) -> None:
+ _validate_optional_text(self.id, field_name="SpeechGenerationResponse.id", allow_empty=False)
+ _validate_optional_text(self.model, field_name="SpeechGenerationResponse.model", allow_empty=False)
+ if not isinstance(self.usage, Usage):
+ raise TypeError("SpeechGenerationResponse.usage must be a Usage")
+ if not isinstance(self.audio, AudioPart):
+ raise TypeError("audio must be an AudioPart")
+ _validate_json_field(self, "provider_data")
+
+
+# ─── Video Generation ────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class VideoGenerationRequest(_PromptRequest):
+ """Text (and optionally an input image) in; a video JOB out.
+
+ Video is job-shaped on every wire that sells it (Sora, Veo,
+ grok-imagine): submission returns a ticket, not bytes. ``seconds``
+ maps to the provider's duration knob and raises where the wire has
+ none; ``images`` are input frames (image-to-video), ordinary
+ ImageParts.
+ """
+
+ seconds: int | None = None
+ images: tuple[ImagePart, ...] = ()
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ _PromptRequest.__post_init__(self)
+ if self.seconds is not None and (
+ not isinstance(self.seconds, int) or isinstance(self.seconds, bool) or self.seconds <= 0
+ ):
+ raise ValueError("VideoGenerationRequest.seconds must be a positive int")
+ object.__setattr__(self, "images", tuple(self.images))
+ if not all(isinstance(img, ImagePart) for img in self.images):
+ raise TypeError("VideoGenerationRequest.images must contain ImagePart objects")
+ _validate_extensions_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class VideoJobInfo:
+ """A snapshot of a provider-side video job — the ticket.
+
+ ``id`` is the provider's job id, a plain string; store it anywhere
+ (on xAI it is the ONLY copy — the wire has no list endpoint).
+ ``progress`` is a percentage when the provider reports one. Raw job
+ state stays verbatim in ``provider_data``.
+ """
+
+ id: str
+ status: VideoStatus
+ progress: int | None = None
+ created_at: str | None = None
+ model: str | None = None
+ provider_data: ProviderData | None = None
+
+ @property
+ def done(self) -> bool:
+ return self.status in VIDEO_TERMINAL_STATUSES
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="VideoJobInfo.id", allow_empty=False)
+ if self.status not in VIDEO_STATUSES:
+ raise ValueError(f"unsupported video status: {self.status}")
+ if self.progress is not None and (
+ not isinstance(self.progress, int) or isinstance(self.progress, bool)
+ or not 0 <= self.progress <= 100
+ ):
+ raise ValueError("VideoJobInfo.progress must be an int percentage 0-100")
+ _validate_optional_text(self.created_at, field_name="VideoJobInfo.created_at", allow_empty=False)
+ _validate_optional_text(self.model, field_name="VideoJobInfo.model", allow_empty=False)
+ _validate_json_field(self, "provider_data")
+
+
+EndpointRequest: TypeAlias = (
+ Request
+ | FileUploadRequest
+ | BatchRequest
+ | ImageGenerationRequest
+ | SpeechGenerationRequest
+ | VideoGenerationRequest
+)
+
+EndpointResponse: TypeAlias = (
+ Response
+ | FileInfo
+ | BatchJobInfo
+ | ImageGenerationResponse
+ | SpeechGenerationResponse
+ | VideoJobInfo
+)
+
+
+# ─── Audio Format ────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class AudioFormat:
+ encoding: AudioEncoding
+ sample_rate: int
+ channels: int = 1
+
+ def __post_init__(self) -> None:
+ if self.encoding not in AUDIO_ENCODINGS:
+ raise ValueError(f"unsupported audio encoding: {self.encoding}")
+ _coerce_int_field(self, "sample_rate")
+ _coerce_int_field(self, "channels")
+ _validate_positive(self.sample_rate, field_name="sample_rate")
+ _validate_positive(self.channels, field_name="channels")
+
+
+# ─── Live (Realtime) ─────────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class LiveConfig(_ModelRequest):
+ system: str | tuple[PromptPart, ...] | None = None
+ tools: tuple[Tool, ...] = ()
+ voice: str | None = None
+ input_format: AudioFormat | None = None
+ output_format: AudioFormat | None = None
+ extensions: Extensions | None = None
+
+ def __post_init__(self) -> None:
+ _ModelRequest.__post_init__(self)
+ object.__setattr__(self, "tools", tuple(self.tools))
+ object.__setattr__(self, "system", _normalize_system(self.system))
+ if not all(isinstance(t, (FunctionTool, BuiltinTool)) for t in self.tools):
+ raise TypeError("LiveConfig.tools must contain Tool objects")
+ tool_names = [t.name for t in self.tools]
+ if len(set(tool_names)) != len(tool_names):
+ raise ValueError("LiveConfig.tools cannot contain duplicate tool names")
+ if self.input_format is not None and not isinstance(self.input_format, AudioFormat):
+ raise TypeError("input_format must be an AudioFormat")
+ if self.output_format is not None and not isinstance(self.output_format, AudioFormat):
+ raise TypeError("output_format must be an AudioFormat")
+ _validate_optional_text(self.voice, field_name="LiveConfig.voice", allow_empty=False)
+ _validate_extensions_field(self)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientTurnEvent:
+ parts: tuple[PromptPart, ...]
+ turn_complete: bool = True
+ type: Literal["turn"] = field(default="turn", init=False)
+
+ def __post_init__(self) -> None:
+ parts = (self.parts,) if _is_part(self.parts) else tuple(self.parts)
+ object.__setattr__(self, "parts", parts)
+ if not self.parts:
+ raise ValueError("LiveClientTurnEvent requires at least one part")
+ if not all(_is_part(p) for p in self.parts):
+ raise TypeError("LiveClientTurnEvent.parts must contain Part objects")
+ if any(isinstance(p, _PROMPT_FORBIDDEN_PARTS) for p in self.parts):
+ raise TypeError("LiveClientTurnEvent.parts cannot contain model/tool protocol parts")
+ _validate_bool(self.turn_complete, field_name="LiveClientTurnEvent.turn_complete")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientAudioEvent:
+ data: str
+ media_type: str = "audio/pcm;rate=16000"
+ type: Literal["audio"] = field(default="audio", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.data, field_name="LiveClientAudioEvent.data", allow_empty=False)
+ _validate_base64_data("LiveClientAudioEvent", self.data)
+ _validate_text(self.media_type, field_name="LiveClientAudioEvent.media_type", allow_empty=False)
+ if not self.media_type.startswith("audio/"):
+ raise ValueError("LiveClientAudioEvent.media_type must start with 'audio/'")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientImageEvent:
+ data: str
+ media_type: str = "image/jpeg"
+ type: Literal["image"] = field(default="image", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.data, field_name="LiveClientImageEvent.data", allow_empty=False)
+ _validate_base64_data("LiveClientImageEvent", self.data)
+ _validate_text(self.media_type, field_name="LiveClientImageEvent.media_type", allow_empty=False)
+ if not self.media_type.startswith("image/"):
+ raise ValueError("LiveClientImageEvent.media_type must start with 'image/'")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientTextEvent:
+ text: str
+ type: Literal["text"] = field(default="text", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.text, field_name="LiveClientTextEvent.text")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientToolResultEvent:
+ id: str
+ content: tuple[ToolResultContentPart, ...]
+ type: Literal["tool_result"] = field(default="tool_result", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="LiveClientToolResultEvent.id", allow_empty=False)
+ object.__setattr__(self, "content", tuple(self.content))
+ if not self.content:
+ raise ValueError("LiveClientToolResultEvent requires content")
+ if not all(_is_part(p) for p in self.content):
+ raise TypeError("LiveClientToolResultEvent.content must contain Part objects")
+ if any(isinstance(p, _TOOL_RESULT_FORBIDDEN_PARTS) for p in self.content):
+ raise TypeError("LiveClientToolResultEvent.content cannot contain model or protocol parts")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientInterruptEvent:
+ type: Literal["interrupt"] = field(default="interrupt", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveClientEndAudioEvent:
+ type: Literal["end_audio"] = field(default="end_audio", init=False)
+
+
+LiveClientEvent: TypeAlias = (
+ LiveClientTurnEvent
+ | LiveClientAudioEvent
+ | LiveClientImageEvent
+ | LiveClientTextEvent
+ | LiveClientToolResultEvent
+ | LiveClientInterruptEvent
+ | LiveClientEndAudioEvent
+)
+LIVE_CLIENT_EVENT_CLASSES: tuple[type, ...] = get_args(LiveClientEvent)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerAudioEvent:
+ data: str
+ media_type: str | None = None
+ type: Literal["audio"] = field(default="audio", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.data, field_name="LiveServerAudioEvent.data", allow_empty=False)
+ _validate_base64_data("LiveServerAudioEvent", self.data)
+ _validate_optional_text(self.media_type, field_name="LiveServerAudioEvent.media_type", allow_empty=False)
+ if self.media_type is not None and not self.media_type.startswith("audio/"):
+ raise ValueError("LiveServerAudioEvent.media_type must start with 'audio/'")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerTextEvent:
+ text: str
+ type: Literal["text"] = field(default="text", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.text, field_name="LiveServerTextEvent.text")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerToolCallEvent:
+ id: str
+ name: str
+ input: JsonObject
+ type: Literal["tool_call"] = field(default="tool_call", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="LiveServerToolCallEvent.id", allow_empty=False)
+ _validate_text(self.name, field_name="LiveServerToolCallEvent.name", allow_empty=False)
+ _validate_json_field(self, "input", required=True)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerToolCallDeltaEvent:
+ input_delta: str
+ id: str | None = None
+ name: str | None = None
+ type: Literal["tool_call_delta"] = field(default="tool_call_delta", init=False)
+
+ def __post_init__(self) -> None:
+ _validate_text(self.input_delta, field_name="LiveServerToolCallDeltaEvent.input_delta")
+ _validate_optional_text(self.id, field_name="LiveServerToolCallDeltaEvent.id", allow_empty=False)
+ _validate_optional_text(self.name, field_name="LiveServerToolCallDeltaEvent.name", allow_empty=False)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerInterruptedEvent:
+ type: Literal["interrupted"] = field(default="interrupted", init=False)
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerTurnEndEvent:
+ usage: Usage
+ type: Literal["turn_end"] = field(default="turn_end", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.usage, Usage):
+ raise TypeError("LiveServerTurnEndEvent.usage must be a Usage")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerUsageEvent:
+ """Billed usage for a response that did not end the turn.
+
+ A function-call response (the model waits for results; the turn stays
+ open) and a cancelled response (barge-in) both consume tokens the
+ provider reports. ``turn_end`` carries the usage of a completed turn;
+ this event carries the usage of everything else, so a session's bill
+ is the sum of every ``usage`` and ``turn_end`` event. Never a turn
+ boundary; dispatch loops ignore it.
+ """
+
+ usage: Usage
+ type: Literal["usage"] = field(default="usage", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.usage, Usage):
+ raise TypeError("LiveServerUsageEvent.usage must be a Usage")
+
+
+@dataclass(frozen=True, slots=True)
+class LiveServerErrorEvent:
+ error: ErrorDetail
+ type: Literal["error"] = field(default="error", init=False)
+
+ def __post_init__(self) -> None:
+ if not isinstance(self.error, ErrorDetail):
+ raise TypeError("LiveServerErrorEvent.error must be an ErrorDetail")
+
+
+LiveServerEvent: TypeAlias = (
+ LiveServerAudioEvent
+ | LiveServerTextEvent
+ | LiveServerToolCallEvent
+ | LiveServerToolCallDeltaEvent
+ | LiveServerInterruptedEvent
+ | LiveServerTurnEndEvent
+ | LiveServerUsageEvent
+ | LiveServerErrorEvent
+)
+LIVE_SERVER_EVENT_CLASSES: tuple[type, ...] = get_args(LiveServerEvent)
+
+
+# ─── ToolCallInfo (for callbacks) ────────────────────────────────────
+#
+# Lightweight callback payload: same identity/input shape as ToolCallPart,
+# but without the content-part discriminator.
+
+
+@dataclass(frozen=True, slots=True)
+class ToolCallInfo:
+ """Callback view of a tool call without the part discriminator."""
+
+ id: str
+ name: str
+ input: JsonObject
+
+ def __post_init__(self) -> None:
+ _validate_text(self.id, field_name="ToolCallInfo.id", allow_empty=False)
+ _validate_text(self.name, field_name="ToolCallInfo.name", allow_empty=False)
+ _validate_json_field(self, "input", required=True)
+
+ @classmethod
+ def from_part(cls, part: ToolCallPart) -> "ToolCallInfo":
+ if not isinstance(part, ToolCallPart):
+ raise TypeError("ToolCallInfo.from_part() requires a ToolCallPart")
+ return cls(id=part.id, name=part.name, input=part.input)
+
+ def to_part(self) -> ToolCallPart:
+ return ToolCallPart(id=self.id, name=self.name, input=self.input)
+
+
+def _check_literal_vocabularies() -> None:
+ checks = (
+ ("PartType", set(get_args(PartType)), set(PART_TYPES)),
+ ("DeltaType", set(get_args(DeltaType)), set(DELTA_TYPES)),
+ ("ErrorCode", set(get_args(ErrorCode)), set(ERROR_CODES)),
+ ("FinishReason", set(get_args(FinishReason)), set(FINISH_REASONS)),
+ ("Role", set(get_args(Role)), set(ROLE_VALUES)),
+ ("StreamEventType", set(get_args(StreamEventType)), {_variant_type(cls) for cls in STREAM_EVENT_CLASSES}),
+ ("BatchStatus", set(get_args(BatchStatus)), set(BATCH_STATUSES)),
+ ("BatchOutcome", set(get_args(BatchOutcome)), set(BATCH_OUTCOMES)),
+ ("FileReadiness", set(get_args(FileReadiness)), set(FILE_READINESS_VALUES)),
+ ("AudioEncoding", set(get_args(AudioEncoding)), set(AUDIO_ENCODINGS)),
+ ("ToolChoiceMode", set(get_args(ToolChoiceMode)), set(TOOL_CHOICE_MODES)),
+ ("ReasoningEffort", set(get_args(ReasoningEffort)), set(REASONING_EFFORTS)),
+ ("ReasoningSummary", set(get_args(ReasoningSummary)), set(REASONING_SUMMARIES)),
+ ("LiveClientEventType", set(get_args(LiveClientEventType)), {_variant_type(cls) for cls in LIVE_CLIENT_EVENT_CLASSES}),
+ ("LiveServerEventType", set(get_args(LiveServerEventType)), {_variant_type(cls) for cls in LIVE_SERVER_EVENT_CLASSES}),
+ )
+ for name, literal_values, runtime_values in checks:
+ if literal_values != runtime_values:
+ raise RuntimeError(
+ f"{name} literal values must match runtime vocabulary: "
+ f"literal={sorted(literal_values)} runtime={sorted(runtime_values)}"
+ )
+
+
+_check_literal_vocabularies()
diff --git a/dspy/_vendor/lm15/vet.py b/dspy/_vendor/lm15/vet.py
new file mode 100644
index 000000000..7dcb48424
--- /dev/null
+++ b/dspy/_vendor/lm15/vet.py
@@ -0,0 +1,868 @@
+"""
+lm15.vet — the lm15 vet shim (reference implementation).
+
+Speaks the newline-delimited JSON protocol defined in
+``lm15-contract/harness/PROTOCOL.md``: one JSON request per stdin line, one
+JSON reply per stdout line, same order, one output per input. The shim only
+transforms — the harness performs all comparison and runs the shim inside a
+no-network sandbox, so this module must never open a connection.
+
+Run as: ``python -m lm15.vet`` (cwd: lm15-python).
+"""
+
+from __future__ import annotations
+
+import base64
+import dataclasses
+import json
+import sys
+import urllib.parse
+from typing import Any, Callable, Iterator, Literal, get_args, get_origin
+
+from . import types as lm15_types
+from . import serde
+from .errors import AmbiguousModelError, LM15Error, StreamAssemblyError, UnknownModelError, canonical_error_code
+from .providers import HttpResponse
+from .providers.base import BaseProviderLM
+from .result import coalesce_stream, materialize_response
+from .sse import parse_sse
+from .types import Request, Response, StreamEvent
+
+JsonObject = dict[str, Any]
+
+LANGUAGE = "python"
+
+from ._version import __version__ as IMPL_VERSION
+
+# Parse-only ops (parse_response, replay_stream, normalize_error) construct an
+# adapter but never build auth headers; the key value is irrelevant and must
+# never come from the environment.
+_PARSE_ONLY_KEY = "vet-parse-only"
+
+
+# ─── Adapters ────────────────────────────────────────────────────────
+
+def _credential_of(msg: JsonObject):
+ """PROTOCOL.md: ``credential`` (an AUTH-2 value) or the ``api_key`` shorthand."""
+ from .credentials import credential_from_dict
+
+ cred = msg.get("credential")
+ if isinstance(cred, dict):
+ return credential_from_dict(cred)
+ return str(msg["api_key"])
+
+
+def _clock_of(msg: JsonObject):
+ """The fixed clock the harness pins (``now``), or None for wall time."""
+ from .credentials import parse_rfc3339
+
+ now = msg.get("now")
+ if now is None:
+ return None
+ fixed = parse_rfc3339(str(now))
+ return lambda: fixed
+
+
+def _settings_of(msg: JsonObject) -> dict[str, str] | None:
+ settings = msg.get("settings")
+ return {str(k): str(v) for k, v in settings.items()} if isinstance(settings, dict) else None
+
+
+def _adapter(msg: JsonObject) -> BaseProviderLM:
+ return adapter_for_provider(str(msg["provider"]), _credential_of(msg), _base_url(msg),
+ settings=_settings_of(msg), clock=_clock_of(msg))
+
+
+def adapter_for_provider(provider: str, api_key: Any, base_url: str | None = None, *,
+ settings: dict[str, str] | None = None, clock: Any = None) -> BaseProviderLM:
+ """The LM a contract case's ``provider`` string names, from the registry.
+
+ A chat-bound provider (groq, deepseek, …) is the chat dialect with that
+ provider's compat preset and access policy bound, exactly as the router
+ builds it; an adapter-owned provider is its class. ``base_url``
+ overrides the provider's default (local vLLM/SGLang cases).
+ """
+ from .registry import lookup
+
+ definition = lookup(provider)
+ if definition is None:
+ raise ValueError(f"unknown provider: {provider}")
+ kwargs: dict[str, Any] = {"api_key": api_key}
+ if base_url is not None:
+ kwargs["base_url"] = base_url
+ if definition.bound:
+ kwargs["access"] = definition.access
+ if definition.compat is not None:
+ # The Gemini dialect takes no compat (the router does the same).
+ kwargs["compat"] = definition.compat
+ if definition.hosted:
+ kwargs["settings"] = settings
+ if clock is not None:
+ kwargs["clock"] = clock
+ if definition.id == "openai-codex":
+ # PROTOCOL.md pins the harness account id: the ctor cannot derive one
+ # from a non-JWT injected key, and the wire header must be exact.
+ kwargs["account_id"] = "test-account"
+ return definition.adapter(**kwargs)
+
+
+# ─── Serde kind table ────────────────────────────────────────────────
+
+JsonToObj = Callable[[JsonObject], Any]
+ObjToJson = Callable[[Any], JsonObject]
+
+def _credential_from_dict(data: JsonObject):
+ from .credentials import credential_from_dict
+
+ return credential_from_dict(data)
+
+
+def _credential_to_dict(value: Any) -> JsonObject:
+ from .credentials import credential_to_dict
+
+ return credential_to_dict(value)
+
+
+KIND_SERDE: dict[str, tuple[JsonToObj, ObjToJson]] = {
+ "part": (serde.part_from_dict, serde.part_to_dict),
+ "message": (serde.message_from_dict, serde.message_to_dict),
+ "tool": (serde.tool_from_dict, serde.tool_to_dict),
+ "tool_choice": (serde.tool_choice_from_dict, serde.tool_choice_to_dict),
+ "reasoning": (serde.reasoning_from_dict, serde.reasoning_to_dict),
+ "config": (serde.config_from_dict, serde.config_to_dict),
+ "cache_config": (serde.cache_config_from_dict, serde.cache_config_to_dict),
+ "cache_info": (serde.cache_info_from_dict, serde.cache_info_to_dict),
+ "cache_page": (serde.cache_page_from_dict, serde.cache_page_to_dict),
+ "cached_prefix": (serde.cached_prefix_from_dict, serde.cached_prefix_to_dict),
+ "token_logprob": (serde.token_logprob_from_dict, serde.token_logprob_to_dict),
+ "continuation_state": (serde.continuation_from_dict, serde.continuation_to_dict),
+ "error_detail": (serde.error_detail_from_dict, serde.error_detail_to_dict),
+ "delta": (serde.delta_from_dict, serde.delta_to_dict),
+ "usage": (serde.usage_from_dict, serde.usage_to_dict),
+ "credential": (_credential_from_dict, _credential_to_dict),
+ "stream_event": (serde.stream_event_from_dict, serde.stream_event_to_dict),
+ "request": (serde.request_from_dict, serde.request_to_dict),
+ "response": (serde.response_from_dict, serde.response_to_dict),
+ "model_info": (serde.model_info_from_dict, serde.model_info_to_dict),
+ "batch_request": (serde.batch_request_from_dict, serde.batch_request_to_dict),
+ "batch_job": (serde.batch_job_from_dict, serde.batch_job_to_dict),
+ "batch_entry": (serde.batch_entry_from_dict, serde.batch_entry_to_dict),
+ "file_upload_request": (serde.file_upload_request_from_dict, serde.file_upload_request_to_dict),
+ "file_info": (serde.file_info_from_dict, serde.file_info_to_dict),
+ "file_page": (serde.file_page_from_dict, serde.file_page_to_dict),
+ "image_generation_request": (serde.image_generation_request_from_dict, serde.image_generation_request_to_dict),
+ "image_generation_response": (serde.image_generation_response_from_dict, serde.image_generation_response_to_dict),
+ "speech_generation_request": (serde.speech_generation_request_from_dict, serde.speech_generation_request_to_dict),
+ "speech_generation_response": (serde.speech_generation_response_from_dict, serde.speech_generation_response_to_dict),
+ "video_generation_request": (serde.video_generation_request_from_dict, serde.video_generation_request_to_dict),
+ "video_job": (serde.video_job_from_dict, serde.video_job_to_dict),
+ "audio_format": (serde.audio_format_from_dict, serde.audio_format_to_dict),
+ "live_config": (serde.live_config_from_dict, serde.live_config_to_dict),
+ "live_client_event": (serde.live_client_event_from_dict, serde.live_client_event_to_dict),
+ "live_server_event": (serde.live_server_event_from_dict, serde.live_server_event_to_dict),
+}
+
+
+def _serde_for_kind(kind: str) -> tuple[JsonToObj, ObjToJson]:
+ if kind not in KIND_SERDE:
+ raise ValueError(f"unknown kind: {kind}")
+ return KIND_SERDE[kind]
+
+
+# ─── Normalization helpers ───────────────────────────────────────────
+
+def normalize_transport_request(transport_req: Any) -> JsonObject:
+ """Normalize a TransportRequest into the protocol's build_request shape.
+
+ Mirrors conformance/cross_sdk/dump_request.py, except nothing is ever
+ redacted — the harness asserts exact auth formatting against the api_key
+ it injected.
+ """
+ parsed = urllib.parse.urlparse(transport_req.url)
+ params = dict(urllib.parse.parse_qsl(parsed.query, keep_blank_values=True))
+ url = urllib.parse.urlunparse((parsed.scheme, parsed.netloc, parsed.path, "", "", ""))
+
+ headers: JsonObject = {key.lower(): value for key, value in transport_req.headers}
+
+ out: JsonObject = {
+ "method": transport_req.method,
+ "url": url,
+ "params": params,
+ "headers": headers,
+ "body": None,
+ }
+
+ body = transport_req.body
+ if body:
+ content_type = headers.get("content-type", "")
+ if "json" in content_type.lower():
+ try:
+ out["body"] = json.loads(body.decode("utf-8"))
+ return out
+ except Exception:
+ pass
+ out["body_b64"] = base64.b64encode(body).decode("ascii")
+ return out
+
+
+def _http_response(status: int, body: bytes) -> HttpResponse:
+ return HttpResponse(
+ status=status,
+ reason="OK",
+ headers=[("content-type", "application/json")],
+ body=body,
+ )
+
+
+def _response_result(response: Response) -> JsonObject:
+ """Serialize a Response per the protocol, surfacing the unmapped canary."""
+ result: JsonObject = {"canonical_response": serde.response_to_dict(response)}
+ provider_data = response.provider_data if isinstance(response.provider_data, dict) else {}
+ unmapped = provider_data.get("_lm15_unmapped")
+ if unmapped is not None:
+ result["unmapped"] = list(unmapped)
+ return result
+
+
+def _parse_stream_body(lm: BaseProviderLM, request: Request, body: bytes) -> list[StreamEvent]:
+ def raw_events() -> Iterator[StreamEvent]:
+ for raw in parse_sse(iter(body.splitlines(keepends=True))):
+ for event in lm.parse_stream_events(request, raw):
+ if event is not None:
+ yield event
+
+ # MAP-3/MAP-4: the canonical event trace is the POST-coalesce trace —
+ # exactly one merged StreamEndEvent, final, and exactly one leading
+ # StreamStartEvent (synthesized with the request's model for dialects
+ # without a start frame).
+ return list(coalesce_stream(raw_events(), model=request.model))
+
+
+# ─── Ops ─────────────────────────────────────────────────────────────
+
+def op_capabilities(msg: JsonObject) -> JsonObject:
+ return {
+ "language": LANGUAGE,
+ "ops": sorted(HANDLERS),
+ "impl_version": IMPL_VERSION,
+ }
+
+
+def _base_url(msg: JsonObject) -> str | None:
+ base_url = msg.get("base_url")
+ return str(base_url) if base_url is not None else None
+
+
+def op_build_request(msg: JsonObject) -> JsonObject:
+ lm = _adapter(msg)
+ request = serde.request_from_dict(msg["canonical_request"])
+ transport_req = lm.build_request(request, stream=bool(msg.get("stream", False)))
+ return normalize_transport_request(transport_req)
+
+
+def op_ingest_openai_chat(msg: JsonObject) -> JsonObject:
+ """MAP-12: a Chat Completions request body → canonical Request, under the
+ compat the case's provider binds (the same adapter build_request uses).
+ Pure; no credential is read (PROTOCOL.md)."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ ingest = getattr(lm, "request_from_openai_chat", None)
+ if ingest is None:
+ raise ValueError(f"provider {msg['provider']!r} does not speak the Chat Completions wire; nothing to ingest")
+ return {"canonical_request": serde.request_to_dict(ingest(msg["body"]))}
+
+
+def op_parse_response(msg: JsonObject) -> JsonObject:
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ request = serde.request_from_dict(msg["canonical_request"])
+ body = base64.b64decode(msg["body_b64"])
+ response = lm.parse_response(request, _http_response(int(msg["status"]), body))
+ return _response_result(response)
+
+
+def op_replay_stream(msg: JsonObject) -> JsonObject:
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ request = serde.request_from_dict(msg["canonical_request"])
+ body = base64.b64decode(msg["body_b64"])
+ events = _parse_stream_body(lm, request, body)
+ event_dicts = [serde.stream_event_to_dict(e) for e in events]
+ try:
+ response = materialize_response(iter(events), request)
+ except StreamAssemblyError as exc:
+ # The trace parsed; assembly refused (MAP-9). Report the trace with
+ # the error so the golden pins both what arrived and the refusal.
+ raise _OpFailure(exc, {"events": event_dicts}) from exc
+ result: JsonObject = {"events": event_dicts}
+ result.update(_response_result(response))
+ return result
+
+
+def op_normalize_error(msg: JsonObject) -> JsonObject:
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ err = lm.normalize_error(int(msg["status"]), str(msg["body_text"]))
+ return {
+ "class": type(err).__name__,
+ "code": err.code or canonical_error_code(err),
+ "provider_code": err.provider_code,
+ "message": err.message,
+ }
+
+
+def op_serde_roundtrip(msg: JsonObject) -> JsonObject:
+ from_dict, to_dict = _serde_for_kind(str(msg["kind"]))
+ return {"value": to_dict(from_dict(msg["value"]))}
+
+
+def op_validate(msg: JsonObject) -> JsonObject:
+ from_dict, to_dict = _serde_for_kind(str(msg["kind"]))
+ obj = from_dict(msg["value"])
+ return {"ok": True, "normalized": to_dict(obj)}
+
+
+def op_resolve_model(msg: JsonObject) -> JsonObject:
+ """PROTOCOL.md resolve_model: the router's pure ``resolve`` over
+ harness-supplied inputs only — the env map (never the process env) and,
+ when given, an explicit catalog of canonical ModelInfo values."""
+ from .models import ModelRegistry
+ from .router import LMRouter, RouterConfig
+
+ env = {str(k): str(v) for k, v in (msg.get("env") or {}).items()}
+ registry = None
+ if "catalog" in msg:
+ registry = ModelRegistry()
+ for entry in msg["catalog"] or []:
+ registry.add(serde.model_info_from_dict(entry), replace=False)
+ resolution = LMRouter(RouterConfig(registry=registry, env=env)).resolve(str(msg["model"]))
+ return {"provider": resolution.provider, "model": resolution.model, "source": resolution.source}
+
+
+def op_build_models_request(msg: JsonObject) -> JsonObject:
+ lm = _adapter(msg)
+ return normalize_transport_request(lm._models_request())
+
+
+def op_parse_models_response(msg: JsonObject) -> JsonObject:
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ status = int(msg["status"])
+ if status >= 400:
+ raise lm.normalize_error(status, body)
+ models = lm._models_from_body(body)
+ return {"models": [serde.model_info_to_dict(m) for m in models]}
+
+
+def _headers_list(msg: JsonObject) -> list:
+ headers = msg.get("headers") or {}
+ return [(str(k), str(v)) for k, v in headers.items()]
+
+
+def op_generation_build(msg: JsonObject) -> JsonObject:
+ """Wire request for image_generate / speech_generate (kind discriminates)."""
+ lm = _adapter(msg)
+ kind = str(msg["kind"])
+ if kind == "image":
+ request = serde.image_generation_request_from_dict(msg["generation_request"])
+ return normalize_transport_request(lm._image_generate_request(request))
+ if kind == "speech":
+ request = serde.speech_generation_request_from_dict(msg["generation_request"])
+ return normalize_transport_request(lm._speech_generate_request(request))
+ raise ValueError(f"unknown generation kind: {kind}")
+
+
+def op_generation_parse(msg: JsonObject) -> JsonObject:
+ """Canonical generation response from a pinned wire body (+ headers:
+ OpenAI speech is raw bytes typed only by content-type)."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ kind = str(msg["kind"])
+ status = int(msg["status"])
+ body = base64.b64decode(msg["body_b64"])
+ if status >= 400:
+ raise lm.normalize_error(status, body.decode("utf-8", "replace"))
+ resp = HttpResponse(status=status, reason="OK", headers=_headers_list(msg), body=body)
+ if kind == "image":
+ request = serde.image_generation_request_from_dict(msg["generation_request"])
+ return serde.image_generation_response_to_dict(lm._image_generation_from_response(request, resp))
+ if kind == "speech":
+ request = serde.speech_generation_request_from_dict(msg["generation_request"])
+ return serde.speech_generation_response_to_dict(lm._speech_generation_from_response(request, resp))
+ raise ValueError(f"unknown generation kind: {kind}")
+
+
+def op_file_op_build(msg: JsonObject) -> JsonObject:
+ """Wire request for one files-lifecycle operation (file_op discriminates)."""
+ lm = _adapter(msg)
+ op = str(msg["file_op"])
+ if op == "upload":
+ request = serde.file_upload_request_from_dict(msg["upload_request"])
+ return normalize_transport_request(lm._file_upload_request(request))
+ if op == "get":
+ return normalize_transport_request(lm._file_get_request(str(msg["file_id"])))
+ if op == "list":
+ cursor = msg.get("cursor")
+ return normalize_transport_request(lm._file_list_request(int(msg.get("limit", 20)), cursor))
+ if op == "delete":
+ return normalize_transport_request(lm._file_delete_request(str(msg["file_id"])))
+ if op == "download":
+ return normalize_transport_request(lm._file_download_request(str(msg["file_id"])))
+ raise ValueError(f"unknown file_op: {op}")
+
+
+def op_file_op_parse(msg: JsonObject) -> JsonObject:
+ """Canonical FileInfo / FilePage from a pinned wire body (kind discriminates)."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ kind = str(msg["kind"])
+ status = int(msg["status"])
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ if status >= 400:
+ raise lm.normalize_error(status, body)
+ if kind == "info":
+ return {"file": serde.file_info_to_dict(lm._file_info_from_body(body))}
+ if kind == "page":
+ return {"page": serde.file_page_to_dict(lm._file_page_from_list_body(body))}
+ raise ValueError(f"unknown file parse kind: {kind}")
+
+
+def op_cache_op_build(msg: JsonObject) -> JsonObject:
+ """Wire request for one cache-resource operation (cache_op discriminates)."""
+ lm = _adapter(msg)
+ op = str(msg["cache_op"])
+ if op == "create":
+ prefix = serde.request_from_dict(msg["prefix_request"])
+ lm._check_cache_prefix(prefix, msg.get("ttl_seconds"))
+ return normalize_transport_request(lm._cache_create_request(prefix, msg.get("ttl_seconds"), msg.get("label")))
+ if op == "get":
+ return normalize_transport_request(lm._cache_get_request(str(msg["cache_id"])))
+ if op == "list":
+ return normalize_transport_request(lm._cache_list_request(int(msg.get("limit", 20)), msg.get("cursor")))
+ if op == "delete":
+ return normalize_transport_request(lm._cache_delete_request(str(msg["cache_id"])))
+ if op == "update":
+ return normalize_transport_request(lm._cache_update_request(str(msg["cache_id"]), int(msg["ttl_seconds"])))
+ raise ValueError(f"unknown cache_op: {op}")
+
+
+def op_cache_op_parse(msg: JsonObject) -> JsonObject:
+ """Canonical CacheInfo / CachePage from a pinned wire body (kind discriminates)."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ kind = str(msg["kind"])
+ status = int(msg["status"])
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ if status >= 400:
+ raise lm.normalize_error(status, body)
+ if kind == "info":
+ return {"cache": serde.cache_info_to_dict(lm._cache_info_from_body(body))}
+ if kind == "page":
+ return {"page": serde.cache_page_to_dict(lm._cache_page_from_list_body(body))}
+ raise ValueError(f"unknown cache parse kind: {kind}")
+
+
+def op_video_op_build(msg: JsonObject) -> JsonObject:
+ """Wire request(s) for one video-job operation (action discriminates).
+
+ Always returns {"requests": [...]}: result_fetch may be zero requests
+ (xAI's terminal body carries a public URL) or one (Sora content, Veo's
+ key-bound file URI).
+ """
+ lm = _adapter(msg)
+ action = str(msg["action"])
+ if action == "submit":
+ request = serde.video_generation_request_from_dict(msg["video_request"])
+ return {"requests": [normalize_transport_request(lm._video_submit_request(request))]}
+ if action == "status":
+ return {"requests": [normalize_transport_request(lm._video_status_request(str(msg["video_id"])))]}
+ if action == "result_fetch":
+ fetch = lm._video_result_fetch(msg["status_body"])
+ return {"requests": [] if fetch is None else [normalize_transport_request(fetch)]}
+ if action == "list":
+ return {"requests": [normalize_transport_request(lm._video_list_request(int(msg.get("limit", 20)), msg.get("model")))]}
+ raise ValueError(f"unknown video action: {action}")
+
+
+def op_video_op_parse(msg: JsonObject) -> JsonObject:
+ """Canonical video snapshots / parts from pinned wire bodies."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ kind = str(msg["kind"])
+ if kind == "job":
+ status = int(msg["status"])
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ if status >= 400:
+ raise lm.normalize_error(status, body)
+ return {"job": serde.video_job_to_dict(lm._video_job_from_body(body, msg.get("video_id")))}
+ if kind == "list":
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ return {"jobs": [serde.video_job_to_dict(j) for j in lm._video_jobs_from_list_body(body)]}
+ if kind == "part":
+ fetched = None
+ if msg.get("fetched_b64") is not None:
+ fetched = HttpResponse(
+ status=200, reason="OK", headers=_headers_list(msg),
+ body=base64.b64decode(msg["fetched_b64"]),
+ )
+ return {"part": serde.part_to_dict(lm._video_part(msg["status_body"], fetched))}
+ raise ValueError(f"unknown video parse kind: {kind}")
+
+
+def op_batch_op_build(msg: JsonObject) -> JsonObject:
+ """Wire request(s) for one batch operation (action discriminates).
+
+ Always returns {"requests": [...]}: upload may be zero requests
+ (single-step providers), result_fetches may be several (OpenAI's
+ output and error files).
+ """
+ lm = _adapter(msg)
+ action = str(msg["action"])
+ if action == "upload":
+ request = serde.batch_request_from_dict(msg["batch_request"])
+ upload = lm._batch_upload_request(request)
+ return {"requests": [] if upload is None else [normalize_transport_request(upload)]}
+ if action == "submit":
+ request = serde.batch_request_from_dict(msg["batch_request"])
+ upload_body = msg.get("upload_body")
+ return {"requests": [normalize_transport_request(lm._batch_submit_request(request, upload_body))]}
+ if action == "status":
+ return {"requests": [normalize_transport_request(lm._batch_status_request(str(msg["batch_id"])))]}
+ if action == "cancel":
+ return {"requests": [normalize_transport_request(lm._batch_cancel_request(str(msg["batch_id"])))]}
+ if action == "list":
+ return {"requests": [normalize_transport_request(lm._batch_list_request(int(msg.get("limit", 20))))]}
+ if action == "result_fetches":
+ fetches = lm._batch_result_fetches(msg["status_body"])
+ return {"requests": [normalize_transport_request(f) for f in fetches]}
+ raise ValueError(f"unknown batch action: {action}")
+
+
+def op_batch_op_parse(msg: JsonObject) -> JsonObject:
+ """Canonical batch snapshots from pinned wire bodies (kind discriminates)."""
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ kind = str(msg["kind"])
+ if kind == "job":
+ status = int(msg["status"])
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ if status >= 400:
+ raise lm.normalize_error(status, body)
+ return {"job": serde.batch_job_to_dict(lm._batch_job_from_body(body))}
+ if kind == "list":
+ body = base64.b64decode(msg["body_b64"]).decode("utf-8")
+ return {"jobs": [serde.batch_job_to_dict(j) for j in lm._batch_jobs_from_list_body(body)]}
+ if kind == "entries":
+ fetched = tuple(base64.b64decode(b).decode("utf-8") for b in msg.get("fetched_b64", []))
+ entries = lm._batch_entries(msg["status_body"], fetched)
+ return {"entries": [serde.batch_entry_to_dict(e) for e in entries]}
+ raise ValueError(f"unknown batch parse kind: {kind}")
+
+
+def op_replay_live(msg: JsonObject) -> JsonObject:
+ """Live transcript replay: the pure websocket codec, no socket.
+
+ Three transformations per case, all driven by the recorded transcript:
+ setup frames from the LiveConfig, wire frames from each canonical
+ client event, and canonical server events from each verbatim recorded
+ server frame (empty list = housekeeping frame, deliberately ignored).
+ The harness performs all comparison; session mechanics (locking,
+ queues, iteration sugar) are per-language and stay out of scope.
+ """
+ lm = adapter_for_provider(str(msg["provider"]), _PARSE_ONLY_KEY, _base_url(msg), settings=_settings_of(msg), clock=_clock_of(msg))
+ config = serde.live_config_from_dict(msg["live_config"])
+ encoder = lm._live_encoder(config)
+ client_frames = [
+ encoder(serde.live_client_event_from_dict(event))
+ for event in msg.get("client_events", [])
+ ]
+ events = []
+ for frame_b64 in msg.get("server_frames_b64", []):
+ raw = base64.b64decode(frame_b64)
+ events.append([serde.live_server_event_to_dict(e) for e in lm._decode_live_server_event(raw)])
+ return {
+ "setup_frames": lm._live_setup_frames(config),
+ "client_frames": client_frames,
+ "events": events,
+ }
+
+
+def op_explain_auth(msg: JsonObject) -> JsonObject:
+ """AUTH-7 resolution chain over harness-supplied inputs only.
+
+ The harness owns every input: ``env`` (always passed, even empty, so the
+ real process environment never leaks in), ``api_keys_providers`` planted
+ with the fixture sentinel, and ``credentials_path`` pointing at a
+ harness-materialized borrowed file. ``report_text`` carries every human
+ rendering so the harness can enforce AUTH-5 (sentinel absence) itself.
+ """
+ from .doctor import explain_auth
+
+ provider = str(msg["provider"])
+ sentinel = str(msg["sentinel"])
+ kwargs: dict[str, Any] = {"env": {str(k): str(v) for k, v in (msg.get("env") or {}).items()}}
+ providers = msg.get("api_keys_providers") or []
+ if providers:
+ kwargs["api_keys"] = {str(p): sentinel for p in providers}
+ files = msg.get("files")
+ if isinstance(files, dict):
+ kwargs["files"] = {str(k): str(v) for k, v in files.items()}
+ if kwargs["env"].get("HOME"):
+ kwargs["home"] = kwargs["env"]["HOME"]
+ if isinstance(msg.get("settings"), dict):
+ kwargs["settings"] = {str(k): str(v) for k, v in msg["settings"].items()}
+ credentials_path = msg.get("credentials_path")
+ if credentials_path is not None:
+ if provider == "claude-code":
+ kwargs["claude_credentials_path"] = str(credentials_path)
+ elif provider == "xai":
+ kwargs["xai_credentials_path"] = str(credentials_path)
+ else:
+ kwargs["codex_auth_path"] = str(credentials_path)
+
+ report = explain_auth(provider, **kwargs)
+ return {
+ "configured": report.configured,
+ "steps": [{"kind": step.kind, "state": step.state} for step in report.steps],
+ "report_text": "\n".join((report.describe(), repr(report), str(report))),
+ }
+
+
+def op_token_exchange_build(msg: JsonObject) -> JsonObject:
+ """PROTOCOL.md token_exchange_build: the exact token-exchange request a
+ chain rung sends under the fixed clock (auth/token-vectors.json)."""
+ from .cloud.chains import ChainContext, token_exchange_build
+ from .credentials import parse_rfc3339
+ from .registry import lookup
+
+ definition = lookup(str(msg["provider"]))
+ if definition is None:
+ raise ValueError(f"unknown provider: {msg['provider']}")
+ inputs = dict(msg.get("input") or msg.get("credential") or {})
+ env = {str(k): str(v) for k, v in (inputs.get("env") or {}).items()}
+ files: dict[str, str] = {}
+ if inputs.get("certificate_pem") and env.get("AZURE_CLIENT_CERTIFICATE_PATH"):
+ # The harness gives the certificate and the key separately; the
+ # environment rung reads one PEM file carrying both.
+ files[env["AZURE_CLIENT_CERTIFICATE_PATH"]] = str(inputs["certificate_pem"]) + "\n" + str(inputs.get("private_key_pem") or "")
+ fixed = parse_rfc3339(str(msg["now"]))
+ ctx = ChainContext(env=env, files=files or None, now=lambda: fixed,
+ settings={str(k): str(v) for k, v in (inputs.get("settings") or msg.get("settings") or {}).items()})
+ return token_exchange_build(definition.access, str(msg["rung"]), inputs, ctx)
+
+
+def op_token_exchange_parse(msg: JsonObject) -> JsonObject:
+ from .cloud.chains import ChainContext, token_exchange_parse
+ from .credentials import credential_to_dict, parse_rfc3339
+ from .registry import lookup
+
+ definition = lookup(str(msg["provider"]))
+ if definition is None:
+ raise ValueError(f"unknown provider: {msg['provider']}")
+ fixed = parse_rfc3339(str(msg["now"]))
+ body = msg.get("body")
+ if body is None and msg.get("body_b64") is not None:
+ body = json.loads(base64.b64decode(str(msg["body_b64"])))
+ ctx = ChainContext(env={}, now=lambda: fixed)
+ try:
+ credential = token_exchange_parse(definition.access, str(msg["rung"]), int(msg.get("status", 200)), dict(body or {}), ctx)
+ except LM15Error as exc:
+ return {"ok": False, "error": {"class": type(exc).__name__, "code": getattr(exc, "code", None)}}
+ return {"ok": True, "credential": credential_to_dict(credential)}
+
+
+def op_sigv4_sign(msg: JsonObject) -> JsonObject:
+ """PROTOCOL.md sigv4_sign: the AWS test-suite vectors (auth/sigv4-vectors.json)."""
+ from .cloud import sigv4
+ from .credentials import credential_from_dict, parse_rfc3339
+
+ credential = credential_from_dict(msg["credential"])
+ req = msg["request"]
+ headers = {str(k): (v if isinstance(v, str) else ",".join(v)) for k, v in dict(req.get("headers") or {}).items()
+ if str(k).lower() not in ("host", "x-amz-date", "x-amz-security-token")}
+ signature = sigv4.sign(method=str(req["method"]), url=str(req["url"]), headers=headers,
+ payload=str(req.get("body") or "").encode("utf-8"), credentials=credential,
+ region=str(msg["region"]), service=str(msg["service"]), now=parse_rfc3339(str(msg["now"])))
+ return {"canonical_request": signature.canonical_request, "string_to_sign": signature.string_to_sign,
+ "authorization": signature.authorization, "headers": signature.headers}
+
+
+def op_surface_dump(msg: JsonObject) -> JsonObject:
+ return {
+ "types": _reflect_types(),
+ "enums": _reflect_enums(),
+ "providers": _reflect_providers(),
+ }
+
+
+def _reflect_providers() -> JsonObject:
+ """Every registered provider's access policy: who supports what, by reflection.
+
+ This is the support matrix the contract pins (spec/support-matrix.json):
+ a port that silently disagrees about endpoint support fails the audit,
+ not a user at runtime.
+ """
+ from .registry import PROVIDERS
+
+ out: JsonObject = {}
+ for provider in sorted(PROVIDERS):
+ manifest = PROVIDERS[provider].access
+ supports = manifest.supports
+ out[provider] = {
+ "supports": {
+ f.name: sorted(getattr(supports, f.name)) if f.name == "extra" else getattr(supports, f.name)
+ for f in dataclasses.fields(supports)
+ },
+ "auth_modes": list(manifest.auth_modes),
+ "env_keys": list(manifest.env_keys),
+ }
+ return out
+
+
+def _reflect_types() -> JsonObject:
+ """Every public dataclass in lm15.types, by reflection."""
+ out: JsonObject = {}
+ for name in sorted(vars(lm15_types)):
+ obj = getattr(lm15_types, name)
+ if name.startswith("_") or not isinstance(obj, type):
+ continue
+ if obj.__module__ != lm15_types.__name__ or not dataclasses.is_dataclass(obj):
+ continue
+ out[obj.__name__] = {"fields": [f.name for f in dataclasses.fields(obj)]}
+ return out
+
+
+def _reflect_enums() -> JsonObject:
+ """Every string vocabulary in lm15.types, by reflection.
+
+ Harvests Literal type aliases (Role, FinishReason, …) and module-level
+ string collections (FINISH_REASONS, PART_TYPES, …) — never a
+ hand-maintained list. Unordered collections are sorted; Literal aliases
+ keep declaration order.
+ """
+ from . import credentials as lm15_credentials
+ from . import features as lm15_features
+
+ out: JsonObject = {}
+ # lm15.types, plus the auth vocabularies (spec/vocabularies.md AuthScheme,
+ # CredentialKind, CredentialPolicy, StreamFraming, ModelPlacement; 2026-09-03).
+ for module in (lm15_types, lm15_features, lm15_credentials):
+ for name in sorted(vars(module)):
+ if name.startswith("_") or name in ("AuthHeader",):
+ continue
+ vocabulary = _string_vocabulary(getattr(module, name))
+ if vocabulary:
+ out[name] = vocabulary
+ return out
+
+
+def _string_vocabulary(obj: Any) -> list[str] | None:
+ if get_origin(obj) is Literal:
+ args = get_args(obj)
+ if args and all(isinstance(a, str) for a in args):
+ return list(args)
+ return None
+ if isinstance(obj, (frozenset, set)):
+ if obj and all(isinstance(v, str) for v in obj):
+ return sorted(obj)
+ return None
+ if isinstance(obj, dict):
+ if obj and all(isinstance(k, str) for k in obj) and all(isinstance(v, type) for v in obj.values()):
+ return sorted(obj)
+ return None
+ if isinstance(obj, (tuple, list)):
+ if obj and all(isinstance(v, str) for v in obj):
+ return sorted(obj)
+ return None
+ return None
+
+
+# ─── Framing ─────────────────────────────────────────────────────────
+
+HANDLERS: dict[str, Callable[[JsonObject], JsonObject]] = {
+ "capabilities": op_capabilities,
+ "build_request": op_build_request,
+ "ingest_openai_chat": op_ingest_openai_chat,
+ "parse_response": op_parse_response,
+ "replay_stream": op_replay_stream,
+ "normalize_error": op_normalize_error,
+ "serde_roundtrip": op_serde_roundtrip,
+ "validate": op_validate,
+ "surface_dump": op_surface_dump,
+ "explain_auth": op_explain_auth,
+ "resolve_model": op_resolve_model,
+ "token_exchange_build": op_token_exchange_build,
+ "token_exchange_parse": op_token_exchange_parse,
+ "sigv4_sign": op_sigv4_sign,
+ "build_models_request": op_build_models_request,
+ "parse_models_response": op_parse_models_response,
+ "replay_live": op_replay_live,
+ "generation_build": op_generation_build,
+ "generation_parse": op_generation_parse,
+ "file_op_build": op_file_op_build,
+ "file_op_parse": op_file_op_parse,
+ "video_op_build": op_video_op_build,
+ "video_op_parse": op_video_op_parse,
+ "batch_op_build": op_batch_op_build,
+ "batch_op_parse": op_batch_op_parse,
+ "cache_op_build": op_cache_op_build,
+ "cache_op_parse": op_cache_op_parse,
+}
+
+
+class _OpFailure(Exception):
+ """An op failed with a typed error plus extra fields for the error reply."""
+
+ def __init__(self, cause: BaseException, extra: JsonObject) -> None:
+ super().__init__(str(cause))
+ self.cause = cause
+ self.extra = extra
+
+
+def _error_reply(req_id: Any, exc: BaseException) -> JsonObject:
+ # lm15-typed errors report the canonical class name and ErrorCode;
+ # unexpected exceptions report the native exception name. A
+ # StreamAssemblyError also carries the partial Response it salvaged
+ # (MAP-9), so a golden can pin a raise and what survived it.
+ extra: JsonObject = {}
+ if isinstance(exc, _OpFailure):
+ extra = exc.extra
+ exc = exc.cause
+ error: JsonObject = {"type": type(exc).__name__, "message": str(exc)}
+ if isinstance(exc, LM15Error) and exc.code is not None:
+ error["code"] = exc.code
+ if isinstance(exc, StreamAssemblyError) and exc.partial is not None:
+ error["partial_response"] = _response_result(exc.partial)["canonical_response"]
+ if isinstance(exc, (UnknownModelError, AmbiguousModelError)):
+ # The payload spec/vocabularies.md pins for the router codes.
+ error["model"] = exc.model
+ if isinstance(exc, AmbiguousModelError):
+ error["providers"] = list(exc.providers)
+ error.update(extra)
+ return {"id": req_id, "ok": False, "error": error}
+
+
+def handle_line(line: str) -> JsonObject:
+ try:
+ msg = json.loads(line)
+ except Exception as exc:
+ return _error_reply(None, exc)
+
+ if not isinstance(msg, dict):
+ return _error_reply(None, ValueError("request must be a JSON object"))
+
+ req_id = msg.get("id")
+ try:
+ op = msg.get("op")
+ handler = HANDLERS.get(str(op))
+ if handler is None:
+ raise ValueError(f"unknown op: {op}")
+ result = handler(msg)
+ except Exception as exc:
+ return _error_reply(req_id, exc)
+ return {"id": req_id, "ok": True, "result": result}
+
+
+def main(argv: list[str] | None = None) -> int:
+ for line in sys.stdin:
+ if not line.strip():
+ continue
+ reply = handle_line(line)
+ sys.stdout.write(json.dumps(reply, separators=(",", ":")) + "\n")
+ sys.stdout.flush()
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/dspy/_vendor/lm15/video_jobs.py b/dspy/_vendor/lm15/video_jobs.py
new file mode 100644
index 000000000..4e7dba909
--- /dev/null
+++ b/dspy/_vendor/lm15/video_jobs.py
@@ -0,0 +1,134 @@
+"""
+lm15.video_jobs — the VideoJob handle (ticket ergonomics over the pure ops).
+
+A video job is a ticket, exactly like a batch job: the provider cooks,
+``job.id`` is the ticket number, and the id is a plain string you can
+store anywhere. On xAI it is the ONLY copy — the wire has no list
+endpoint — so the primary pattern is store-the-id and re-attach.
+
+The handle is per-language sugar over four pure operations
+(``video_submit`` / ``video_status`` / ``video_result`` /
+``video_list``); ports implement the ops, the handle idiom is theirs.
+
+``refresh()`` / ``wait()`` update the handle's snapshot in place and
+return the handle — the batch precedent (a mutating refresh avoids the
+forgot-to-reassign-stale-status bug).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING
+
+from .types import VideoJobInfo, VideoPart, VideoStatus
+
+if TYPE_CHECKING: # pragma: no cover - annotations only
+ from .providers.async_base import AsyncBaseProviderLM
+ from .providers.base import BaseProviderLM
+
+__all__ = ["AsyncVideoJob", "VideoJob"]
+
+_DEFAULT_POLL_SECONDS = 5.0 # video jobs finish in seconds-to-minutes, not hours
+
+
+class VideoJob:
+ """A live handle on one provider-side video job."""
+
+ def __init__(self, lm: "BaseProviderLM", info: VideoJobInfo) -> None:
+ self._lm = lm
+ self._info = info
+
+ # ─── Snapshot access ─────────────────────────────────────────────
+
+ @property
+ def info(self) -> VideoJobInfo:
+ """The frozen snapshot from the last provider contact."""
+ return self._info
+
+ @property
+ def id(self) -> str:
+ return self._info.id
+
+ @property
+ def status(self) -> VideoStatus:
+ return self._info.status
+
+ @property
+ def progress(self) -> int | None:
+ return self._info.progress
+
+ def __repr__(self) -> str:
+ return f"VideoJob(id={self._info.id!r}, status={self._info.status!r}, progress={self._info.progress!r})"
+
+ # ─── Operations ──────────────────────────────────────────────────
+
+ def refresh(self) -> "VideoJob":
+ self._info = self._lm.video_status(self._info.id)
+ return self
+
+ def wait(self, poll_every: float = _DEFAULT_POLL_SECONDS, timeout: float | None = None) -> "VideoJob":
+ """Poll until the job is terminal; returns the handle (check
+ ``status`` — ``failed`` returns, it does not raise, mirroring
+ batch's entry-level honesty)."""
+ deadline = None if timeout is None else time.monotonic() + timeout
+ while True:
+ if self._info.done:
+ return self
+ if deadline is not None and time.monotonic() >= deadline:
+ raise TimeoutError(
+ f"video {self._info.id} still {self._info.status!r} after {timeout}s"
+ )
+ time.sleep(poll_every)
+ self.refresh()
+
+ def result(self) -> VideoPart:
+ """The finished video as a VideoPart (URL- or bytes-addressed,
+ the provider's own delivery mode)."""
+ return self._lm.video_result(self._info.id)
+
+
+class AsyncVideoJob:
+ """Async mirror of :class:`VideoJob`."""
+
+ def __init__(self, lm: "AsyncBaseProviderLM", info: VideoJobInfo) -> None:
+ self._lm = lm
+ self._info = info
+
+ @property
+ def info(self) -> VideoJobInfo:
+ return self._info
+
+ @property
+ def id(self) -> str:
+ return self._info.id
+
+ @property
+ def status(self) -> VideoStatus:
+ return self._info.status
+
+ @property
+ def progress(self) -> int | None:
+ return self._info.progress
+
+ def __repr__(self) -> str:
+ return f"AsyncVideoJob(id={self._info.id!r}, status={self._info.status!r}, progress={self._info.progress!r})"
+
+ async def refresh(self) -> "AsyncVideoJob":
+ self._info = await self._lm.video_status(self._info.id)
+ return self
+
+ async def wait(self, poll_every: float = _DEFAULT_POLL_SECONDS, timeout: float | None = None) -> "AsyncVideoJob":
+ deadline = None if timeout is None else time.monotonic() + timeout
+ while True:
+ if self._info.done:
+ return self
+ if deadline is not None and time.monotonic() >= deadline:
+ raise TimeoutError(
+ f"video {self._info.id} still {self._info.status!r} after {timeout}s"
+ )
+ await asyncio.sleep(poll_every)
+ await self.refresh()
+
+ async def result(self) -> VideoPart:
+ return await self._lm.video_result(self._info.id)
diff --git a/dspy/lm15.py b/dspy/lm15.py
new file mode 100644
index 000000000..64e92473f
--- /dev/null
+++ b/dspy/lm15.py
@@ -0,0 +1,15 @@
+"""Use the lm15 types and providers bundled with DSPy.
+
+Import public names here rather than from DSPy's private vendor directory.
+These are the original lm15 objects, not copies or subclasses. Bundling them
+alone does not change how `dspy.LM` makes requests.
+
+Examples:
+ >>> from dspy.lm15 import Message, Request
+ >>> request = Request(model="example", messages=(Message.user("Hello"),))
+ >>> request.model
+ 'example'
+"""
+
+from dspy._vendor.lm15 import *
+from dspy._vendor.lm15 import __all__ as __all__
diff --git a/pyproject.toml b/pyproject.toml
index a3b8ac522..7f36c054c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -78,6 +78,8 @@ exclude = ["tests", "tests.*"]
[tool.setuptools.package-data]
dspy = ["primitives/*.js"]
+"dspy._vendor" = ["lm15-LICENSE", "lm15-provenance.txt", "UPDATING.md"]
+"dspy._vendor.lm15" = ["py.typed"]
[project.urls]
homepage = "https://github.com/stanfordnlp/dspy"
@@ -125,6 +127,7 @@ filterwarnings = [
include = ["dspy/**/*.py", "tests/**/*.py"]
exclude = [
"dspy/__metadata__.py",
+ "dspy/_vendor/**", # vendored lm15, linted in its own repository
"tests/reliability/*.py",
]
diff --git a/scripts/update_vendored_lm15.py b/scripts/update_vendored_lm15.py
new file mode 100644
index 000000000..cdbdb9a40
--- /dev/null
+++ b/scripts/update_vendored_lm15.py
@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""Import/update lm15 using a package-only, squashed Git subtree.
+
+Run from any directory: python scripts/update_vendored_lm15.py [REF]
+Defaults to main from cmpnd-ai/lm15-python. Requires a clean checkout and
+creates local commits, but never pushes. --source overrides the source URL.
+"""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import subprocess
+import tempfile
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PREFIX = "dspy/_vendor/lm15"
+DEFAULT_SOURCE = "https://github.com/cmpnd-ai/lm15-python.git"
+RECORD = REPO_ROOT / "dspy/_vendor/lm15-provenance.txt"
+LICENSE = REPO_ROOT / "dspy/_vendor/lm15-LICENSE"
+
+
+def git(*args: str, cwd: Path = REPO_ROOT) -> str:
+ return subprocess.run(
+ ["git", *args], cwd=cwd, check=True, text=True, stdout=subprocess.PIPE
+ ).stdout.strip()
+
+
+def main() -> int:
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("ref", nargs="?", default="main")
+ parser.add_argument("--source", default=DEFAULT_SOURCE)
+ args = parser.parse_args()
+ if git("status", "--porcelain", "--untracked-files=all"):
+ parser.error("Commit or stash all changes first. This command creates local commits.")
+ git("symbolic-ref", "--quiet", "HEAD")
+ git("var", "GIT_AUTHOR_IDENT")
+ git("var", "GIT_COMMITTER_IDENT")
+ before = git("rev-parse", "HEAD")
+
+ # Full history is necessary: split commit identities must remain stable
+ # between updates so subtree merge can find its previous imported ancestor.
+ with tempfile.TemporaryDirectory(prefix="dspy-lm15-") as tmp:
+ checkout = Path(tmp) / "source"
+ git("clone", "--no-checkout", args.source, str(checkout))
+ git("fetch", "origin", args.ref, cwd=checkout)
+ source_commit = git("rev-parse", "FETCH_HEAD", cwd=checkout)
+ git("checkout", "--detach", source_commit, cwd=checkout)
+ contract = git("show", f"{source_commit}:CONTRACT_PIN", cwd=checkout)
+ version_source = ast.parse(git("show", f"{source_commit}:lm15/_version.py", cwd=checkout))
+ version = next(
+ ast.literal_eval(node.value)
+ for node in version_source.body
+ if isinstance(node, ast.Assign)
+ and any(isinstance(target, ast.Name) and target.id == "__version__" for target in node.targets)
+ )
+ if not isinstance(version, str) or not version or "\n" in version:
+ parser.error("Source package must declare a nonempty, single-line version string.")
+ license_text = git("show", f"{source_commit}:LICENSE", cwd=checkout)
+ git("cat-file", "-e", f"{source_commit}:lm15/__init__.py", cwd=checkout)
+ split = git("subtree", "split", "--prefix=lm15", source_commit, cwd=checkout)
+ git("fetch", str(checkout), split)
+
+ initialized = RECORD.exists()
+ if initialized:
+ fields = dict(
+ line.split("=", 1) for line in RECORD.read_text().splitlines() if "=" in line
+ )
+ # A GitHub squash can remove every subtree parent and trailer.
+ # Recover the old package from its source pin, not DSPy's history.
+ for key in ("commit", "split"):
+ value = fields.get(key, "")
+ if len(value) != 40 or any(char not in "0123456789abcdef" for char in value):
+ parser.error(f"Invalid {key} in {RECORD.name}; refusing to update.")
+ git("fetch", "origin", fields["commit"], cwd=checkout)
+ old_split = git("subtree", "split", "--prefix=lm15", fields["commit"], cwd=checkout)
+ if old_split != fields["split"]:
+ parser.error("Recorded split does not match the pinned source; refusing to update.")
+ git("fetch", str(checkout), old_split)
+ old_tree = git("rev-parse", f"{old_split}^{{tree}}")
+ if git("rev-parse", f"HEAD:{PREFIX}") != old_tree:
+ parser.error("Vendored files differ from the recorded source; move edits upstream first.")
+ if (fields.get("split"), fields.get("commit"), fields.get("version"), fields.get("contract")) == (
+ split, source_commit, version, contract
+ ):
+ print("lm15 is already at this source commit.")
+ return 0
+ elif (REPO_ROOT / PREFIX).exists():
+ if git("ls-files", "--", PREFIX):
+ if not (REPO_ROOT / PREFIX / "VENDORED").exists():
+ parser.error("Existing package has no legacy VENDORED record; refusing to replace it.")
+ git("rm", "-r", PREFIX)
+ git("commit", "-m", "Remove copied lm15 before establishing its subtree")
+ # Git leaves ignored files (such as bytecode) behind. Preserve them
+ # outside the prefix, which subtree add requires to be absent.
+ if (REPO_ROOT / PREFIX).exists():
+ backup = Path(tempfile.mkdtemp(prefix="dspy-lm15-leftovers-")) / "lm15"
+ (REPO_ROOT / PREFIX).rename(backup)
+ print(f"Preserved untracked package leftovers at {backup}")
+
+ message = (
+ f"{'Update' if initialized else 'Vendor'} lm15 package subtree\n\n"
+ f"Source: {args.source}\nPython commit: {source_commit}\n"
+ f"Contract: {contract}\nPackage split: {split}"
+ )
+ try:
+ if initialized:
+ # Reconstruct a genuine package-root squash parent. A metadata-
+ # only commit with DSPy's root tree would be the wrong merge base.
+ anchor = git(
+ "commit-tree", old_tree, "-m",
+ f"Restore lm15 subtree base from source pin\n\n"
+ f"git-subtree-dir: {PREFIX}\ngit-subtree-split: {old_split}",
+ )
+ mainline = git("rev-parse", "HEAD")
+ git(
+ "merge", "--strategy=ours", "--no-ff", "--allow-unrelated-histories",
+ "-m", f"Reconnect lm15 subtree history without changing files\n\n"
+ f"git-subtree-dir: {PREFIX}\ngit-subtree-mainline: {mainline}\n"
+ f"git-subtree-split: {old_split}", anchor,
+ )
+ git("subtree", "merge" if initialized else "add", f"--prefix={PREFIX}",
+ "--squash", "-m", message, split)
+ RECORD.write_text(
+ f"source={args.source}\nversion={version}\ncommit={source_commit}\ncontract={contract}\nsplit={split}\n"
+ )
+ LICENSE.write_text(license_text + "\n")
+ git("add", str(RECORD), str(LICENSE))
+ if git("diff", "--cached", "--name-only"):
+ git("commit", "-m", f"Record lm15 source and contract for {source_commit[:12]}")
+ except subprocess.CalledProcessError:
+ print(f"Update stopped. Inspect git status before continuing. Previous HEAD: {before}")
+ raise
+ print(f"Imported lm15 {source_commit} (contract {contract}). Local commits only; review before pushing.")
+ return 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/tests/test_lm15_subtree_updater.py b/tests/test_lm15_subtree_updater.py
new file mode 100644
index 000000000..88c19fa80
--- /dev/null
+++ b/tests/test_lm15_subtree_updater.py
@@ -0,0 +1,120 @@
+"""Exercise subtree operations using local repositories, without network access."""
+
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPT = Path(__file__).resolve().parents[1] / "scripts/update_vendored_lm15.py"
+
+
+def run(cwd, *args, check=True):
+ return subprocess.run(args, cwd=cwd, check=check, capture_output=True, text=True, timeout=90)
+
+
+def git(cwd, *args):
+ return run(cwd, "git", *args).stdout.strip()
+
+
+def initialize(path):
+ path.mkdir()
+ git(path, "init", "-b", "main")
+ git(path, "config", "user.name", "Subtree test")
+ git(path, "config", "user.email", "[email protected]")
+
+
+def commit(path):
+ git(path, "add", ".")
+ git(path, "commit", "-m", "Test snapshot")
+ return git(path, "rev-parse", "HEAD")
+
+
[email protected]("merge_style", ["merge", "squash", "squash-with-trailers"])
+def test_pinned_import_update_and_noop(tmp_path, monkeypatch, merge_style):
+ # Tests create commits in disposable repositories only. Disable inherited
+ # signing/hooks and identity overrides from developer or CI configuration.
+ for key in list(os.environ):
+ if key.startswith(("GIT_", "PRE_COMMIT_")):
+ monkeypatch.delenv(key)
+ monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
+ monkeypatch.setenv("GIT_CONFIG_GLOBAL", os.devnull)
+ monkeypatch.setenv("GIT_AUTHOR_NAME", "Subtree test")
+ monkeypatch.setenv("GIT_AUTHOR_EMAIL", "[email protected]")
+ monkeypatch.setenv("GIT_COMMITTER_NAME", "Subtree test")
+ monkeypatch.setenv("GIT_COMMITTER_EMAIL", "[email protected]")
+
+ source, target = tmp_path / "source", tmp_path / "target"
+ initialize(source)
+ initialize(target)
+ (source / "lm15").mkdir()
+ (source / "lm15/__init__.py").write_text('SNAPSHOT = "old"\n')
+ (source / "lm15/_version.py").write_text('__version__ = "1.0.0a1"\n')
+ (source / "LICENSE").write_text("MIT test license\n")
+ (source / "CONTRACT_PIN").write_text("1" * 40 + "\n")
+ old = commit(source)
+ (source / "lm15/__init__.py").write_text('SNAPSHOT = "new"\n')
+ (source / "CONTRACT_PIN").write_text("2" * 40 + "\n")
+ new = commit(source)
+ (source / "lm15/__init__.py").write_text('SNAPSHOT = "third"\n')
+ third = commit(source)
+
+ (target / "scripts").mkdir()
+ shutil.copyfile(SCRIPT, target / "scripts/update_vendored_lm15.py")
+ commit(target)
+
+ def update(ref):
+ return run(target, sys.executable, "scripts/update_vendored_lm15.py", ref, "--source", str(source))
+
+ def squash_into_fresh_clone(repository, branch, round_number):
+ record = dict(line.split("=", 1) for line in (
+ repository / "dspy/_vendor/lm15-provenance.txt"
+ ).read_text().splitlines())
+ # GitHub can preserve original commit messages in its squash body.
+ message = "Squashed vendor PR"
+ if merge_style == "squash-with-trailers":
+ message += "\n\n" + git(repository, "log", "main..HEAD", "--format=%B")
+ git(repository, "checkout", "main")
+ git(repository, "merge", "--squash", branch)
+ git(repository, "commit", "-m", message)
+ fresh = tmp_path / f"fresh-{round_number}"
+ git(tmp_path, "clone", "--no-local", "--single-branch", "--branch", "main", str(repository), str(fresh))
+ assert run(fresh, "git", "cat-file", "-e", record["split"], check=False).returncode != 0
+ return fresh
+
+ # Import an older pin while the source's default branch points elsewhere.
+ if merge_style != "merge":
+ git(target, "checkout", "-b", "import-one")
+ update(old)
+ assert git(target, "rev-parse", "HEAD:dspy/_vendor/lm15") == git(source, "rev-parse", f"{old}:lm15")
+ assert (target / "dspy/_vendor/lm15/__init__.py").read_text() == 'SNAPSHOT = "old"\n'
+ if merge_style != "merge":
+ target = squash_into_fresh_clone(target, "import-one", 1)
+ git(target, "checkout", "-b", "update-two")
+ update(new)
+ assert git(target, "rev-parse", "HEAD:dspy/_vendor/lm15") == git(source, "rev-parse", f"{new}:lm15")
+ record = dict(line.split("=", 1) for line in (target / "dspy/_vendor/lm15-provenance.txt").read_text().splitlines())
+ assert record["commit"] == new
+ assert record["contract"] == "2" * 40
+ assert record["version"] == "1.0.0a1"
+ assert (target / "dspy/_vendor/lm15-LICENSE").read_text() == "MIT test license\n"
+ if merge_style != "merge":
+ target = squash_into_fresh_clone(target, "update-two", 2)
+ update(third)
+ assert git(target, "rev-parse", "HEAD:dspy/_vendor/lm15") == git(source, "rev-parse", f"{third}:lm15")
+ before = git(target, "rev-parse", "HEAD")
+ assert "already at this source commit" in update(third).stdout
+ assert git(target, "rev-parse", "HEAD") == before
+ assert git(target, "status", "--porcelain") == ""
+
+ # A committed hand edit must not be silently blessed or overwritten, even
+ # on a same-version update. Test rejection before any bookkeeping commit.
+ (target / "dspy/_vendor/lm15/__init__.py").write_text("LOCAL_EDIT = True\n")
+ edited = commit(target)
+ result = run(target, sys.executable, "scripts/update_vendored_lm15.py", third,
+ "--source", str(source), check=False)
+ assert result.returncode != 0 and "differ from the recorded source" in result.stderr
+ assert git(target, "rev-parse", "HEAD") == edited
+ assert (target / "dspy/_vendor/lm15/__init__.py").read_text() == "LOCAL_EDIT = True\n"
diff --git a/tests/test_vendored_lm15.py b/tests/test_vendored_lm15.py
new file mode 100644
index 000000000..1c1ddeb07
--- /dev/null
+++ b/tests/test_vendored_lm15.py
@@ -0,0 +1,74 @@
+"""These checks also run against the installed wheel outside the source tree."""
+
+import importlib
+import pickle
+import subprocess
+import sys
+from pathlib import Path
+
+
+def test_public_exports_are_the_vendored_objects():
+ import dspy
+ from dspy import lm15
+ from dspy._vendor import lm15 as vendored
+ from dspy.lm15 import Request
+
+ assert importlib.import_module("dspy.lm15") is dspy.lm15
+ assert Request is vendored.Request
+ assert lm15.__all__ == vendored.__all__
+ for name in lm15.__all__:
+ assert getattr(lm15, name) is getattr(vendored, name)
+ request = Request(model="example", messages=(lm15.Message.user("Hello"),))
+ restored = pickle.loads(pickle.dumps(request))
+ assert type(restored) is Request
+ assert restored == request
+
+
+def test_openai_converters_are_available_without_provider_calls():
+ from dspy.lm15 import Request, Response, request_from_openai_chat, response_from_openai_chat
+
+ request = request_from_openai_chat({"model": "example", "messages": [{"role": "user", "content": "Hello"}]})
+ response = response_from_openai_chat({
+ "id": "example-response",
+ "model": "example",
+ "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hi"}, "finish_reason": "stop"}],
+ "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2},
+ })
+ assert isinstance(request, Request)
+ assert isinstance(response, Response)
+ assert response.message.text == "Hi"
+
+
+def test_vendored_lm15_carries_provenance_and_license():
+ from dspy._vendor import lm15
+
+ pkg = Path(lm15.__file__).parent
+ assert (pkg / "py.typed").is_file()
+ marker = dict(line.split("=", 1) for line in (pkg.parent / "lm15-provenance.txt").read_text().splitlines())
+ assert marker["source"] == "https://github.com/cmpnd-ai/lm15-python.git"
+ assert marker["version"] == lm15.__version__ != "0.0.0"
+ for key in ("commit", "contract", "split"):
+ assert len(marker[key]) == 40
+ assert all(char in "0123456789abcdef" for char in marker[key])
+ assert "MIT" in (pkg.parent / "lm15-LICENSE").read_text()
+
+
+def test_version_ignores_an_unrelated_installed_distribution(tmp_path):
+ metadata = tmp_path / "lm15-7.8.9.dist-info"
+ metadata.mkdir()
+ (metadata / "METADATA").write_text("Metadata-Version: 2.1\nName: lm15\nVersion: 7.8.9\n")
+ code = """
+import sys
+sys.path.insert(0, sys.argv[1])
+from importlib.metadata import version
+assert version("lm15") == "7.8.9"
+import dspy.lm15
+from dspy._vendor import lm15
+from dspy._vendor.lm15 import vet
+from pathlib import Path
+record = Path(lm15.__file__).parent.parent / "lm15-provenance.txt"
+expected = dict(line.split("=", 1) for line in record.read_text().splitlines())["version"]
+assert dspy.lm15.__version__ == lm15.__version__ == vet.IMPL_VERSION == expected
+assert expected != "7.8.9"
+"""
+ subprocess.run([sys.executable, "-c", code, str(tmp_path)], check=True)