Skip to content

armgit / dspy

Public Imported from GitHub
0

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

Python

Update vendored lm15 to 1.4.0 with temporary auth fixes (#10540)

Isaac Miller76fe4c028c10
diff --git a/dspy/_vendor/UPDATING.md b/dspy/_vendor/UPDATING.md
index 7b0923d33..582dd7851 100644
--- a/dspy/_vendor/UPDATING.md
+++ b/dspy/_vendor/UPDATING.md
@@ -26,6 +26,17 @@ 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.
+For a temporary downstream patch stack, import its exact tested integration
+commit, not fork main. After the updater runs, record `upstream_tag`,
+`upstream_commit` and comma-separated, ordered `patches` commit IDs in
+`lm15-provenance.txt`. These identify the release base and source fixes;
+`commit` remains the exact patched source tip. Keep each patch's motivation,
+regression tests and upstream contribution status in the source repository
+(currently `DOWNSTREAM_PATCHES.md`). The package version alone does not imply
+an unmodified upstream release. The updater regenerates the provenance file,
+so review and record these fields for each patched import; omit them when
+returning to an unpatched release. Keep fork main an unpatched release mirror.
+
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,
diff --git a/dspy/_vendor/lm15-provenance.txt b/dspy/_vendor/lm15-provenance.txt
index fe0e7f89b..e4a9aa767 100644
--- a/dspy/_vendor/lm15-provenance.txt
+++ b/dspy/_vendor/lm15-provenance.txt
@@ -1,5 +1,8 @@
source=https://github.com/cmpnd-ai/lm15-python.git
-version=1.0.0rc3
-commit=55fce2e61a04ed3193acfeb8797b7c58d1b55398
-contract=b721ce4f03877d72a91431b3a5ce653ffc0b3e38
-split=63b6bb319f38ad1d31060138da54cb8ac8718711
+version=1.4.0
+commit=05acf78594fe82df81d9cc37b1c88c5ffc99760b
+contract=10645e5f6a69d9d7a365bdb62de9abac1f4dcffc
+split=39ec7880f77e9452e19a69ccb2f2c3e2d31166be
+upstream_tag=v1.4.0
+upstream_commit=48ab49d84257873e63329c62712973cd0c838363
+patches=2d3730fb1de1b501a08cb457e5a3242da77ca141,1e04a5a2edd6d81e9d2940f08b7ce87d11caa013,f6a7f8bb8bc13c247053a5a42728bbd9c008fe13,7d344a10ee0db3cec5516dbdffe496f1d36760a8,5211b7df922247c82a6639a1c1fe013e9a0491c6,3e9269f199a450b105637b4db6764a04920b454e,a91003b66b64fea90d1fd104429dee1585889007,5c4770348454193b9a6abfba69d1a3419faf5652,a3a526edffb18ca2f8818e9dc14da31c356e4da6,359f90953dd90089c306ceb5a69fe10bbb14c483
diff --git a/dspy/_vendor/lm15/__init__.py b/dspy/_vendor/lm15/__init__.py
index 63287be3b..55c0b8ed2 100644
--- a/dspy/_vendor/lm15/__init__.py
+++ b/dspy/_vendor/lm15/__init__.py
@@ -10,7 +10,9 @@ 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:
+Quick tour (tested recipes for every feature — conversations, streaming,
+tools, structured output, images and PDFs, reasoning, web search, caching,
+async, errors, image and speech generation: https://lm15.dev/skill.md):
from lm15 import AnthropicLM, Request, Message
@@ -166,6 +168,7 @@ from .errors import (
UnsupportedModelError,
UnsupportedFeatureError,
NotConfiguredError,
+ AuthOperationError,
RETRYABLE_ERRORS,
)
@@ -222,16 +225,6 @@ from .transports import Timeouts
# ── MAP-13 adaptations (lm15.adaptation) ──────────────────────────────
from .adaptation import Adaptation, AdaptationPolicy
-# ── Tool derivation (lm15.tools) ─────────────────────────────────────
-from .tools import (
- DerivedParam,
- ToolConfig,
- ToolDerivation,
- ToolDerivationError,
- tool,
-)
-from .tools import derive as derive_tool
-
# ── Judgments (changes/2026-09-17-judgments.md) ─────────────────────
from .judgments import choice, judgments, score, yes_no
from .types import data
@@ -270,9 +263,12 @@ __all__ = [
"ProviderError", "AuthError", "BillingError", "RateLimitError",
"InvalidRequestError", "ContextLengthError", "TimeoutError",
"ServerError", "UnsupportedModelError", "UnsupportedFeatureError",
- "NotConfiguredError", "RETRYABLE_ERRORS",
+ "NotConfiguredError", "AuthOperationError", "RETRYABLE_ERRORS",
"AccessPolicy", "EndpointSupport",
+ # managed authentication (lm15.login / lm15.interactive; loaded on first use)
+ "Auth", "AsyncAuth", "BoundClient", "TerminalUI", "login_providers", "connect",
# providers
+ "providers",
"choice", "judgments", "score", "yes_no", "data",
"OpenAILM", "OpenAIChatLM", "AnthropicLM", "GeminiLM", "ClaudeCodeLM", "OpenAICodexLM", "XaiLM", "TypeSafeLM", "AsyncTypeSafeLM",
"ProviderLM",
@@ -292,7 +288,31 @@ __all__ = [
"Adaptation", "AdaptationPolicy",
"UnknownModelError",
"AmbiguousModelError", "MissingCredentialError",
- # tool derivation (lm15.tools)
- "tool", "derive_tool", "ToolConfig", "ToolDerivation", "DerivedParam",
- "ToolDerivationError",
]
+
+
+# ── Managed authentication: loaded on first use ──────────────────────
+# ``lm15.login`` pulls in threading, http.server and the login flows;
+# nothing on the request path needs them, and lm15's import time is a
+# promise, so these names resolve lazily (PEP 562).
+# ``providers`` already names the implementation package (including xai,
+# openai, etc.). Keep the descriptor collection under a non-colliding name.
+_LAZY_LOGIN = {
+ "Auth": (".login", "Auth"),
+ "AsyncAuth": (".login", "AsyncAuth"),
+ "BoundClient": (".login", "BoundClient"),
+ "TerminalUI": (".login", "TerminalUI"),
+ "login_providers": (".login", "providers"),
+ "connect": (".interactive", "connect"),
+}
+
+
+def __getattr__(name: str):
+ target = _LAZY_LOGIN.get(name)
+ if target is None:
+ raise AttributeError(f"module 'lm15' has no attribute {name!r}")
+ import importlib
+
+ value = getattr(importlib.import_module(target[0], __package__), target[1])
+ globals()[name] = value
+ return value
diff --git a/dspy/_vendor/lm15/_authlock.py b/dspy/_vendor/lm15/_authlock.py
index 243508a76..81b41d977 100644
--- a/dspy/_vendor/lm15/_authlock.py
+++ b/dspy/_vendor/lm15/_authlock.py
@@ -66,15 +66,19 @@ def _lock_dir() -> Path:
try:
base = Path("~/.cache").expanduser()
except RuntimeError as exc: # no home directory: a WASI guest, some containers
- raise NotConfiguredError(
- "No home directory to keep the credential lock in, so lm15 cannot "
- "serialize credential refreshes against other processes. Reading "
- "credentials still works; refreshing them from here does not.",
- credential_hint="Set LM15_LOCK_DIR (or XDG_CACHE_HOME), or pass an explicit credential instead of a stored login",
- ) from exc
+ raise _no_home_error() from exc
return base / "lm15" / "locks"
+def _no_home_error() -> NotConfiguredError:
+ return NotConfiguredError(
+ "No home directory to keep the credential lock in, so lm15 cannot "
+ "serialize credential refreshes against other processes. Reading "
+ "credentials still works; refreshing them from here does not.",
+ credential_hint="Set LM15_LOCK_DIR (or XDG_CACHE_HOME), or pass an explicit credential instead of a stored login",
+ )
+
+
def _strip_windows_verbatim(path: str) -> str:
path = path.replace("/", "\\")
if path[:8].lower() == "\\\\?\\unc\\":
@@ -148,7 +152,10 @@ def _real_path_allow_missing(target: str) -> str:
raise ValueError("Named-user home expansion is unsupported for credential locks")
target = os.path.expanduser(target)
if target == "~" or target.startswith("~/") or (windows and target.startswith("~\\")):
- raise ValueError("No home directory for credential lock path")
+ # No home directory (Windows has no passwd fallback, so this is where
+ # it shows there): the same fact about the host as _lock_dir's, and
+ # the same typed error with the same remedy.
+ raise _no_home_error()
cwd = os.path.realpath(os.getcwd(), strict=True)
resolved, pending = parts(target, _strip_windows_verbatim(cwd) if windows else cwd)
links = 0
diff --git a/dspy/_vendor/lm15/_version.py b/dspy/_vendor/lm15/_version.py
index d958a62d9..7931e2bbd 100644
--- a/dspy/_vendor/lm15/_version.py
+++ b/dspy/_vendor/lm15/_version.py
@@ -1,3 +1,3 @@
"""The version of this source package, also used when building distributions."""
-__version__ = "1.0.0rc3"
+__version__ = "1.4.0"
diff --git a/dspy/_vendor/lm15/_vet_managed.py b/dspy/_vendor/lm15/_vet_managed.py
new file mode 100644
index 000000000..b914c9878
--- /dev/null
+++ b/dspy/_vendor/lm15/_vet_managed.py
@@ -0,0 +1,330 @@
+"""The vet shim's ``managed_run`` op (lm15-contract harness/PROTOCOL.md § managed).
+
+Runs one scripted program against the public managed-auth API with every
+seam injected: the store file the harness created, a fake wall and
+monotonic clock (waits advance them), a scripted auth server behind
+``Auth(opener=...)`` and a scripted UI. Returns one outcome per step, the
+ordered trace and the store file afterwards. The harness compares; this
+module only reports.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from .errors import AuthOperationError, LM15Error
+from .login import Auth
+from .login.engine import LoginCancelled
+from .login.types import AuthUrlNotice, DeviceCodeNotice, InfoNotice, ManualCodePrompt, ProgressNotice, \
+ SecretPrompt, SelectPrompt, TextPrompt
+
+JsonObject = dict[str, Any]
+
+
+class _Clock:
+ def __init__(self, start_ms: int) -> None:
+ self.start_s = start_ms / 1000.0
+ self.elapsed_s = 0.0
+
+ def wall(self) -> float:
+ return self.start_s + self.elapsed_s
+
+ def mono(self) -> float:
+ return self.elapsed_s
+
+
+class _Reply:
+ def __init__(self, status: int, body: bytes, content_type: str) -> None:
+ self.status = status
+ self._body = body
+ self.headers = {"Content-Type": content_type} if content_type else {}
+
+ def read(self, _n: int = -1) -> bytes:
+ return self._body
+
+ def getcode(self) -> int:
+ return self.status
+
+ def __enter__(self) -> "_Reply":
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ return None
+
+
+def _request_body(request: Any) -> Any:
+ data = request.data
+ if data is None:
+ return None
+ text = data.decode("utf-8")
+ content_type = (request.get_header("Content-type") or "").split(";")[0].strip()
+ if content_type == "application/x-www-form-urlencoded":
+ return dict(urllib.parse.parse_qsl(text, keep_blank_values=True))
+ try:
+ return json.loads(text)
+ except ValueError:
+ return text
+
+
+_TRANSPORT_HEADERS = {"accept", "accept-encoding", "connection", "content-length", "content-type", "host"}
+
+
+def _headers(request: Any) -> JsonObject:
+ """The request's own headers, lowercased; transport noise dropped and
+ lm15's own User-Agent reduced to its product token (versions differ
+ per language)."""
+ out: JsonObject = {}
+ for name, value in request.header_items():
+ key = name.lower()
+ if key in _TRANSPORT_HEADERS:
+ continue
+ if key == "user-agent" and value.startswith("lm15/"):
+ value = "lm15"
+ out[key] = value
+ return out
+
+
+class _Server:
+ def __init__(self, script: list[JsonObject], events: list[JsonObject]) -> None:
+ self.script = list(script)
+ self.events = events
+
+ def __call__(self, request: Any, _timeout: float) -> _Reply:
+ content_type = (request.get_header("Content-type") or "").split(";")[0].strip() or None
+ self.events.append({"http": {"method": request.get_method(), "url": request.full_url,
+ "content_type": content_type, "headers": _headers(request),
+ "body": _request_body(request)}})
+ if not self.script:
+ raise urllib.error.URLError(ConnectionRefusedError("no scripted reply"))
+ reply = self.script.pop(0)
+ if reply.get("delay_ms"):
+ import time as _time
+
+ _time.sleep(float(reply["delay_ms"]) / 1000.0) # real time: lets another process race this exchange
+ network = reply.get("network")
+ if network == "timeout":
+ raise urllib.error.URLError(TimeoutError("timed out"))
+ if network == "refused":
+ raise urllib.error.URLError(ConnectionRefusedError("refused"))
+ if "json" in reply:
+ return _Reply(int(reply.get("status", 200)), json.dumps(reply["json"]).encode(), "application/json")
+ return _Reply(int(reply.get("status", 200)), str(reply.get("text", "")).encode(),
+ str(reply.get("content_type", "text/plain")))
+
+
+def _prompt_event(prompt: Any) -> JsonObject:
+ event: JsonObject = {"type": prompt.type, "field_id": prompt.field_id}
+ if isinstance(prompt, SelectPrompt):
+ event["options"] = [option.id for option in prompt.options]
+ return event
+
+
+def _notice_event(notice: Any) -> JsonObject:
+ if isinstance(notice, AuthUrlNotice):
+ return {"type": "auth_url", "url": notice.url}
+ if isinstance(notice, DeviceCodeNotice):
+ return {"type": "device_code", "user_code": notice.user_code, "verification_url": notice.verification_url,
+ "expires_in_s": notice.expires_in_s, "interval_s": notice.interval_s}
+ if isinstance(notice, ProgressNotice):
+ return {"type": "progress", "stage": notice.stage}
+ if isinstance(notice, InfoNotice):
+ return {"type": "info"}
+ return {"type": type(notice).__name__}
+
+
+class _UI:
+ def __init__(self, answers: list[Any], events: list[JsonObject]) -> None:
+ self.answers = list(answers)
+ self.events = events
+ self.last_auth_url: str | None = None
+
+ def notify(self, notice: Any) -> None:
+ if isinstance(notice, AuthUrlNotice):
+ self.last_auth_url = notice.url
+ self.events.append({"notice": _notice_event(notice)})
+
+ def prompt(self, prompt: Any) -> str:
+ self.events.append({"prompt": _prompt_event(prompt)})
+ if not self.answers:
+ raise EOFError("the script has no more answers")
+ answer = self.answers.pop(0)
+ if isinstance(answer, str):
+ return answer
+ if answer.get("cancel"):
+ raise EOFError("the script cancels here")
+ query = dict(urllib.parse.parse_qsl(urllib.parse.urlsplit(self.last_auth_url or "").query))
+ state = query.get("state", "")
+ if "paste" in answer:
+ return f"{answer['paste']}#{state}"
+ if "paste_wrong_state" in answer:
+ return f"{answer['paste_wrong_state']}#not-the-state-of-this-attempt"
+ if "paste_url" in answer:
+ redirect = query.get("redirect_uri", "")
+ return f"{redirect}?{urllib.parse.urlencode({'code': answer['paste_url'], 'state': state})}"
+ raise ValueError(f"unknown scripted answer {answer!r}")
+
+ def dismiss(self, _prompt: Any) -> None:
+ return None
+
+
+def _error(exc: BaseException) -> JsonObject:
+ if isinstance(exc, LoginCancelled):
+ return {"type": "cancelled"}
+ if isinstance(exc, AuthOperationError):
+ return {"type": "AuthOperationError", "code": exc.code, "reason": exc.reason, "stage": exc.stage,
+ "commit_state": exc.commit_state, "recovery": exc.recovery}
+ if isinstance(exc, LM15Error):
+ return {"type": type(exc).__name__, "code": exc.code}
+ return {"type": type(exc).__name__}
+
+
+def _connection(c: Any) -> JsonObject | None:
+ if c is None:
+ return None
+ out: JsonObject = {
+ "id": c.id, "provider": c.provider, "instance_id": c.instance_id, "kind": c.kind, "method_id": c.method_id,
+ "routes": list(c.routes), "label": c.label, "created_at": c.created_at,
+ "identity_generation": c.identity_generation, "credential_revision": c.credential_revision,
+ "settings": dict(c.settings),
+ }
+ if c.account_label is not None:
+ out["account_label"] = c.account_label
+ return out
+
+
+def _status(s: Any) -> JsonObject:
+ return {"provider": s.provider, "presence": s.presence, "usability": s.usability,
+ "connection": _connection(s.connection), "expires_at": s.expires_at, "logged_out": s.logged_out,
+ "verification": None if s.verification is None else {"result": s.verification.result,
+ "check": s.verification.check}}
+
+
+def _credential(value: Any) -> JsonObject | None:
+ from .credentials import ApiKey, BearerToken
+
+ if value is None:
+ return None
+ if isinstance(value, BearerToken):
+ return {"kind": "bearer", "value": value.value}
+ if isinstance(value, ApiKey):
+ return {"kind": "api_key", "value": value.value}
+ if isinstance(value, str):
+ return {"kind": "api_key", "value": value}
+ return {"kind": type(value).__name__}
+
+
+def _method(m: Any) -> JsonObject:
+ return {"id": m.id, "kind": m.kind, "flow": m.flow, "availability": m.availability,
+ "subscription": m.subscription, "delivery": list(m.delivery),
+ "fields": [{"id": f.id, "type": f.type, "required": f.required,
+ "options": [o.id for o in f.options]} for f in m.fields]}
+
+
+def _resolve_refs(step: JsonObject, outcomes: list[JsonObject]) -> JsonObject:
+ """``{"id_of_step": n}`` is the connection id step n returned;
+ ``{"of_step": n}`` is its ``[id, identity_generation]`` pin."""
+ def value(n: int) -> JsonObject:
+ outcome = outcomes[n]
+ if not outcome.get("ok") or not isinstance(outcome.get("value"), dict):
+ raise ValueError(f"step {n} returned no connection to refer to")
+ return outcome["value"]
+
+ resolved: JsonObject = {}
+ for key, item in step.items():
+ if isinstance(item, dict) and "id_of_step" in item:
+ resolved[key] = value(int(item["id_of_step"]))["id"]
+ elif isinstance(item, dict) and "of_step" in item:
+ connection = value(int(item["of_step"]))
+ resolved[key] = [connection["id"], connection["identity_generation"]]
+ else:
+ resolved[key] = item
+ return resolved
+
+
+def _step(auth: Auth, step: JsonObject, clock: _Clock, ui: _UI, env: dict[str, str], sentinel: str) -> Any:
+ do = step["do"]
+ if do == "advance":
+ clock.elapsed_s += float(step["ms"]) / 1000.0
+ return None
+ if do == "login":
+ return _connection(auth.login(
+ step["provider"], step.get("method"), ui=ui, answers=step.get("answers"), settings=step.get("settings"),
+ replace=step.get("replace"), allow_unverified=bool(step.get("allow_unverified")),
+ ))
+ if do == "configure":
+ return _connection(auth.configure(step["provider"], method=step["method"], answers=step.get("answers"),
+ settings=step.get("settings"), replace=step.get("replace")))
+ if do == "set_api_key":
+ return _connection(auth.set_api_key(step["provider"], step["key"], replace=step.get("replace")))
+ if do == "status":
+ return _status(auth.status(step["provider"]))
+ if do == "connections":
+ return [_connection(c) for c in auth.connections()]
+ if do == "logout":
+ forgotten = auth.logout(step["target"])
+ return {"provider": forgotten.provider, "forgot": forgotten.forgot, "routes": list(forgotten.routes),
+ "identity_generation": forgotten.identity_generation}
+ if do == "cancel_login":
+ return auth.cancel_login(step["provider"])
+ if do == "request_auth":
+ pinned = step.get("pinned")
+ result = auth.request_auth(step["provider"], pinned=tuple(pinned) if pinned else None)
+ return {"credential": _credential(result.credential), "headers": dict(result.headers),
+ "base_url": result.base_url, "account_id": result.account_id, "named": result.named}
+ if do == "methods":
+ return [_method(m) for m in auth.methods(step["provider"])]
+ if do == "providers":
+ return sorted(d.id for d in auth.providers())
+ if do == "explain":
+ from .doctor import explain_auth
+ from .router import RouterConfig
+
+ api_keys = {p: f"{sentinel}-explicit" for p in step.get("api_keys", [])}
+ report = explain_auth(step["provider"], env=env, api_keys=api_keys or None,
+ config=RouterConfig(auth=auth, env=env, api_keys=api_keys or None))
+ return {"configured": report.configured, "steps": [{"kind": s.kind, "state": s.state} for s in report.steps]}
+ raise ValueError(f"unknown managed step {do!r}")
+
+
+def op_managed_run(msg: JsonObject) -> JsonObject:
+ events: list[JsonObject] = []
+ clock = _Clock(int(msg["clock_ms"]))
+ env = {str(k): str(v) for k, v in (msg.get("env") or {}).items()}
+
+ def sleep(seconds: float) -> None:
+ clock.elapsed_s += seconds
+ events.append({"sleep_ms": int(round(seconds * 1000))})
+
+ server = _Server(msg.get("http") or [], events)
+ ui = _UI(msg.get("ui") or [], events)
+ store_path = Path(msg["store_path"])
+ saved_env = dict(os.environ)
+ os.environ.clear()
+ os.environ.update(env)
+ steps: list[JsonObject] = []
+ try:
+ from .login import FileStore
+
+ auth = Auth(FileStore(store_path), clock=clock.wall, monotonic=clock.mono, opener=server, sleep=sleep)
+ for index, step in enumerate(msg["steps"]):
+ events.append({"step": index})
+ try:
+ steps.append({"ok": True, "value": _step(auth, _resolve_refs(step, steps), clock, ui, env, str(msg["sentinel"]))})
+ except (LM15Error, LoginCancelled, ValueError, KeyError, TypeError) as exc:
+ steps.append({"ok": False, "error": _error(exc)})
+ finally:
+ os.environ.clear()
+ os.environ.update(saved_env)
+ store: Any = None
+ if store_path.exists():
+ text = store_path.read_text(encoding="utf-8")
+ try:
+ store = {"document": json.loads(text)}
+ except ValueError:
+ store = {"raw": text}
+ return {"steps": steps, "events": events, "store": store}
diff --git a/dspy/_vendor/lm15/_vet_tables.py b/dspy/_vendor/lm15/_vet_tables.py
new file mode 100644
index 000000000..0e4cfefa9
--- /dev/null
+++ b/dspy/_vendor/lm15/_vet_tables.py
@@ -0,0 +1,105 @@
+"""The provider tables, as data, for the vet protocol's ``provider_tables`` op.
+
+``lm15-contract/tables/providers.json`` is this function's output, and
+``tools/audit.py`` there fails when the two differ. Ports generate their
+copies from that file (``playbooks/port.md`` rule 2: tables are data, copied,
+never re-derived). This module reads the tables the reference uses at import
+time and serializes them; it adds no fact of its own.
+
+Shape rules, so a generator never guesses:
+
+- Compat policies list only the knobs a preset sets (``None`` means
+ "inherit", so an absent key is exactly the value), with
+ ``model_overrides`` as ``[prefix, {knob: value}]`` pairs in match order.
+- Access policies, host specs and endpoint support are written whole, every
+ field, so a port never depends on its own defaults agreeing with these.
+- Tuples become arrays and keep their order; mappings keep insertion order;
+ a frozenset (``EndpointSupport.extra``) becomes a sorted array.
+- Field names are the reference's (snake_case); a port renames them.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Mapping
+from typing import Any
+
+SCHEMA = 1
+
+
+_NO_DEFAULT = object()
+
+
+def _default(f: dataclasses.Field) -> Any:
+ if f.default is not dataclasses.MISSING:
+ return f.default
+ if f.default_factory is not dataclasses.MISSING: # type: ignore[misc]
+ return f.default_factory() # type: ignore[misc]
+ return _NO_DEFAULT
+
+
+def _plain(value: Any, *, elide: tuple[type, ...]) -> Any:
+ if dataclasses.is_dataclass(value) and not isinstance(value, type):
+ out: dict[str, Any] = {}
+ for f in dataclasses.fields(value):
+ v = getattr(value, f.name)
+ if isinstance(value, elide) and v == _default(f):
+ continue # a compat knob at its default inherits
+ out[f.name] = _plain(v, elide=elide)
+ return out
+ if isinstance(value, Mapping):
+ return {str(k): _plain(v, elide=elide) for k, v in value.items()}
+ if isinstance(value, (frozenset, set)):
+ return sorted(_plain(v, elide=elide) for v in value)
+ if isinstance(value, (list, tuple)):
+ return [_plain(v, elide=elide) for v in value]
+ if value is None or isinstance(value, (str, int, float, bool)):
+ return value
+ raise TypeError(f"provider_tables: no JSON form for {type(value).__name__}")
+
+
+def provider_tables() -> dict[str, Any]:
+ from . import compat as _compat
+ from .login import declared as _declared
+ from .login import flows as _flows
+ from . import registry as _registry
+ from . import router as _router
+
+ elide = (_compat.OpenAIChatCompat, _compat.OpenAIResponsesCompat, _compat.AnthropicCompat)
+
+ def plain(value: Any) -> Any:
+ return _plain(value, elide=elide)
+
+ def row(definition: Any) -> dict[str, Any]:
+ compat = definition.compat
+ return {
+ "id": definition.id,
+ "dialect": definition.dialect,
+ "kind": "hosted" if definition.hosted else ("bound" if definition.bound else "adapter-owned"),
+ "compat": compat if compat is None or isinstance(compat, str) else plain(compat),
+ "access": plain(definition.access),
+ "aliases": list(definition.aliases),
+ "placeholder_key": definition.placeholder_key,
+ "console_url": definition.console_url,
+ "note": definition.note,
+ }
+
+ return {
+ "schema": SCHEMA,
+ "providers": [row(d) for d in _registry.PROVIDERS.values()],
+ "declared_login": [row(d) for d in _declared.DECLARED_PROVIDERS],
+ "compat": {
+ "chat": plain(_compat.OPENAI_CHAT_PRESETS),
+ "chat_base_urls": plain(_compat.OPENAI_CHAT_PRESET_BASE_URLS),
+ "responses": plain(_compat.OPENAI_RESPONSES_PRESETS),
+ "responses_base_urls": plain(_compat.OPENAI_RESPONSES_PRESET_BASE_URLS),
+ "anthropic": plain(_compat.ANTHROPIC_PRESETS),
+ "anthropic_base_urls": plain(_compat.ANTHROPIC_PRESET_BASE_URLS),
+ "preset_aliases": plain(_compat._OPENAI_CHAT_PRESET_ALIASES),
+ },
+ "routing": {
+ "default_rules": [{"prefix": r.prefix, "provider": r.provider, "note": r.note} for r in _router.DEFAULT_RULES],
+ "litellm_prefixes": plain(_router.LITELLM_PROVIDER_PREFIXES),
+ },
+ "login": {"service_labels": plain(_flows._SERVICE_LABELS)},
+ }
diff --git a/dspy/_vendor/lm15/access.py b/dspy/_vendor/lm15/access.py
index 7539efbef..2b85a55db 100644
--- a/dspy/_vendor/lm15/access.py
+++ b/dspy/_vendor/lm15/access.py
@@ -35,8 +35,9 @@ manifest is its access policy.
from __future__ import annotations
import os
+import re
from dataclasses import dataclass, field
-from typing import Callable
+from typing import Callable, Mapping
from .auth import (
CLAUDE_CODE_LOGIN_HINT,
@@ -46,7 +47,7 @@ from .auth import (
get_claude_code_access_token,
get_codex_cli_access_token,
get_xai_access_token,
- usable_xai_credential,
+ xai_stored_state,
)
from .compat import ANTHROPIC_PRESET_BASE_URLS, OPENAI_CHAT_PRESET_BASE_URLS, OPENAI_RESPONSES_PRESET_BASE_URLS
from .errors import NotConfiguredError
@@ -87,8 +88,17 @@ TYPESAFE_API = AccessPolicy(
auth_scheme=("bearer",),
)
-DEFAULT_CLAUDE_CODE_VERSION = "2.1.170"
+# The Claude Code release this door says it is (``user-agent:
+# claude-cli/<version>``). Anthropic's server reads it: a model can require
+# a newer release (claude-opus-5-5 refuses anything before 2.1.280, live
+# 2026-09-23 and 2026-09-30). The latest release when last receipted
+# (changes/2026-09-30-claude-code-client-version.md); callers move it
+# without a release through the ``client_version`` setting or
+# LM15_CLAUDE_CODE_VERSION (AUTH-10 backend settings).
+DEFAULT_CLAUDE_CODE_VERSION = "2.1.285"
DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude."
+CLAUDE_CODE_VERSION_ENV = "LM15_CLAUDE_CODE_VERSION"
+CODEX_CLIENT_VERSION_ENV = "LM15_CODEX_CLIENT_VERSION"
# models=True: the Anthropic /v1/models endpoint answers to the OAuth
# headers (validated live 2026-08-31, HTTP 200). Files and batch are
@@ -107,6 +117,8 @@ CLAUDE_CODE = AccessPolicy(
),
login_hint=CLAUDE_CODE_LOGIN_HINT,
backend="claude-code",
+ backend_options={"client_version": DEFAULT_CLAUDE_CODE_VERSION},
+ backend_settings=(HostSetting("client_version", env=(CLAUDE_CODE_VERSION_ENV,)),),
system_prefix=DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT,
)
@@ -140,6 +152,7 @@ OPENAI_CODEX = AccessPolicy(
login_hint=OPENAI_CODEX_LOGIN_HINT,
backend="chatgpt-codex",
backend_options={"client_version": DEFAULT_CODEX_CLIENT_VERSION},
+ backend_settings=(HostSetting("client_version", env=(CODEX_CLIENT_VERSION_ENV,)),),
system_prefix=DEFAULT_CODEX_INSTRUCTIONS,
base_url=DEFAULT_CODEX_BASE_URL,
)
@@ -276,6 +289,47 @@ MOONSHOTAI = AccessPolicy(
base_url=OPENAI_CHAT_PRESET_BASE_URLS["moonshotai"],
)
+# ─── Open-model inference hosts (changes/2026-09-26-inference-hosts-live.md) ───
+#
+# DeepInfra, Together AI, Fireworks AI and Parasail: a bearer key each, the
+# provider's own documented variable (docs examples use exactly these names;
+# lm15-contract/scrapes/<id>/pages), prepaid or card-billed balances (HTTP
+# 402 when drained on DeepInfra and Together). Each also sells batch jobs
+# and files on the same key, and some sell images, speech or video; none is
+# registered — `supports` names what has a receipt.
+
+DEEPINFRA = AccessPolicy(
+ provider="deepinfra",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("DEEPINFRA_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["deepinfra"],
+)
+
+TOGETHER = AccessPolicy(
+ provider="together",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("TOGETHER_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["together"],
+)
+
+FIREWORKS = AccessPolicy(
+ provider="fireworks",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("FIREWORKS_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["fireworks"],
+)
+
+PARASAIL = AccessPolicy(
+ provider="parasail",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=("PARASAIL_API_KEY",),
+ base_url=OPENAI_CHAT_PRESET_BASE_URLS["parasail"],
+)
+
# 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
@@ -548,13 +602,20 @@ AZURE_ANTHROPIC = AccessPolicy(
# else {loc}-aiplatform.googleapis.com (vertex-locations.md:40-63, :91).
_VERTEX_BASE = "https://{location_host}/v1/projects/{project}/locations/{location}"
+# API keys (amended 2026-09-26): Google accepts a Vertex API key in
+# ``x-goog-api-key`` on the project-scoped global and regional hosts
+# (live: generateContent, streamGenerateContent, countTokens), so a key
+# user keeps residency control. Key first, then bearer: a string is a key
+# unless it has an access token's shape (``auth_header``). No env key:
+# ``GOOGLE_API_KEY`` is commonly set for the Gemini API, and reading it
+# here would silently replace the ADC identity (and its billing) with it.
VERTEX = AccessPolicy(
provider="vertex",
supports=EndpointSupport(complete=True, stream=True), # caches/batches/models: live cells
credential_policy="gcp-chain",
- auth_modes=("google-oauth",),
+ auth_modes=("x-goog-api-key", "google-oauth"),
env_keys=(),
- auth_scheme=("bearer",),
+ auth_scheme=("x-api-key", "bearer"),
backend="vertex",
host=HostSpec(base_url=_VERTEX_BASE + "/publishers/google", settings=(_GCP_PROJECT, _GCP_LOCATION)),
)
@@ -624,6 +685,92 @@ SGLANG = AccessPolicy(
)
+# ─── Backend settings (AUTH-10, amended 2026-09-30) ──────────────────
+
+
+def resolve_backend_settings(
+ policy: AccessPolicy,
+ given: "Mapping[str, str] | None",
+ env: "Mapping[str, str] | None" = None,
+ *,
+ sources: dict[str, str] | None = None,
+) -> dict[str, str]:
+ """The door's backend settings: the caller's value, then ``env`` (when
+ given — the router passes the environment, an adapter built by hand
+ does not), then the table's ``backend_options`` value. ``sources``
+ receives each origin in the AUTH-10 ``from`` vocabulary (``explicit``,
+ ``env:<VAR>``, ``default``). A name the door does not declare is a
+ configuration error that lists the names it does: a setting nothing
+ reads would otherwise be dropped with nothing said."""
+ given = {str(k): str(v) for k, v in (given or {}).items()}
+ known = [setting.name for setting in policy.backend_settings]
+ unknown = sorted(set(given) - set(known))
+ if unknown:
+ hint = f"known: {', '.join(known)}" if known else "this door takes no settings"
+ raise NotConfiguredError(
+ f"{policy.provider}: unknown setting(s) {', '.join(repr(n) for n in unknown)}; {hint}",
+ provider=policy.provider,
+ credential_hint=(f"Pass only {', '.join(known)} for {policy.provider}" if known
+ else f"Remove the settings entry for {policy.provider}"),
+ )
+ out: dict[str, str] = {}
+ record = sources if sources is not None else {}
+ for setting in policy.backend_settings:
+ value = given.get(setting.name) or ""
+ origin = "explicit" if value else ""
+ if not value and env is not None:
+ for var in setting.env:
+ candidate = env.get(var)
+ if candidate:
+ value, origin = candidate, f"env:{var}"
+ break
+ if not value:
+ value, origin = policy.backend_options[setting.name], "default"
+ out[setting.name] = value
+ record[setting.name] = origin
+ return out
+
+
+def with_backend_settings(policy: AccessPolicy, values: "Mapping[str, str]") -> AccessPolicy:
+ """The policy with these resolved backend settings in ``backend_options``.
+
+ ``client_version`` on the ``claude-code`` backend is also the version the
+ ``user-agent`` header claims (``claude-cli/<client_version>``): the one
+ backend setting that reaches a header. On ``chatgpt-codex`` it is the
+ ``/models`` query parameter, read from ``backend_options``."""
+ from dataclasses import replace
+
+ if not values:
+ return policy
+ options = {**policy.backend_options, **values}
+ if options == dict(policy.backend_options):
+ return policy
+ out = replace(policy, backend_options=options)
+ if policy.backend == "claude-code" and "client_version" in values:
+ out = out.with_headers({"user-agent": f"claude-cli/{options['client_version']}"})
+ return out
+
+
+# Anthropic's refusal when the claimed Claude Code release is older than a
+# model requires (live 2026-09-23, 2026-09-30; errors/cases/claude-code.json).
+_CLAUDE_CODE_FLOOR = re.compile(r"Claude Code (\S+) does not support this model; version (\S+) or newer is required")
+
+
+def claude_code_version_guidance(message: str) -> str:
+ """The claude-code door's minimum-version refusal, with what an lm15
+ caller changes. The server says "run 'claude update'", which does not
+ move the version lm15 claims; the guidance names the setting that does
+ (AUTH-10 backend settings). Any other message is returned unchanged."""
+ match = _CLAUDE_CODE_FLOOR.search(message)
+ if match is None or "\n\n To fix:" in message:
+ return message
+ required = match.group(2)
+ return (f"{message}\n\n To fix:\n"
+ " - lm15 sends this version itself; updating Claude Code does not change it\n"
+ f" - Set the claude-code setting client_version to {required} or newer "
+ f"(or {CLAUDE_CODE_VERSION_ENV}={required})\n")
+
+
# ─── Credential loading, keyed by provider ───────────────────────────
@@ -658,11 +805,6 @@ _CREDENTIAL_LOADERS: dict[str, Callable[[str | os.PathLike[str] | None], LoadedC
"xai": _load_xai,
}
-_STORED_PROBES: dict[str, Callable[[], bool]] = {
- "xai": usable_xai_credential,
-}
-
-
def load_credential(
policy: AccessPolicy,
api_key: Credential | None,
@@ -680,11 +822,20 @@ def load_credential(
loader = _CREDENTIAL_LOADERS.get(policy.provider) if policy.credential_policy != "key" else None
if loader is not None:
return loader(credentials_path)
+ if policy.env_keys:
+ # An adapter built by hand reads no environment (only the router
+ # does), so "set the variable" would not help: say what does.
+ var = policy.env_keys[0]
+ raise NotConfiguredError(
+ f"{policy.provider}: no API key given. An adapter built by hand reads no environment variable, "
+ f"so {var} is not used here even when it is set",
+ provider=policy.provider,
+ credential_hint=policy.login_hint
+ or f'pass api_key=os.environ["{var}"], or use lm15.LMRouter(), which reads {" or ".join(policy.env_keys)}',
+ )
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="),
+ f"{policy.provider}: no credential given; pass api_key=",
provider=policy.provider,
- env_keys=policy.env_keys,
credential_hint=policy.login_hint,
)
@@ -692,8 +843,19 @@ def load_credential(
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
+ return stored_credential_state(policy) == "usable"
+
+
+_STORED_STATES: dict[str, Callable[[], str]] = {
+ "xai": xai_stored_state,
+}
+
+
+def stored_credential_state(policy: AccessPolicy) -> str:
+ """``usable`` | ``unusable`` | ``logged_out`` | ``absent`` (spec/auth.md
+ AUTH-1 ``oauth-unless-explicit``, R3). Reads files only."""
+ probe = _STORED_STATES.get(policy.provider)
+ return probe() if probe is not None else "absent"
# AUTH-2 (ratified 2026-09-06, lm15-contract/changes/2026-09-06-decisions.md D1): the
@@ -736,6 +898,19 @@ def select_scheme(policy: AccessPolicy, credential: CredentialValue) -> AuthSche
)
+def looks_like_access_token(text: str) -> str | None:
+ """The token shape a plain string has, if any (AUTH-2, amended
+ 2026-09-19 and 2026-09-26): ``"JWT"`` (JWS compact: Entra, OIDC, a
+ Google self-signed JWT) or ``"Google access token"`` (``ya29.``, what
+ every Google OAuth endpoint issues: user, service account, metadata,
+ STS, impersonation). No key any door here issues has either shape."""
+ if text.startswith("ya29."):
+ return "Google access token"
+ if _looks_like_jwt(text):
+ return "JWT"
+ return None
+
+
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."""
@@ -766,7 +941,7 @@ def auth_header(
``_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):
+ if scheme in ("api-key", "x-api-key") and "bearer" in policy.auth_scheme and looks_like_access_token(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 any door lm15
# has: it is an Entra/OAuth access token that a token-provider
@@ -777,7 +952,9 @@ def auth_header(
# which the request can succeed — and the doctor says so. Before
# that date this was a refusal naming the BearerToken wrap; the
# wrap is still accepted and still the form to use when nothing
- # should be read from a token's shape.
+ # should be read from a token's shape. Amended 2026-09-26: a Google
+ # access token (``ya29.``) is read the same way, so an access token
+ # string on the vertex door (key header first) still goes as bearer.
scheme = "bearer"
if scheme == "bearer":
return ("Authorization", f"Bearer {value.value}")
diff --git a/dspy/_vendor/lm15/auth.py b/dspy/_vendor/lm15/auth.py
index fe6565dc0..eab7e1102 100644
--- a/dspy/_vendor/lm15/auth.py
+++ b/dspy/_vendor/lm15/auth.py
@@ -56,6 +56,7 @@ from pathlib import Path
from typing import Any
from ._authlock import CredentialLockTimeout, hold_file_lock, write_private_json_atomic
+from ._version import __version__
from .errors import AuthError, NotConfiguredError, UnsupportedFeatureError
__all__ = [
@@ -79,6 +80,7 @@ __all__ = [
"refresh_xai_credential",
"start_xai_device_login",
"usable_xai_credential",
+ "xai_stored_state",
"write_claude_code_credential",
"write_codex_cli_credential",
"write_xai_credential",
@@ -100,7 +102,7 @@ def _user_path(*parts: str) -> Path:
CLAUDE_CODE_CREDENTIALS_PATH = _user_path(".claude", ".credentials.json")
-CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d5-88ed-5944d1962f5e"
+CLAUDE_CODE_CLIENT_ID = "9d1c250a-e61b-44d9-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)"
@@ -202,7 +204,8 @@ def _post_json(url: str, payload: dict[str, Any]) -> dict[str, Any]:
request = urllib.request.Request(
url,
data=body,
- headers={"Content-Type": "application/json", "Accept": "application/json"},
+ headers={"Content-Type": "application/json", "Accept": "application/json",
+ "User-Agent": f"lm15/{__version__}"},
method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response: # noqa: S310 - provider token endpoint
@@ -215,7 +218,8 @@ def _post_form(url: str, payload: dict[str, Any]) -> dict[str, Any]:
request = urllib.request.Request(
url,
data=body,
- headers={"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json"},
+ headers={"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json",
+ "User-Agent": f"lm15/{__version__}"},
method="POST",
)
with urllib.request.urlopen(request, timeout=30) as response: # noqa: S310 - provider token endpoint
@@ -541,10 +545,19 @@ def _xai_entry_to_credential(entry: Any) -> LocalOAuthCredential | None:
return None
refresh = entry.get("refresh")
expires = entry.get("expires")
+ expires_at = expires if isinstance(expires, int) and not isinstance(expires, bool) else None
+ if expires_at is not None and "issued_at" in entry:
+ # Written by the managed flow: ``expires`` is the ACTUAL expiry
+ # (AUTH-20.2). This legacy reader's ``expired`` means "renewal is
+ # due", so apply the ratified lead here. Entries without
+ # ``issued_at`` were written already reduced by the old 5-minute skew.
+ lifetime = entry.get("lifetime_s")
+ lead_s = min(300.0, lifetime / 10.0) if isinstance(lifetime, (int, float)) and lifetime > 0 else 300.0
+ expires_at = int(expires_at - lead_s * 1000)
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,
+ expires_at=expires_at,
)
@@ -604,10 +617,34 @@ def usable_xai_credential(auth_path: str | os.PathLike[str] | None = None) -> bo
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)
+ return xai_stored_state(auth_path) == "usable"
+
+
+def xai_stored_state(auth_path: str | os.PathLike[str] | None = None) -> str:
+ """The stored xAI subscription's state, offline (spec/auth.md AUTH-1,
+ ratified R2/R3 2026-09-22):
+
+ - ``usable``: fresh, or expired with a refresh token;
+ - ``unusable``: stored but expired with no refresh token — this BLOCKS
+ the environment key (a failed subscription is never silently
+ replaced by a metered key);
+ - ``logged_out``: signed out under a managed Auth; the non-secret
+ marker in lm15's own store blocks the environment key after a
+ restart too;
+ - ``absent``: nothing stored anywhere; the ordinary key chain applies.
+ """
+ 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)
+ if not data:
+ continue
+ credential = _xai_entry_to_credential(data.get(_XAI_PROVIDER_KEY))
+ if credential is not None:
+ return "usable" if (not credential.expired or credential.refresh_token) else "unusable"
+ slots = (data.get("_lm15") or {}).get("slots") if isinstance(data.get("_lm15"), dict) else None
+ if isinstance(slots, dict) and isinstance(slots.get(_XAI_PROVIDER_KEY), dict) and slots[_XAI_PROVIDER_KEY].get("logged_out"):
+ return "logged_out"
+ return "absent"
def _xai_credential_from_token_response(
@@ -849,16 +886,33 @@ def login_xai(
) -> 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.
+ Since 2026-09-22 this runs the managed xAI flow (``lm15.login``): same
+ protocol, same store entry, one implementation. ``echo`` receives the
+ verification URL and user code; the call 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
+ from .login import Auth, AuthOperationError
+ from .login.types import DeviceCodeNotice
+
+ class _EchoUI:
+ def prompt(self, prompt: Any) -> str:
+ raise AuthOperationError("login_xai takes no input", reason="interaction_required",
+ stage="interaction", recovery="provide_input")
+
+ def notify(self, notice: Any) -> None:
+ if isinstance(notice, DeviceCodeNotice):
+ echo(f"Open {notice.verification_url} and enter code: {notice.user_code}")
+
+ auth = Auth.local(auth_path)
+ current = auth.status("xai").connection
+ try:
+ auth.login("xai", "device", ui=_EchoUI(), replace=current.id if current else None)
+ except AuthOperationError as exc:
+ if exc.reason == "login_denied":
+ raise AuthError(str(exc), provider="xai", credential_hint=XAI_LOGIN_HINT) from exc
+ raise
+ return load_xai_credential(auth_path)
# ─── Uniform login entry point ───────────────────────────────────
diff --git a/dspy/_vendor/lm15/cloud/chains.py b/dspy/_vendor/lm15/cloud/chains.py
index e21724e20..023f020e2 100644
--- a/dspy/_vendor/lm15/cloud/chains.py
+++ b/dspy/_vendor/lm15/cloud/chains.py
@@ -41,6 +41,7 @@ import hashlib
import http.client
import json
import os
+import re
import subprocess
import threading
import urllib.parse
@@ -49,11 +50,11 @@ import uuid
from dataclasses import dataclass, field
from datetime import datetime, timedelta, timezone
from pathlib import Path
-from typing import Any, Callable, Mapping
+from typing import Any, Callable, Mapping, Optional, Tuple
from xml.etree import ElementTree
from ..credentials import ApiKey, AwsCredentials, BearerToken, CredentialValue, parse_rfc3339
-from ..errors import AuthError, NotConfiguredError
+from ..errors import _GUIDANCE_MARKER, AuthError, NotConfiguredError
from ..features import NAMED_CREDENTIALS, RUNG_KINDS, AccessPolicy
from . import rs256, sigv4
@@ -94,7 +95,10 @@ def _default_http(method: str, url: str, headers: Mapping[str, str], body: bytes
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)
+ # A cloud CLI's output: the token is ASCII JSON; any other text may be in
+ # the console code page on Windows, so decode leniently, never crash.
+ out = subprocess.run(argv, capture_output=True, text=True, encoding="utf-8", errors="replace",
+ timeout=timeout, check=False, env=env)
except (OSError, subprocess.SubprocessError):
raise AuthError("credential command failed") from None
if out.returncode != 0:
@@ -236,12 +240,39 @@ 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:
+# AUTH-21 (clarified 2026-09-24): a failed auth-endpoint exchange carries
+# the HTTP status and, only when the reply's ``error`` (or ``error.code`` /
+# ``error.type``) is one of these fixed words, that word — nothing else from
+# the reply. An error description can reflect the request (a refresh token,
+# a signed assertion); a fixed word cannot.
+_OAUTH_ERROR_WORDS = frozenset({
+ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client", "unsupported_grant_type",
+ "invalid_scope", "access_denied", "server_error", "temporarily_unavailable", "authorization_pending",
+ "slow_down", "expired_token",
+})
+
+
+def _oauth_error_word(data: Mapping[str, Any]) -> str | None:
+ err = data.get("error")
+ candidates = [err.get("code"), err.get("type")] if isinstance(err, dict) else [err]
+ for value in candidates:
+ if isinstance(value, str) and value in _OAUTH_ERROR_WORDS:
+ return value
+ return None
+
+
+def _exchange(ctx: ChainContext, method: str, url: str, headers: Mapping[str, str], body: bytes | None, what: str,
+ hint: str | None = None) -> dict:
+ """One token-endpoint round trip. A refusal carries the status and a
+ fixed-vocabulary OAuth error word (AUTH-21), and, when the caller knows
+ it, the one action that fixes it (``hint``) instead of the API-key
+ guidance: the action is what the user needs, and it holds no secret."""
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}")
+ word = _oauth_error_word(data)
+ raise AuthError(f"{what}: HTTP {status}" + (f" ({word})" if word else ""), credential_hint=hint, provider_code=word)
return data
@@ -996,12 +1027,15 @@ def _gcp_from_info(ctx: ChainContext, info: Mapping[str, Any], where: str) -> Be
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")
+ data = _exchange(ctx, "POST", str(info.get("token_uri") or _GCP_TOKEN_URL), {"content-type": "application/x-www-form-urlencoded"}, _form(pairs),
+ f"Google OAuth refresh ({where})", _gcp_user_login_hint(where))
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")
+ _form([("grant_type", _JWT_BEARER), ("assertion", assertion)]), f"Google service account key ({where})",
+ f"the key in {where} may have been deleted or disabled, or this machine's clock is off; "
+ "create a new key (Cloud console: IAM & Admin > Service accounts > Keys) or use another identity")
return _bearer_from_oauth(data, now, "Google service account")
if kind == "external_account":
return _gcp_external_account(ctx, info, where)
@@ -1010,14 +1044,19 @@ def _gcp_from_info(ctx: ChainContext, info: Mapping[str, Any], where: str) -> Be
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 [])
+ return _gcp_impersonate(ctx, base, str(info["service_account_impersonation_url"]), info.get("delegates") or [], where)
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:
+def _gcp_impersonate(ctx: ChainContext, source: BearerToken, url: str, delegates: list, where: str) -> 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")
+ data = _exchange(ctx, "POST", url, {"content-type": "application/json", "authorization": f"Bearer {source.value}"}, body,
+ f"service account impersonation ({where}; generateAccessToken)",
+ f"the service account named in {where} must exist, and the source identity needs "
+ "roles/iam.serviceAccountTokenCreator on it "
+ "(roles/iam.workloadIdentityUser for a workload identity pool), and the IAM Credentials API "
+ "(iamcredentials.googleapis.com) enabled; a new grant can take several minutes to apply")
token = data.get("accessToken")
if not token:
raise AuthError("generateAccessToken: no accessToken")
@@ -1068,10 +1107,13 @@ def _gcp_external_account(ctx: ChainContext, info: Mapping[str, Any], where: str
"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")
+ data = _exchange(ctx, "POST", str(info.get("token_url") or _GCP_STS_URL), {"content-type": "application/json"}, body,
+ f"Google STS exchange ({where})",
+ "the workload identity pool refused the external token: check the provider's issuer, allowed "
+ "audience and attribute condition, and that the subject token is fresh")
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 _gcp_impersonate(ctx, token, str(info["service_account_impersonation_url"]), [], where)
return token
@@ -1088,10 +1130,23 @@ def _gcp_metadata_acquire(ctx: ChainContext) -> BearerToken | None:
return _bearer_from_oauth(_json_body(raw), ctx.now(), "GCE metadata")
+def _gcp_user_login_hint(where: str) -> str:
+ return (f"the saved Google login in {where} has expired or was revoked; run "
+ "`gcloud auth application-default login` (Google ends these sessions on its own schedule)")
+
+
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()
+ try:
+ token = ctx.run(["gcloud", "auth", "print-access-token"], 30.0).strip()
+ except AuthError as exc:
+ # gcloud's own words stay unread (AUTH-5: a command's stderr is not
+ # shown); the user runs the same command to see them.
+ raise AuthError("`gcloud auth print-access-token` failed: " + str(exc).split(_GUIDANCE_MARKER, 1)[0],
+ credential_hint="run `gcloud auth print-access-token` yourself to see gcloud's reason; usually "
+ "`gcloud auth login` fixes it (or `gcloud auth application-default login`, "
+ "which lm15 reads first)") from None
return BearerToken(token) if token else None
@@ -1150,26 +1205,100 @@ def _gcp_chain(policy: AccessPolicy) -> list[Rung]:
# ─── 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."""
+# Where a setting came from, beyond the caller and the setting's own env
+# variables (AUTH-10, amended 2026-09-26): the ``from`` vocabulary the
+# doctor prints and the harness pins. ``(None, "metadata")`` means the
+# metadata server would be asked, and this context is offline (the doctor):
+# unprobed, not absent.
+SettingSource = Tuple[Optional[str], str]
+
+_GCLOUD_CONFIG_NAME = re.compile(r"[a-z][-a-z0-9]*") # gcloud's own rule (named_configs.py:37); also keeps the name inside the directory
+
+
+def _gcloud_config_dir(ctx: ChainContext) -> str:
+ return (ctx.env.get("CLOUDSDK_CONFIG") or "~/.config/gcloud").rstrip("/")
+
+
+def gcloud_config_project(ctx: ChainContext) -> SettingSource | None:
+ """The project ``gcloud config get project`` prints, read from the files
+ gcloud reads (google-auth runs that command; lm15 reads the same files so
+ the doctor can say it offline): ``CLOUDSDK_CORE_PROJECT``, then
+ ``[core] project`` in ``$CLOUDSDK_CONFIG/configurations/config_<name>``,
+ ``<name>`` from ``CLOUDSDK_ACTIVE_CONFIG_NAME``, else the ``active_config``
+ file, else ``default`` (gcp-gcloud-named-configs-py.md, config.py:776-785,
+ named_configs.py:494-575; gcp-gcloud-configurations.md:397, :433-436).
+ Not read, stated: the installation-wide properties file and the
+ ``--configuration`` flag (neither exists outside a gcloud command)."""
+ value = (ctx.env.get("CLOUDSDK_CORE_PROJECT") or "").strip()
+ if value:
+ return value, "env:CLOUDSDK_CORE_PROJECT"
+ base = _gcloud_config_dir(ctx)
+ name = (ctx.env.get("CLOUDSDK_ACTIVE_CONFIG_NAME") or "").strip() or (ctx.read(f"{base}/active_config") or "").strip() or "default"
+ if not _GCLOUD_CONFIG_NAME.fullmatch(name):
+ return None
+ raw = ctx.read(f"{base}/configurations/config_{name}")
+ if not raw:
+ return None
+ parser = configparser.ConfigParser(interpolation=None)
+ try:
+ parser.read_string(raw)
+ except configparser.Error:
+ return None
+ value = (parser.get("core", "project", fallback="") or "").strip()
+ return (value, "gcloud-config") if value else None
+
+
+def _gcp_metadata_project(ctx: ChainContext) -> SettingSource | None:
+ """``project/project-id`` from the metadata server: the project a
+ Cloud Run service, GKE pod or VM runs in (gcp-google-auth-default-py.md
+ :391-420, compute-engine-py.md:395-409). Offline, unprobed."""
+ if (ctx.env.get("NO_GCE_CHECK") or "").lower() in ("1", "true"):
+ return None
+ if ctx.http is None:
+ return None, "metadata"
+ 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/project/project-id", {"Metadata-Flavor": "Google"}, None, 1.0)
+ except Exception: # noqa: BLE001 - not on Google Cloud: absent
+ return None
+ value = raw.decode("utf-8", "replace").strip() if status == 200 else ""
+ return (value, "metadata") if value and not any(c.isspace() or c in "/?#" for c in value) else None
+
+
+def profile_settings(policy: AccessPolicy, ctx: ChainContext) -> Callable[[str], SettingSource | None]:
+ """The setting values the cloud's own configuration carries, after the
+ caller and the setting's env variables (AUTH-10), as ``(value, from)``.
- def lookup(name: str) -> str | None:
+ AWS ``region``: the active profile (`~/.aws/config`, then
+ `~/.aws/credentials`). Google ``project`` (amended 2026-09-26, the
+ order google-auth and gcloud give it): the ``GOOGLE_APPLICATION_CREDENTIALS``
+ file's ``project_id`` (then its ``quota_project_id``); gcloud's active
+ configuration (``CLOUDSDK_CORE_PROJECT``, then the config file); the
+ ADC file's ``quota_project_id`` / ``project_id``; the metadata server.
+ Nothing for Azure."""
+
+ def lookup(name: str) -> SettingSource | 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
+ return (value, "aws-profile") if value else 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)
+ path = ctx.env.get("GOOGLE_APPLICATION_CREDENTIALS")
+ if path:
+ info = _gcp_credential_file(ctx, path) or {}
+ value = info.get("project_id") or info.get("quota_project_id")
+ if value:
+ return str(value), "adc-env"
+ found = gcloud_config_project(ctx)
+ if found:
+ return found
+ info = _gcp_credential_file(ctx, _adc_file_path(ctx)) or {}
+ value = info.get("quota_project_id") or info.get("project_id")
+ if value:
+ return str(value), "adc-file"
+ return _gcp_metadata_project(ctx)
return None
return lookup
@@ -1177,6 +1306,41 @@ def profile_settings(policy: AccessPolicy, ctx: ChainContext) -> Callable[[str],
# ─── Chains ──────────────────────────────────────────────────────────
+# What to do when a whole chain answers nothing: the one command that
+# creates a credential the chain reads, then the deployed alternatives.
+_NOTHING_FOUND_HINTS = {
+ "gcp-chain": "on a laptop: `gcloud auth application-default login`; elsewhere: set "
+ "GOOGLE_APPLICATION_CREDENTIALS to a service-account or workload-identity file, run on Google Cloud "
+ "with an attached service account, or pass api_keys={\"<provider>\": <token or callable>}",
+ "azure-chain": "on a laptop: `az login`; elsewhere: a managed identity, AZURE_TENANT_ID + AZURE_CLIENT_ID with a "
+ "secret or certificate, or api_keys={\"<provider>\": <token provider>}",
+ "aws-chain": "on a laptop: `aws sso login` or `aws configure`; elsewhere: the instance or container role, "
+ "AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, or api_keys={\"<provider>\": <credentials callable>}",
+}
+
+# How a cloud door's wire refusal (HTTP 401/403 from the model endpoint,
+# after a credential was obtained) is fixed: the identity lacks a role, a
+# new grant has not applied yet, the token expired, or the key is not a
+# Vertex key. Replaces the generic API-key guidance. ``sent`` is what
+# the adapter knows it sent: "key", "token", or None (a callable).
+def wire_auth_hint(policy: AccessPolicy, status: int | None, sent: str | None) -> str | None:
+ if policy.credential_policy != "gcp-chain":
+ return None
+ if status == 403:
+ return ("give the identity named above the Vertex AI User role (roles/aiplatform.user) on the project and "
+ "enable the Vertex AI API (aiplatform.googleapis.com); a new project or a new grant can take a few "
+ "minutes to apply. To use another identity: `gcloud auth application-default login`, or "
+ "GOOGLE_APPLICATION_CREDENTIALS=<file>")
+ if status != 401:
+ return None
+ if sent == "key":
+ return ("Google refused this API key: use a Vertex AI key (Cloud console > APIs & Services > Credentials, "
+ "restricted to the Vertex AI API or bound to a service account); Claude on Vertex takes no keys. "
+ "If the value is an access token that does not start with `ya29.`, pass BearerToken(value)")
+ return ("Google refused this access token: it expired (they last an hour; pass a callable, or let lm15's "
+ "chain refresh it) or it is not an OAuth token. Sign in again with "
+ "`gcloud auth application-default login`")
+
_CHAINS = {"aws-chain": _aws_chain, "azure-chain": _azure_chain, "gcp-chain": _gcp_chain}
# AUTH-1 named credentials (amended 2026-09-19): the rungs each name
@@ -1275,10 +1439,9 @@ def _gcp_typed(rung: Rung, name: str) -> Rung:
def named_rungs(policy: AccessPolicy, name: str) -> list[Rung]:
"""The rungs a named credential covers on this door, in chain order."""
if name not in NAMED_CREDENTIALS:
- raise NotConfiguredError(
- f"{policy.provider}: unknown named credential {name!r}; one of {', '.join(repr(n) for n in NAMED_CREDENTIALS)}",
- provider=policy.provider,
- )
+ from ..errors import named_credential_refusal
+
+ raise named_credential_refusal(policy.provider, name, cloud_door=True)
wanted = NAMED_RUNGS[policy.credential_policy][name]
rungs = [rung for rung in chain_for(policy) if rung.name in wanted]
if policy.credential_policy == "gcp-chain" and name in _GCP_NAMED_TYPES:
@@ -1372,12 +1535,20 @@ def resolve(policy: AccessPolicy, ctx: ChainContext, *, named: str | None = None
)
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"),
+ f" ({_probed_summary(policy, ctx, rungs)})",
provider=policy.provider,
env_keys=policy.env_keys,
+ credential_hint=_nothing_found_hint(policy),
)
+def _nothing_found_hint(policy: AccessPolicy) -> str | None:
+ hint = _NOTHING_FOUND_HINTS.get(policy.credential_policy)
+ if hint and policy.env_keys:
+ hint = f"set {policy.env_keys[0]}, or {hint}"
+ return hint.replace("<provider>", policy.provider) if hint else None
+
+
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.
diff --git a/dspy/_vendor/lm15/cloud/hosts.py b/dspy/_vendor/lm15/cloud/hosts.py
index 2624c3895..14cb00e1c 100644
--- a/dspy/_vendor/lm15/cloud/hosts.py
+++ b/dspy/_vendor/lm15/cloud/hosts.py
@@ -52,45 +52,86 @@ def resolve_settings(
env: Mapping[str, str] | None = None,
*,
provider: str = "",
- profile: Callable[[str], str | None] | None = None,
+ profile: Callable[[str], Any] | None = None,
endpoint: str | None = None,
+ sources: dict[str, str] | None = None,
+ unprobed_ok: bool = False,
+ problems: list[NotConfiguredError] | 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.
- With ``endpoint`` the settings only the URL root needed are optional."""
+ """Explicit values, then ``env`` (when given), then the cloud's own
+ configuration (``profile(name)`` → ``(value, from)``: the AWS profile's
+ ``region``; the Google project from the credential file, gcloud's
+ active configuration, the ADC file, the metadata server — AUTH-10),
+ then defaults. With ``endpoint`` the settings only the URL root needed
+ are optional.
+
+ ``sources``, when given, receives each setting's origin in the AUTH-10
+ ``from`` vocabulary (``explicit``, ``env:<VAR>``, ``adc-env``,
+ ``gcloud-config``, ``adc-file``, ``metadata``, ``aws-profile``,
+ ``default``). ``unprobed_ok`` (the offline doctor): a setting only a
+ network source could supply is left out and recorded as
+ ``unprobed:<from>`` instead of raising. ``problems``, when given
+ (the doctor), receives the missing-setting errors instead of a raise,
+ and the settings that did resolve are returned."""
out: dict[str, str] = {}
if host is None:
return dict(given or {})
given = dict(given or {})
relaxed = host.url_only_settings if endpoint else frozenset()
+ record = sources if sources is not None else {}
+ missing: NotConfiguredError | None = None
for setting in host.settings:
value = given.pop(setting.name, None)
+ origin = "explicit" if value else ""
if not value and env is not None:
for var in setting.env:
candidate = env.get(var)
if candidate:
- value = candidate
+ value, origin = candidate, f"env:{var}"
break
+ unprobed = ""
if not value and profile is not None:
- value = profile(setting.name)
- if not value:
- value = setting.default
+ found = profile(setting.name)
+ if isinstance(found, tuple):
+ if found[0]:
+ value, origin = found[0], found[1]
+ else:
+ unprobed = found[1]
+ elif found:
+ value, origin = found, "profile"
+ if not value and setting.default:
+ value, origin = setting.default, "default"
if not value:
if setting.name in relaxed:
continue
+ if unprobed and unprobed_ok:
+ record[setting.name] = f"unprobed:{unprobed}"
+ continue
hint = f"set {' or '.join(setting.env)}" if setting.env else f"pass settings={{'{setting.name}': ...}}"
+ if setting.name == "project":
+ # The Google project also comes from gcloud and the credential
+ # file; those were read and said nothing (AUTH-10).
+ hint += ", run `gcloud config set project <id>`, or pass settings={'project': ...}"
if setting.name in host.url_only_settings and host.endpoint_env:
hint += f", or the endpoint: {' or '.join(host.endpoint_env)}"
- raise NotConfiguredError(
+ record[setting.name] = "missing"
+ # Every setting is still resolved, so the doctor reports them all;
+ # the first missing one is the error.
+ missing = missing or NotConfiguredError(
f"{provider or 'host'}: setting {setting.name!r} is required and has no default; {hint}",
provider=provider or None,
credential_hint=hint,
)
+ continue
out[setting.name] = value
+ record[setting.name] = origin
unknown = sorted(given)
if unknown:
raise ValueError(f"{provider or 'host'}: unknown host setting(s) {unknown}; known: {list(host.setting_names)}")
+ if missing is not None:
+ if problems is None:
+ raise missing
+ problems.append(missing)
return out
diff --git a/dspy/_vendor/lm15/compat.py b/dspy/_vendor/lm15/compat.py
index 7c3a55410..e8cecda29 100644
--- a/dspy/_vendor/lm15/compat.py
+++ b/dspy/_vendor/lm15/compat.py
@@ -17,10 +17,13 @@ from __future__ import annotations
import dataclasses
from dataclasses import dataclass, field, fields
-from typing import Literal, TypeAlias, get_args
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, get_args
from .types import JsonObject
+if TYPE_CHECKING: # the generated __init__ signatures
+ from collections.abc import Mapping, Sequence
+
# ─── Shared helpers ──────────────────────────────────────────────────
@@ -335,7 +338,7 @@ class ResolvedOpenAIResponsesCompat:
_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",
+ "forced_tool_choice", "json_schema", "reasoning_efforts", "tool_result_media", "reasoning_off",
})
OpenAIChatInstructionRole = Literal["auto", "developer", "system"]
@@ -386,6 +389,16 @@ OpenAIChatUserField = Literal["auto", "user", "user_id", "safety_identifier"]
# 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"]
+# What an explicit reasoning-off becomes. "send" puts the dial's off word
+# on the wire (MAP-5). "lowest" is for a model that cannot stop reasoning
+# on a server that ACCEPTS the off word and reasons anyway — a paid no-op
+# with nothing on the response to say so (Together gpt-oss: reasoning hidden,
+# ~60 reasoning tokens billed; DeepInfra gpt-oss: run as low; Together
+# GLM-5.3: ignored — live 2026-09-26). "lowest" sends the lowest level
+# instead (the first of reasoning_efforts, else "low") and records the
+# substitution (MAP-13 decision 2026-09-14 §4.2, xAI's rule). A server that
+# refuses the off word loudly needs nothing here.
+OpenAIChatReasoningOff = Literal["auto", "send", "lowest"]
# 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
@@ -429,6 +442,7 @@ class OpenAIChatCompat:
cache_control: OpenAICacheControl | None = None
user_field: OpenAIChatUserField | None = None
forced_tool_choice: OpenAIChatForcedToolChoice | None = None
+ reasoning_off: OpenAIChatReasoningOff | None = field(default=None, kw_only=True)
json_schema: OpenAIChatJsonSchema | None = None
token_scoring: OpenAIChatTokenScoring | None = field(default=None, kw_only=True)
reasoning_efforts: OpenAIChatReasoningEfforts | None = field(default=None, kw_only=True)
@@ -440,7 +454,37 @@ class OpenAIChatCompat:
# 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)
+ # A knob's value: a policy word, or a level list for reasoning_efforts.
+ model_overrides: tuple[tuple[str, dict[str, str | tuple[str, ...]]], ...] = field(default=(), kw_only=True)
+
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ instruction_role: OpenAIChatInstructionRole | None = ...,
+ max_tokens_field: OpenAIChatMaxTokensField | None = ...,
+ stream_usage: OpenAIChatStreamUsage | None = ...,
+ tool_result_name: OpenAIToolResultName | None = ...,
+ assistant_after_tool_result: OpenAIChatAssistantAfterToolResult | None = ...,
+ thinking_format: OpenAIChatThinkingFormat | None = ...,
+ thinking_replay: OpenAIChatThinkingReplay | None = ...,
+ assistant_reasoning_content: OpenAIChatAssistantReasoningContent | None = ...,
+ strict_tools: OpenAIStrictTools | None = ...,
+ builtin_tools: OpenAIChatBuiltinTools | None = ...,
+ cache_control: OpenAICacheControl | None = ...,
+ user_field: OpenAIChatUserField | None = ...,
+ forced_tool_choice: OpenAIChatForcedToolChoice | None = ...,
+ json_schema: OpenAIChatJsonSchema | None = ...,
+ routing: dict[str, Any] | None = ...,
+ extensions: dict[str, Any] | None = ...,
+ *,
+ tool_result_media: ToolResultMedia | None = ...,
+ reasoning_off: OpenAIChatReasoningOff | None = ...,
+ token_scoring: OpenAIChatTokenScoring | None = ...,
+ reasoning_efforts: OpenAIChatReasoningEfforts | None = ...,
+ model_overrides: Sequence[tuple[str, Mapping[str, str | Sequence[str]]]] = ...,
+ ) -> None: ...
+ # END generated
def __post_init__(self) -> None:
overrides = []
@@ -476,6 +520,7 @@ class OpenAIChatCompat:
_check_literal_or_none(self.user_field, OpenAIChatUserField, "user_field")
_check_literal_or_none(self.token_scoring, OpenAIChatTokenScoring, "token_scoring")
_check_literal_or_none(self.forced_tool_choice, OpenAIChatForcedToolChoice, "forced_tool_choice")
+ _check_literal_or_none(self.reasoning_off, OpenAIChatReasoningOff, "reasoning_off")
_check_literal_or_none(self.json_schema, OpenAIChatJsonSchema, "json_schema")
if self.reasoning_efforts is not None:
from .types import REASONING_EFFORTS
@@ -493,7 +538,10 @@ class 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)
+ # Each knob was checked against _CHAT_OVERRIDABLE and its own
+ # literal (or tuple) at construction.
+ changes: dict[str, Any] = dict(knobs)
+ return dataclasses.replace(self, model_overrides=(), **changes)
return self
@classmethod
@@ -820,6 +868,133 @@ OPENAI_CHAT_PRESETS: dict[str, OpenAIChatCompat] = {
reasoning_efforts=("low", "high", "max"),
tool_result_media="images", # MAP-10: image tool results received (kimi-k2.6); a file part is 400
),
+ # ─── Open-model inference hosts (changes/2026-09-26-inference-hosts-live.md) ───
+ #
+ # DeepInfra, Together AI, Fireworks AI and Parasail each serve many
+ # vendors' open models behind one Chat Completions root. One policy fits
+ # the four, measured live 2026-09-26 on gpt-oss, DeepSeek V4.1, GLM-5.3,
+ # Qwen3 and Llama 3.3 (lm15-contract/research/providers/<id>/README.md):
+ #
+ # - thinking_format="reasoning_effort": the one dial all four honour for
+ # effort; "none" is the documented off (DeepInfra reasoning.md, Together
+ # reasoning.md). Fireworks rejects the `reasoning: {...}` object (400
+ # "Extra inputs"), so the OpenRouter shape is wrong there. Whether a
+ # MODEL can stop reasoning is the model's business: Fireworks and
+ # Parasail refuse "none" loudly where it cannot (gpt-oss, GLM-5.3);
+ # DeepInfra and Together accept it and reason anyway on those models.
+ # Stated in each dossier; not guessed from model names here.
+ # - thinking_replay="native": reasoning goes back as `reasoning_content`.
+ # A code word planted in a replayed trace was recalled through that
+ # field on every host that reads a replay at all; Fireworks rejects the
+ # alternative `reasoning` field (400), so one field serves all four.
+ # The dialect default ("as_text") would paste the trace into the
+ # visible assistant text of the next request.
+ # - max_completion_tokens: honoured by all four (finish_reason "length"
+ # at the cap); stream_options.include_usage honoured by all four.
+ # - cache_control="none": caching is automatic on all four; none takes the
+ # OpenAI key/retention pair in the shape this dialect sends (DeepInfra's
+ # retention is prompt_cache_options.ttl 5m|1h, a mapping not made yet),
+ # so a key or a long retention is dropped WITH a record (MAP-13).
+ # - tool_result_media (MAP-10, live 2026-09-26, research/providers/
+ # media_tool_results.py): Fireworks (GLM-5.3-Flash) and Parasail
+ # (Qwen3-VL-8B) read an image inside a tool result -> "images"
+ # (documents untested, so they raise). DeepInfra answers 422 "Input
+ # should be a valid string" on messages.2.tool.content -> "reject".
+ # Together: open cell (the account hit its credit limit during the
+ # pass; its serverless vision model is Kimi-K3) -> "reject" until a
+ # receipt.
+ "deepinfra": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject",
+ # Forced tool choice depends on the model here. Survey of 24 models
+ # (research/providers/deepinfra/tool_choice_survey.py, live
+ # 2026-09-26: required twice, a named function, none, and an
+ # unprompted-call control): the 14 below honour all three forms;
+ # Llama 3.x, Qwen3-235B-2507, Qwen3-Coder, Qwen3-30B/14B, Mistral
+ # Small, Gemma 4 and gpt-oss ignore them (text, no call); Qwen3.8-
+ # Flash answers 500; MiniMax M2.7, GLM-4.7 and Seed 2.0 ignore
+ # `none`. MAP-8: a silent cell raises, so the host default is reject
+ # (an untested model is refused, never silently ignored) and only the
+ # receipted models are let through. Ratified 2026-09-26. The ids are
+ # prefixes, so a suffixed variant of a listed model (-Turbo, -0731)
+ # inherits its entry.
+ forced_tool_choice="reject",
+ model_overrides=(
+ ("openai/gpt-oss", {"reasoning_off": "lowest"}),
+ *((model, {"forced_tool_choice": "send"}) for model in (
+ "deepseek-ai/DeepSeek-V3.2",
+ "deepseek-ai/DeepSeek-V4-Flash",
+ "deepseek-ai/DeepSeek-V4.1-Flash",
+ "zai-org/GLM-5.3-Flash",
+ "moonshotai/Kimi-K2.6",
+ "meta-llama/Llama-4-Scout-17B-16E-Instruct",
+ "Qwen/Qwen3.6-27B",
+ "Qwen/Qwen3-Next-80B-A3B-Instruct",
+ "nvidia/NVIDIA-Nemotron-3.5-Lightning",
+ "ibm-granite/granite-4.2-8b",
+ "XiaomiMiMo/MiMo-V2.6-Flash",
+ "tencent/Hy3",
+ "google/gemini-3.1-flash-lite",
+ "anthropic/claude-haiku-4-5",
+ )),
+ ),
+ ),
+ # Together, gpt-oss only (live 2026-09-26; Llama and DeepSeek behave):
+ # - a forced tool choice answers HTTP 500 "Internal server error" every
+ # time. A 500 is classed retryable, so a caller's retry loop would
+ # spin on a request that cannot succeed: refuse it before the wire.
+ # - an effort word outside low|medium|high (xhigh, max, and even
+ # "bogus") is accepted and run at the default, medium — fewer reasoning
+ # tokens than `high` for a request that asked for `max`. Declaring the
+ # levels clamps to the nearest one with a record (MAP-13), as for
+ # Moonshot's kimi-k3. DeepSeek on Together refuses unknown words
+ # loudly (400), and the other three hosts map xhigh/max to high or
+ # refuse, so nothing is declared host-wide.
+ "together": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="reject",
+ model_overrides=(
+ ("openai/gpt-oss", {"forced_tool_choice": "reject", "reasoning_efforts": ("low", "medium", "high"),
+ "reasoning_off": "lowest"}),
+ ("zai-org/GLM-5.3", {"reasoning_off": "lowest"}),
+ ),
+ ),
+ "fireworks": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="images",
+ ),
+ "parasail": OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ thinking_replay="native",
+ tool_result_name="omit",
+ strict_tools="omit",
+ cache_control="none",
+ tool_result_media="images",
+ ),
}
@@ -849,6 +1024,14 @@ OPENAI_CHAT_PRESET_BASE_URLS: dict[str, str] = {
# 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",
+ # The open-model inference hosts, each its documented OpenAI-compatible root:
+ # docs.deepinfra.com chat--overview.md (the /v1/openai root, not /v1),
+ # docs.together.ai openai-compatibility.md, docs.fireworks.ai
+ # openai-compatibility.md, docs.parasail.io authentication.md.
+ "deepinfra": "https://api.deepinfra.com/v1/openai",
+ "together": "https://api.together.ai/v1",
+ "fireworks": "https://api.fireworks.ai/inference/v1",
+ "parasail": "https://api.parasail.io/v1",
}
@@ -881,6 +1064,7 @@ class ResolvedOpenAIChatCompat:
cache_control: Literal["none", "openai", "openai_implicit", "anthropic"] = "openai"
user_field: Literal["user", "user_id"] = "user"
forced_tool_choice: Literal["send", "reject"] = "send"
+ reasoning_off: Literal["send", "lowest"] = field(default="send", kw_only=True)
json_schema: Literal["send", "reject"] = "send"
token_scoring: Literal["none", "logprob_token_ids"] = field(default="none", kw_only=True)
reasoning_efforts: tuple[str, ...] | None = field(default=None, kw_only=True)
@@ -905,6 +1089,7 @@ _CHAT_AUTO_DEFAULTS: dict[str, str] = {
"forced_tool_choice": "send",
"json_schema": "send",
"token_scoring": "none",
+ "reasoning_off": "send",
}
@@ -919,7 +1104,7 @@ def merge_openai_chat_compat(
if override is None:
return base
- kwargs = {}
+ kwargs: dict[str, Any] = {}
for f in fields(OpenAIChatCompat):
value = getattr(override, f.name)
if f.name == "extensions":
@@ -1017,6 +1202,24 @@ class AnthropicCompat:
model_prefixes: tuple[str, ...] | None = None
extensions: JsonObject | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ thinking_format: AnthropicThinkingFormat | None = ...,
+ cache_control: AnthropicCacheControl | None = ...,
+ structured_output: AnthropicStructuredOutput | None = ...,
+ parallel_tool_calls: AnthropicParallelToolCalls | None = ...,
+ model_prefixes: Sequence[str] | None = ...,
+ extensions: dict[str, Any] | None = ...,
+ *,
+ thinking_replay: AnthropicThinkingReplay | None = ...,
+ sampling_params: AnthropicSamplingParams | None = ...,
+ tool_result_media: ToolResultMedia | None = ...,
+ reasoning_efforts: tuple[str, ...] | None = ...,
+ ) -> None: ...
+ # END generated
+
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")
@@ -1179,7 +1382,7 @@ def merge_openai_responses_compat(
if override is None:
return base
- kwargs = {}
+ kwargs: dict[str, Any] = {}
for f in fields(OpenAIResponsesCompat):
value = getattr(override, f.name)
if f.name == "extensions":
diff --git a/dspy/_vendor/lm15/doctor.py b/dspy/_vendor/lm15/doctor.py
index 63236e489..5e97bb0dd 100644
--- a/dspy/_vendor/lm15/doctor.py
+++ b/dspy/_vendor/lm15/doctor.py
@@ -95,6 +95,12 @@ class AuthReport:
# (``"base_urls"``, an env variable name, or ``"template"``).
base_url: str | None = None
base_url_source: str | None = None
+ # Where each setting came from (AUTH-10 ``from`` vocabulary, amended
+ # 2026-09-26): ``explicit``, ``env:<VAR>``, ``adc-env``,
+ # ``gcloud-config``, ``adc-file``, ``metadata``, ``aws-profile``,
+ # ``default``; ``unprobed:metadata`` when only the metadata server could
+ # answer and the doctor does not use the network.
+ setting_sources: tuple[tuple[str, str], ...] = ()
@property
def selected(self) -> AuthStep | None:
@@ -117,8 +123,14 @@ class AuthReport:
lines.append(f" configured: probably — {', '.join(s.source for s in unprobed)} (unprobed offline)")
else:
lines.append(" configured: no")
+ origins = dict(self.setting_sources)
for name, value in self.settings:
- lines.append(f" setting {name}: {value}")
+ origin = origins.get(name)
+ shown = f"env ${origin[4:]}" if origin and origin.startswith("env:") else _SETTING_FROM.get(origin or "", origin)
+ lines.append(f" setting {name}: {value}" + (f" (from {shown})" if origin else ""))
+ for name, origin in self.setting_sources:
+ if origin.startswith("unprobed:"): # "missing" is the error line below
+ lines.append(f" setting {name}: not found offline; {_SETTING_FROM.get(origin, origin)} is asked at request time")
if self.base_url:
origin = f" (from {self.base_url_source})" if self.base_url_source else ""
lines.append(f" base url: {self.base_url}{origin}")
@@ -128,6 +140,18 @@ class AuthReport:
return self.describe()
+_SETTING_FROM = {
+ "explicit": "settings",
+ "adc-env": "the GOOGLE_APPLICATION_CREDENTIALS file",
+ "gcloud-config": "gcloud's active configuration",
+ "adc-file": "the gcloud application default credentials file",
+ "metadata": "the Google Cloud metadata server",
+ "unprobed:metadata": "the Google Cloud metadata server",
+ "aws-profile": "the active AWS profile",
+ "default": "default",
+}
+
+
def _expiry_detail(credential: LocalOAuthCredential) -> str:
if credential.expires_at is None:
return "no recorded expiry"
@@ -244,6 +268,10 @@ def explain_auth(
known = sorted(PROVIDERS)
raise ValueError(f"Unknown provider {provider!r}. Known providers: {', '.join(known)}")
+ if config is not None and config.auth is not None:
+ return _with_backend_settings(_explain_managed(canonical, config, api_keys=api_keys, env=env),
+ settings, env)
+
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
@@ -251,14 +279,14 @@ def explain_auth(
return _explain_cloud(canonical, env=env, api_keys=api_keys, files=files, home=home, settings=settings,
credential=credential, base_url=base_url)
if credential is not None:
- raise NotConfiguredError(
- f"{canonical}: credential={credential!r} names a cloud identity, and this is not a cloud door",
- provider=canonical,
- )
+ from .errors import named_credential_refusal
+
+ raise named_credential_refusal(canonical, credential, cloud_door=False)
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")
+ return _with_backend_settings(AuthReport(provider=canonical, steps=(step,), configured=step.state == "selected"),
+ settings, env)
config = RouterConfig(env=env, api_keys=api_keys)
environment = env if env is not None else os.environ
@@ -286,21 +314,33 @@ def explain_auth(
)
)
+ blocked = False
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.
+ # above can shadow it. An unusable or signed-out login BLOCKS the
+ # env keys (R3, 2026-09-22): they show as shadowed, and nothing is
+ # selected.
+ from .auth import xai_stored_state
+
step = _xai_oauth_step(xai_credentials_path, shadowed=selected)
+ state_word = xai_stored_state(xai_credentials_path)
+ if state_word == "logged_out" and not selected:
+ step = AuthStep(kind="oauth-file", source=step.source, detail="signed out (marker present)", state="absent")
+ blocked = True
+ elif state_word == "unusable" and not selected:
+ blocked = True
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
+ state = "shadowed" if (selected or blocked) else "selected"
+ detail = "set (value never shown)"
+ if blocked and not selected:
+ detail = "set, blocked by the failed/signed-out subscription (pass it explicitly to use it)"
+ steps.append(AuthStep(kind=f"env:{key}", source=f"env ${key}", detail=detail, state=state))
+ selected = selected or not blocked
else:
steps.append(
AuthStep(kind=f"env:{key}", source=f"env ${key}", detail="not set", state="absent")
@@ -321,7 +361,82 @@ def explain_auth(
)
selected = True
- return AuthReport(provider=canonical, steps=tuple(steps), configured=selected)
+ return _with_backend_settings(AuthReport(provider=canonical, steps=tuple(steps), configured=selected),
+ settings, env)
+
+
+def _with_backend_settings(report: AuthReport, settings: Mapping[str, str] | None,
+ env: Mapping[str, str] | None) -> AuthReport:
+ """A door without a host prints its backend settings the way a cloud
+ door prints its host settings (AUTH-7; AUTH-10 amended 2026-09-30):
+ the Claude Code release the claude-code door claims, and where that
+ came from — the value a model's minimum-version refusal is about."""
+ import os
+ from dataclasses import replace
+
+ from .access import resolve_backend_settings
+
+ definition = _bound_definition(report.provider)
+ policy = (definition.access if definition is not None and definition.bound
+ else getattr(ADAPTERS.get(report.provider), "manifest", None))
+ if policy is None or policy.host is not None or (not policy.backend_settings and not settings):
+ return report
+ sources: dict[str, str] = {}
+ values = resolve_backend_settings(policy, settings, env if env is not None else os.environ, sources=sources)
+ return replace(report, settings=tuple(values.items()), setting_sources=tuple(sources.items()))
+
+
+def _explain_managed(provider: str, config: RouterConfig, *, api_keys, env) -> AuthReport:
+ """AUTH-15 mode B, rung by rung: the explicit entry, the named cloud
+ identity, the scope's saved connection; environment keys are shown
+ and marked not consulted. Store reads only, no renewal (AUTH-7)."""
+ import os
+
+ from .router import _credentials_entry
+
+ auth = config.auth
+ walk = 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(walk, provider)
+ if entry is not None:
+ steps.append(AuthStep(kind="api_keys", source=_entry_source(provider, 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"))
+ named = _credentials_entry(config, provider)
+ if named is not None:
+ steps.append(AuthStep(kind="named_cloud", source=f'named credential "{named}"', detail="explicit",
+ state="shadowed" if selected else "selected"))
+ selected = True
+ status = auth.status(provider)
+ if status.connection is not None:
+ detail = f"{status.connection.label} ({status.usability}" + (f", expires {status.expires_at}" if status.expires_at else "") + ")"
+ state = "shadowed" if selected else ("selected" if status.ready else "absent")
+ steps.append(AuthStep(kind="connection", source=f"saved connection {status.connection.id}", detail=detail, state=state))
+ selected = selected or state == "selected"
+ else:
+ detail = "signed out (marker present)" if status.logged_out else "none saved in this scope"
+ steps.append(AuthStep(kind="connection", source=f"saved connection in {auth.store.description}", detail=detail,
+ state="absent"))
+ for key in _declared_env_keys(provider, ADAPTERS):
+ if environment.get(key):
+ steps.append(AuthStep(kind=f"env:{key}", source=f"env ${key}",
+ detail="set, not consulted under a managed Auth (pass it explicitly to use it)",
+ state="shadowed"))
+ else:
+ steps.append(AuthStep(kind=f"env:{key}", source=f"env ${key}", detail="not set", state="absent"))
+ from .registry import PROVIDERS
+
+ definition = PROVIDERS.get(provider)
+ if definition is not None and definition.placeholder_key is not None and not status.logged_out:
+ state = "shadowed" if selected else "selected"
+ steps.append(AuthStep(kind="placeholder", source="local-server placeholder key",
+ detail=f"preset default for keyless {provider} servers", state=state))
+ selected = True
+ return AuthReport(provider=provider, steps=tuple(steps), configured=selected)
def _entry_source(provider: str, entry: str | None) -> str:
@@ -368,6 +483,7 @@ def _explain_cloud(
entry = _api_keys_source(config, canonical)
has_entry = entry is not None
resolved: dict[str, str] = {}
+ setting_sources: dict[str, str] = {}
setting_error: str | None = None
ctx = ChainContext(
env=environment,
@@ -383,13 +499,18 @@ def _explain_cloud(
endpoint_source = next(var for var in policy.host.endpoint_env if (environment.get(var) or "").strip())
endpoint_source = f"env ${endpoint_source}"
try:
+ problems: list[NotConfiguredError] = []
resolved = resolve_settings(policy.host, settings, environment, provider=canonical,
- profile=profile_settings(policy, ctx), endpoint=base_url)
+ profile=profile_settings(policy, ctx), endpoint=base_url,
+ sources=setting_sources, unprobed_ok=True, problems=problems)
+ if problems:
+ setting_error = str(problems[0]).splitlines()[0]
except NotConfiguredError as exc:
setting_error = str(exc).splitlines()[0]
ctx.settings = resolved
rendered: str | None = None
- if policy.host is not None and setting_error is None:
+ pending = any(origin.startswith("unprobed:") for origin in setting_sources.values())
+ if policy.host is not None and setting_error is None and not pending: # nothing missing, nothing unprobed
try:
rendered = render_base_url(policy.host, resolved, base_url, provider=canonical)
except NotConfiguredError as exc:
@@ -417,4 +538,5 @@ def _explain_cloud(
provider=canonical, steps=tuple(out), configured=configured, settings=shown,
named=credential, named_meaning=named_meaning(policy, credential) if credential else None,
base_url=rendered, base_url_source=(endpoint_source or "template") if rendered else None,
+ setting_sources=tuple(sorted(setting_sources.items())),
)
diff --git a/dspy/_vendor/lm15/errors.py b/dspy/_vendor/lm15/errors.py
index ff51751d7..69edfab8d 100644
--- a/dspy/_vendor/lm15/errors.py
+++ b/dspy/_vendor/lm15/errors.py
@@ -113,6 +113,83 @@ class LockTimeoutError(LM15Error):
super().__init__(message, **kwargs)
+# spec/auth.md AUTH-24 (ratified core 2026-09-22): the closed reasons a
+# managed-auth lifecycle operation can fail with. None is a provider HTTP
+# 401; none is automatically retryable.
+AUTH_OPERATION_REASONS: frozenset[str] = frozenset({
+ "interaction_required", "method_unavailable", "connection_exists",
+ "login_in_progress", "login_required", "connection_changed", "login_denied",
+ "login_expired", "invalid_login_state", "attempt_unavailable", "indeterminate",
+ "storage_unavailable", "unsupported_store_version", "selection_mismatch",
+ "credential_rejected",
+})
+AUTH_OPERATION_STAGES: frozenset[str] = frozenset({
+ "discovery", "reservation", "interaction", "authorization", "polling", "exchange",
+ "persistence", "resolution", "renewal", "verification", "catalog", "dispatch",
+})
+AUTH_OPERATION_RECOVERIES: frozenset[str] = frozenset({
+ "provide_input", "choose_method", "resume_attempt", "inspect_attempt", "restart_login",
+ "select_connection", "repair_storage", "operator_action", "none",
+})
+AUTH_COMMIT_STATES: frozenset[str] = frozenset({"not_committed", "committed", "unknown"})
+
+
+class AuthOperationError(LM15Error):
+ """A managed-auth lifecycle operation failed locally (AUTH-24).
+
+ Root-level, beside :class:`TransportError`: nothing here is a provider
+ HTTP reply, and nothing here is safe to retry blindly. ``reason`` is
+ one of :data:`AUTH_OPERATION_REASONS`; ``stage`` names where the
+ operation stopped; ``commit_state`` says whether the store changed
+ (``committed``, ``not_committed``, or ``unknown`` after an interrupted
+ write); ``recovery`` is guidance for the caller, never an instruction
+ to retry. ``provider`` is the route; ``connection_id`` and
+ ``attempt_id`` are safe references, never secrets.
+
+ The message is for people. Programs match on ``reason``.
+ """
+
+ default_code = "auth_operation"
+
+ def __init__(
+ self,
+ message: str = "",
+ *,
+ reason: str,
+ stage: str = "resolution",
+ commit_state: str = "not_committed",
+ recovery: str = "none",
+ operation: str | None = None,
+ connection_id: str | None = None,
+ attempt_id: str | None = None,
+ method_id: str | None = None,
+ **kwargs,
+ ) -> None:
+ if reason not in AUTH_OPERATION_REASONS:
+ raise ValueError(f"AuthOperationError: unknown reason {reason!r}")
+ if stage not in AUTH_OPERATION_STAGES:
+ raise ValueError(f"AuthOperationError: unknown stage {stage!r}")
+ if commit_state not in AUTH_COMMIT_STATES:
+ raise ValueError(f"AuthOperationError: unknown commit_state {commit_state!r}")
+ if recovery not in AUTH_OPERATION_RECOVERIES:
+ raise ValueError(f"AuthOperationError: unknown recovery {recovery!r}")
+ self.reason = reason
+ self.stage = stage
+ self.commit_state = commit_state
+ self.recovery = recovery
+ self.operation = operation
+ self.connection_id = connection_id
+ self.attempt_id = attempt_id
+ self.method_id = method_id
+ super().__init__(message, **kwargs)
+
+ def __repr__(self) -> str:
+ return (
+ f"AuthOperationError(reason={self.reason!r}, stage={self.stage!r}, "
+ f"commit_state={self.commit_state!r}, provider={self.provider!r})"
+ )
+
+
class CollectionLimitError(LM15Error):
"""A local turn collector reached its budget, not a provider failure.
@@ -247,7 +324,7 @@ class ProviderError(LM15Error):
)
if item
)
- base = self.message or self.code
+ base = self.message or self.code or ""
head, sep, tail = base.partition("\n\n")
suffix = f" ({context})" if context else ""
details = diagnostics_text(self.rate_limit_headers, self.retry_after)
@@ -411,6 +488,35 @@ class NotConfiguredError(ConfigurationError):
super().__init__(message, **kwargs)
+def named_credential_refusal(provider: str, value: str, *, cloud_door: bool) -> NotConfiguredError:
+ """The refusal of a ``credential=`` value this door cannot use (AUTH-1
+ named credentials, amended 2026-10-10).
+
+ ``credential=`` takes one of the four cloud identity names. Any other
+ value is almost always an API key put in the wrong argument, so it is
+ never repeated (AUTH-5) and the message says where a key goes. One of
+ the four names on a door without a cloud chain is safe to repeat.
+ """
+ from .features import NAMED_CREDENTIALS
+
+ names = ", ".join(repr(n) for n in NAMED_CREDENTIALS)
+ if value in NAMED_CREDENTIALS:
+ return NotConfiguredError(
+ f"{provider}: credential={value!r} names a cloud identity, and {provider} is not a cloud door",
+ provider=provider,
+ credential_hint="pass the key as api_key=... (or RouterConfig(api_keys={...})), or use the cloud door of this provider",
+ )
+ if cloud_door:
+ what = f"{provider}: unknown named credential (one of {names})"
+ else:
+ what = f"{provider}: credential= takes the name of a cloud identity ({names}), and {provider} is not a cloud door"
+ return NotConfiguredError(
+ f"{what}; the value given is not shown, because it may be a key",
+ provider=provider,
+ credential_hint="if that value is your API key, pass it as api_key=... (or RouterConfig(api_keys={...}))",
+ )
+
+
class UnknownModelError(ConfigurationError):
"""The router found no provider for a model string.
@@ -520,6 +626,88 @@ def with_credential_hint(error: ProviderError, hint: str) -> ProviderError:
# ─── HTTP status → error class mapping ───────────────────────────────
+# MAP-15: the pinned forms of a provider's "no such model" answer that carry no
+# model-specific code and no not-found class (lm15-contract
+# spec/model-not-found.json, carried verbatim; each form has a live receipt).
+MODEL_NOT_FOUND_FORMS: tuple[dict[str, str], ...] = (
+ {"code": "not_found_error", "prefix": "model: "}, # Anthropic, Claude Code
+ {"code": "invalid_request_error", "contains": "The supported API model names are "}, # DeepSeek
+ {"code": "1211"}, # Z.AI: Unknown Model
+ {"code": "1214", "prefix": "modelCode: "}, # Z.AI: the model field is invalid
+ {"code": "400", "suffix": " is not a valid model ID"}, # OpenRouter
+ {"code": "invalid-argument", "prefix": "Model not found: "}, # xAI (2026-09-01)
+ {"code": "validation_error", "contains": "The provided model identifier is invalid"}, # Bedrock Chat
+ {"code": "invalid_request_error", "prefix": "Deployment ", "suffix": " doesn't exist or isn't accessible."}, # Parasail
+)
+
+
+def is_pinned_model_not_found(provider_code: str | None, message: str | None) -> bool:
+ """True when the error is one of the pinned MAP-15 forms: the provider
+ code matches exactly and the message passes every text test the form
+ gives. Never widened beyond the captured answers."""
+ if not provider_code:
+ return False
+ text = message or ""
+ for form in MODEL_NOT_FOUND_FORMS:
+ if form["code"] != provider_code:
+ continue
+ if "prefix" in form and not text.startswith(form["prefix"]):
+ continue
+ if "contains" in form and form["contains"] not in text:
+ continue
+ if "suffix" in form and not text.endswith(form["suffix"]):
+ continue
+ return True
+ return False
+
+
+# MAP-18: the pinned forms of a provider's "this key is not valid" answer that
+# arrive without HTTP 401 (lm15-contract spec/auth-failed.json, carried
+# verbatim; each form has a live receipt). A form with "reason" also needs
+# that reason in a Google google.rpc.ErrorInfo detail of the body.
+AUTH_FAILED_FORMS: tuple[dict[str, str], ...] = (
+ {"code": "INVALID_ARGUMENT", "reason": "API_KEY_INVALID"}, # Gemini (2026-10-10)
+ {"code": "invalid-argument", "prefix": "Incorrect API key provided"}, # xAI (2026-10-10)
+)
+
+
+def google_error_reasons(error: object) -> tuple[str, ...]:
+ """The ``reason`` of every ``google.rpc.ErrorInfo`` in a Google error
+ envelope's ``details`` (the inner ``error`` object), in order."""
+ if not isinstance(error, dict) or not isinstance(error.get("details"), list):
+ return ()
+ return tuple(
+ detail["reason"]
+ for detail in error["details"]
+ if isinstance(detail, dict)
+ and str(detail.get("@type", "")).endswith("google.rpc.ErrorInfo")
+ and isinstance(detail.get("reason"), str)
+ )
+
+
+def is_pinned_auth_failure(provider_code: str | None, message: str | None, reasons: tuple[str, ...] = ()) -> bool:
+ """True when the error is one of the pinned MAP-18 forms: the provider
+ code matches exactly, the message passes every text test the form
+ gives, and the form's ``reason``, when it names one, is among
+ ``reasons``. Never widened beyond the captured answers."""
+ if not provider_code:
+ return False
+ text = message or ""
+ for form in AUTH_FAILED_FORMS:
+ if form["code"] != provider_code:
+ continue
+ if "reason" in form and form["reason"] not in reasons:
+ continue
+ if "prefix" in form and not text.startswith(form["prefix"]):
+ continue
+ if "contains" in form and form["contains"] not in text:
+ continue
+ if "suffix" in form and not text.endswith(form["suffix"]):
+ continue
+ return True
+ return False
+
+
def map_http_error(
status: int,
message: str,
@@ -579,6 +767,7 @@ _CLASS_TO_CODE: dict[type[LM15Error], str] = {
AmbiguousModelError: "ambiguous_model",
TransportError: "transport",
LockTimeoutError: "lock_timeout",
+ AuthOperationError: "auth_operation",
StreamAssemblyError: "stream_assembly",
CollectionLimitError: "collection_limit",
ProviderError: "provider",
diff --git a/dspy/_vendor/lm15/features.py b/dspy/_vendor/lm15/features.py
index a3f0eca20..988a830ad 100644
--- a/dspy/_vendor/lm15/features.py
+++ b/dspy/_vendor/lm15/features.py
@@ -5,7 +5,8 @@ lm15.features — Provider capability and endpoint declarations.
from __future__ import annotations
from dataclasses import dataclass, field, replace
-from typing import Literal, Mapping
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Literal, Mapping
# How a provider's credential is obtained (spec/auth.md AUTH-1):
#
@@ -30,6 +31,10 @@ from typing import Literal, Mapping
#
# The router and doctor derive their behavior from this declaration; there
# is no parallel provider-name list to keep in sync.
+# - "connection" — a managed account route (spec/auth.md AUTH-1, ratified
+# core 2026-09-22): an accepted explicit credential or a scoped
+# managed Auth selection; never an environment key, never a
+# foreign CLI file. Additive: no existing route was moved to it.
# - "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
@@ -37,9 +42,9 @@ from typing import Literal, Mapping
# 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"]
+CredentialPolicy = Literal["key", "oauth", "oauth-unless-explicit", "connection", "aws-chain", "azure-chain", "gcp-chain"]
CREDENTIAL_POLICIES: frozenset[str] = frozenset(
- {"key", "oauth", "oauth-unless-explicit", "aws-chain", "azure-chain", "gcp-chain"}
+ {"key", "oauth", "oauth-unless-explicit", "connection", "aws-chain", "azure-chain", "gcp-chain"}
)
_CLOUD_CHAINS: frozenset[str] = frozenset({"aws-chain", "azure-chain", "gcp-chain"})
@@ -154,6 +159,22 @@ class HostSpec:
sigv4_service: str | None = None
endpoint_env: tuple[str, ...] = ()
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ base_url: str,
+ settings: Sequence[HostSetting] = ...,
+ paths: Mapping[str, str] = ...,
+ model_in: ModelPlacement = ...,
+ anthropic_version_in: str = ...,
+ stream_framing: StreamFraming = ...,
+ required_headers: Sequence[tuple[str, str]] = ...,
+ sigv4_service: str | None = ...,
+ endpoint_env: Sequence[str] = ...,
+ ) -> None: ...
+ # END generated
+
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)}")
@@ -251,6 +272,12 @@ class AccessPolicy:
prompt / instructions (Claude Code, Codex).
``base_url`` this access path's default base URL, when it is
not the dialect's.
+ ``backend_settings`` the ``backend_options`` a caller may set on a door
+ without a host (spec/auth.md AUTH-10, amended
+ 2026-09-30): each names a ``backend_options`` key and
+ the env variables the router consults for it; its
+ default is the table's ``backend_options`` value.
+ The subscription doors declare ``client_version``.
"""
provider: str
@@ -267,6 +294,7 @@ class AccessPolicy:
backend_options: Mapping[str, str] = field(default_factory=dict)
system_prefix: str | None = None
base_url: str | None = None
+ backend_settings: tuple[HostSetting, ...] = field(default=(), kw_only=True)
# Keep the original positional API, including pattern matching. The legacy
# header is a constructor input/property, NOT a second stored authority.
@@ -280,20 +308,21 @@ class AccessPolicy:
self,
provider: str,
supports: EndpointSupport | None = None,
- auth_modes: tuple[str, ...] = (),
- enterprise_variants: tuple[str, ...] = (),
- env_keys: tuple[str, ...] = (),
+ auth_modes: Sequence[str] = (),
+ enterprise_variants: Sequence[str] = (),
+ env_keys: Sequence[str] = (),
credential_policy: CredentialPolicy = "key",
auth_header: AuthHeader | None = None,
- headers: tuple[tuple[str, str], ...] = (),
+ headers: Sequence[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",),
+ auth_scheme: AuthScheme | Sequence[AuthScheme] = ("bearer",),
host: HostSpec | None = None,
+ backend_settings: Sequence[HostSetting] = (),
) -> None:
# None means the legacy spelling was omitted (the effective default
# remains bearer). An explicit legacy header overrides the scheme input:
@@ -318,6 +347,7 @@ class AccessPolicy:
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)
+ object.__setattr__(self, "backend_settings", backend_settings)
self.__post_init__()
def __post_init__(self) -> None:
@@ -344,6 +374,17 @@ class AccessPolicy:
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))
+ object.__setattr__(self, "backend_settings", tuple(self.backend_settings))
+ for setting in self.backend_settings:
+ # A backend setting's default is the table's backend_options
+ # value: one authority for the value a door sends by default.
+ if setting.default is not None:
+ raise ValueError(f"{self.provider}: backend setting {setting.name!r} takes its default "
+ "from backend_options, not HostSetting.default")
+ if setting.name not in self.backend_options:
+ raise ValueError(f"{self.provider}: backend setting {setting.name!r} has no backend_options default")
+ if self.backend_settings and self.host is not None:
+ raise ValueError(f"{self.provider}: a door with a host declares its settings on the host")
@property
def auth_header(self) -> AuthHeader:
diff --git a/dspy/_vendor/lm15/interactive.py b/dspy/_vendor/lm15/interactive.py
new file mode 100644
index 000000000..780ad5b2c
--- /dev/null
+++ b/dspy/_vendor/lm15/interactive.py
@@ -0,0 +1,226 @@
+"""
+lm15.interactive — ``connect()``: get ready to make model requests.
+
+The explicitly interactive module (spec/auth.md AUTH-23). Import it when
+a person is at a terminal; a server never should — ``connect()`` fails
+before reading any secret when there is no terminal and no UI was given.
+
+ from lm15 import Message
+ from lm15.interactive import connect
+
+ with connect() as lm:
+ answer = lm.complete(messages=[Message.user("Explain drought stress.")])
+ print(answer.text)
+
+What it does, in order: shows where connections are saved; offers the
+saved connections and "connect another" (subscriptions first — an
+explicit key or a named cloud identity is deliberate authority, an
+ambient environment key is offered only as an explicit choice, never
+taken silently: R2/R3); runs the chosen login or setup; fetches the
+account's model list (or takes ``model=``) and asks; returns a
+:class:`~lm15.login.bound.BoundClient` pinned to that connection and
+model. A completed login is saved *before* the model picker runs: cancel
+the picker and the login stays (R6).
+
+What it never does: send a prompt, set a process-wide default, change
+another router, fall back to a different account when one fails.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from .errors import AuthOperationError
+from .login.bound import BoundClient, model_choices
+from .login.engine import LoginCancelled
+from .login.manager import Auth
+from .login.terminal import TerminalUI
+from .login.types import AuthUI, Connection, InfoNotice, LoginMethod, ModelSelection, ProviderDescriptor, \
+ SelectOption, SelectPrompt, TextPrompt
+
+__all__ = ["connect"]
+
+_NEW = "__new__"
+_MANUAL = "__manual__"
+_KEY_FROM_ENV = "__env__"
+
+
+def _interactive_terminal() -> bool:
+ try:
+ return sys.stdin.isatty() and sys.stderr.isatty()
+ except (AttributeError, ValueError):
+ return False
+
+
+def connect(
+ provider: str | None = None,
+ *,
+ model: str | None = None,
+ auth: Auth | None = None,
+ ui: AuthUI | None = None,
+ capability: str | None = None,
+ open_browser: bool = False,
+ router_config: Any = None,
+ allow_unverified: bool = False,
+) -> BoundClient:
+ """Choose (or make) a connection and a model; return a bound client.
+
+ ``provider`` and ``model`` skip the corresponding pickers when given.
+ ``auth`` defaults to ``Auth.local()`` (the private file); ``ui`` to a
+ terminal adapter on an interactive terminal. ``capability`` filters
+ the model picker to models known to support it (``reasoning``,
+ ``vision``, ``structured-output``); unknown ones are not offered.
+ ``allow_unverified`` lets the picker offer login methods that exist
+ but have no live receipt yet, labelled as such.
+ """
+ if ui is None:
+ if not _interactive_terminal():
+ raise AuthOperationError(
+ "connect() needs a person: no interactive terminal here and no ui= was supplied. On a server, "
+ "attach an Auth with saved connections (RouterConfig(auth=...)) instead of calling connect().",
+ reason="interaction_required", stage="interaction", recovery="provide_input",
+ )
+ ui = TerminalUI(open_browser=open_browser)
+ auth = auth or Auth.local()
+ ui.notify(InfoNotice(f"Connections are saved privately in {auth.store.description}."))
+
+ connection = _choose_connection(auth, ui, provider, allow_unverified=allow_unverified)
+ selection = _choose_model(auth, ui, connection, model=model, capability=capability, router_config=router_config)
+ ui.notify(InfoNotice(f"Ready: {selection.routed} through {connection.label}."))
+ return BoundClient(auth, selection, router_config=router_config)
+
+
+# ─── connection ──────────────────────────────────────────────────────
+
+
+def _choose_connection(auth: Auth, ui: AuthUI, provider: str | None, *, allow_unverified: bool) -> Connection:
+ saved = [c for c in auth.connections() if provider is None or c.provider == auth.descriptor(provider).id]
+ # Subscriptions first (R2): account connections before keys.
+ saved.sort(key=lambda c: (0 if c.kind == "account" else 1, c.provider))
+ usable = []
+ for connection in saved:
+ status = auth.status(connection.provider)
+ if status.usability in ("ready", "renewal_due", "unknown"):
+ usable.append(connection)
+ if provider is not None and len(usable) == 1:
+ return usable[0]
+ options = [SelectOption(c.id, f"{c.label}", f"{c.provider} · saved") for c in usable]
+ options.append(SelectOption(_NEW, "Connect another account or API key"))
+ if len(options) == 1:
+ return _new_connection(auth, ui, provider, allow_unverified=allow_unverified)
+ answer = _ask(ui, SelectPrompt("connection", "Use a saved connection, or connect another?", tuple(options)))
+ if answer == _NEW:
+ return _new_connection(auth, ui, provider, allow_unverified=allow_unverified)
+ for connection in usable:
+ if connection.id == answer:
+ return connection
+ raise AuthOperationError("the UI answered with an unknown connection id", reason="invalid_login_state",
+ stage="interaction", recovery="select_connection")
+
+
+def _new_connection(auth: Auth, ui: AuthUI, provider: str | None, *, allow_unverified: bool) -> Connection:
+ if provider is None:
+ descriptors = [d for d in auth.providers() if any(m.availability != "unavailable" for m in d.methods)]
+ # Subscriptions first, then everything else alphabetically.
+ descriptors.sort(key=lambda d: (0 if any(m.subscription and m.availability == "supported" for m in d.methods) else 1,
+ d.label.lower()))
+ options = tuple(SelectOption(d.id, d.label, d.service if d.service != d.label else None) for d in descriptors)
+ provider = _ask(ui, SelectPrompt("provider", "Which provider?", options))
+ descriptor = auth.descriptor(provider)
+ existing = auth.status(descriptor.id).connection
+ method = _choose_method(ui, descriptor, allow_unverified=allow_unverified, env=os.environ)
+ replace = None
+ if existing is not None:
+ answer = _ask(ui, SelectPrompt("replace", f"{descriptor.label} already has a saved connection ({existing.label}).",
+ (SelectOption("keep", "Keep it"), SelectOption("replace", "Replace it"))))
+ if answer == "keep":
+ return existing
+ replace = existing.id
+ if method.flow in ("form", "source_recipe"):
+ answers: dict[str, str] = {}
+ for field_ in method.fields:
+ if field_.type == "select" and len(field_.options) == 1:
+ answers[field_.id] = field_.options[0].id
+ elif field_.type == "select":
+ answers[field_.id] = _ask(ui, SelectPrompt(field_.id, field_.label, field_.options))
+ elif field_.type == "secret":
+ from .login.types import SecretPrompt
+
+ answers[field_.id] = _ask(ui, SecretPrompt(field_.id, field_.label))
+ else:
+ answers[field_.id] = _ask(ui, TextPrompt(field_.id, field_.label))
+ return auth.configure(descriptor.id, method=method.id, answers=answers, replace=replace)
+ try:
+ return auth.login(descriptor.id, method.id, ui=ui, replace=replace, allow_unverified=allow_unverified)
+ except LoginCancelled:
+ raise AuthOperationError("sign-in cancelled", reason="interaction_required", stage="interaction",
+ recovery="restart_login", provider=descriptor.id) from None
+
+
+def _choose_method(ui: AuthUI, descriptor: ProviderDescriptor, *, allow_unverified: bool, env: Any) -> LoginMethod:
+ methods = [m for m in descriptor.methods if m.availability == "supported"
+ or (allow_unverified and m.availability == "unverified")]
+ if not methods:
+ raise AuthOperationError(
+ f"{descriptor.id}: no login method is available here", reason="method_unavailable", stage="discovery",
+ recovery="choose_method", provider=descriptor.id,
+ )
+ # Subscriptions first; an ambient key is offered, never assumed (R2).
+ methods.sort(key=lambda m: (0 if m.subscription else 1, 0 if m.kind == "account" else 1))
+ options = []
+ for method in methods:
+ note = method.billing_note
+ if method.availability == "unverified":
+ note = f"UNVERIFIED — {method.reason}"
+ if method.id == "env":
+ set_names = [o.id for o in method.fields[0].options if env.get(o.id)] if method.fields else []
+ if not set_names:
+ continue # nothing to offer
+ note = f"${set_names[0]} is set in this environment; using it is your explicit choice"
+ options.append(SelectOption(method.id, method.label, note))
+ if len(options) == 1:
+ chosen = options[0].id
+ else:
+ chosen = _ask(ui, SelectPrompt("method", f"How do you want to connect to {descriptor.label}?", tuple(options)))
+ return descriptor.method(chosen)
+
+
+# ─── model ───────────────────────────────────────────────────────────
+
+
+def _choose_model(auth: Auth, ui: AuthUI, connection: Connection, *, model: str | None, capability: str | None,
+ router_config: Any) -> ModelSelection:
+ if model is not None:
+ return ModelSelection(provider=connection.provider, model=model, connection_id=connection.id,
+ identity_generation=connection.identity_generation)
+ choices = ()
+ try:
+ choices = model_choices(auth, connection.provider, refresh=True, capability=capability, router_config=router_config)
+ source_note = "listed by your account just now"
+ except AuthOperationError:
+ raise
+ except Exception as exc: # the catalog is a convenience; say why it is missing, do not pretend
+ ui.notify(InfoNotice(f"Could not list models for {connection.provider} ({type(exc).__name__}); type a model id."))
+ source_note = ""
+ options = [SelectOption(c.model, c.model, source_note or None) for c in choices]
+ options.append(SelectOption(_MANUAL, "Type a model id (not verified against your account)"))
+ if capability and not choices:
+ ui.notify(InfoNotice(f"No model in the list is known to support {capability!r}; you can still type one."))
+ answer = _ask(ui, SelectPrompt("model", f"Which {connection.provider} model?", tuple(options)))
+ if answer == _MANUAL:
+ answer = _ask(ui, TextPrompt("model", "Model id")).strip()
+ if not answer:
+ raise AuthOperationError("no model id given", reason="interaction_required", stage="interaction",
+ recovery="provide_input", provider=connection.provider)
+ return ModelSelection(provider=connection.provider, model=answer, connection_id=connection.id,
+ identity_generation=connection.identity_generation)
+
+
+def _ask(ui: AuthUI, prompt: Any) -> str:
+ try:
+ return ui.prompt(prompt)
+ except (KeyboardInterrupt, EOFError):
+ raise AuthOperationError("cancelled", reason="interaction_required", stage="interaction",
+ recovery="restart_login") from None
diff --git a/dspy/_vendor/lm15/judgments.py b/dspy/_vendor/lm15/judgments.py
index 8fdf1946e..830fa3503 100644
--- a/dspy/_vendor/lm15/judgments.py
+++ b/dspy/_vendor/lm15/judgments.py
@@ -7,8 +7,7 @@ boolean, a string ``enum``/``anyOf``-of-``const``, or an ordered integer
convention off a schema (§1), rewrites judgment properties for the two
wires that need it (§2), folds a model's JSON text into a ``DataPart``
(§3), and offers the sugar that EMITS the convention (``choice``,
-``yes_no``, ``score``, ``judgments``) the way ``tool(fn)`` emits a tool
-schema. Nothing here touches the network.
+``yes_no``, ``score``, ``judgments``) so it need not be written by hand. Nothing here touches the network.
"""
from __future__ import annotations
diff --git a/dspy/_vendor/lm15/login/__init__.py b/dspy/_vendor/lm15/login/__init__.py
new file mode 100644
index 000000000..9b0a2dd3c
--- /dev/null
+++ b/dspy/_vendor/lm15/login/__init__.py
@@ -0,0 +1,125 @@
+"""
+lm15.login — managed authentication: sign in once, use everywhere.
+
+spec/auth.md AUTH-12–26 (ratified core, 2026-09-22). Python is the first
+implementation; the contract, not this module, is the authority.
+
+ from lm15.login import Auth, TerminalUI
+
+ from lm15 import login_providers # descriptor collection (also lm15.login.providers)
+ login_providers.meta.methods # lm15.providers remains the implementation package
+
+ auth = Auth.local() # reads nothing yet
+ auth.login("xai", ui=TerminalUI()) # device code in the terminal; saved on success
+ router = LMRouter(RouterConfig(auth=auth)) # explicit keys still win; otherwise the saved login
+
+ from lm15.interactive import connect # the short path
+ with connect() as lm:
+ lm.complete(messages=[Message.user("hi")])
+
+What this module does not do: read another tool's login unless you
+explicitly configure it as an external source; fall back to an
+environment key after a login fails or is signed out; start a login
+during an ordinary request; keep any conversation state.
+
+``lm15.auth`` (the legacy CLI-credential helpers and ``login_xai``) keeps
+working; ``login_xai`` now runs the same xAI flow as ``Auth.login("xai")``.
+"""
+
+from __future__ import annotations
+
+from ..errors import AUTH_OPERATION_REASONS, AuthOperationError
+from .engine import ATTEMPT_LIFETIME_S, LoginCancelled
+from .bound import BoundClient, model_choices
+from .manager import AsyncAuth, Auth, ForgetResult
+from .store import FileStore, MemoryStore, Store, default_store_path
+from .terminal import TerminalUI
+from .types import (
+ AuthUI,
+ AuthUrlNotice,
+ Connection,
+ ConnectionStatus,
+ DeviceCodeNotice,
+ InfoNotice,
+ LoginMethod,
+ ManualCodePrompt,
+ MethodField,
+ ModelChoice,
+ ModelSelection,
+ Notice,
+ ProgressNotice,
+ Prompt,
+ ProviderDescriptor,
+ SecretPrompt,
+ SelectOption,
+ SelectPrompt,
+ TextPrompt,
+ Verification,
+)
+
+__all__ = [
+ "ATTEMPT_LIFETIME_S",
+ "AUTH_OPERATION_REASONS",
+ "AsyncAuth",
+ "Auth",
+ "AuthOperationError",
+ "BoundClient",
+ "AuthUI",
+ "AuthUrlNotice",
+ "Connection",
+ "ConnectionStatus",
+ "DeviceCodeNotice",
+ "FileStore",
+ "ForgetResult",
+ "InfoNotice",
+ "LoginCancelled",
+ "LoginMethod",
+ "ManualCodePrompt",
+ "MemoryStore",
+ "MethodField",
+ "ModelChoice",
+ "ModelSelection",
+ "Notice",
+ "ProgressNotice",
+ "Prompt",
+ "ProviderDescriptor",
+ "SecretPrompt",
+ "SelectOption",
+ "SelectPrompt",
+ "Store",
+ "TerminalUI",
+ "TextPrompt",
+ "Verification",
+ "default_store_path",
+ "model_choices",
+ "providers",
+]
+
+
+class _Providers:
+ """``providers.xai``, ``providers.openai_codex`` … — discoverable names
+ for the routes a manager can connect (AUTH-13.1). Attribute access
+ only reads definitions; unknown names raise ``AttributeError``."""
+
+ def __getattr__(self, name: str) -> ProviderDescriptor:
+ from .flows import descriptor
+
+ if name.startswith("_"):
+ raise AttributeError(name)
+ try:
+ return descriptor(name.replace("_", "-"))
+ except KeyError:
+ raise AttributeError(f"no provider {name!r}; see Auth.providers()") from None
+
+ def __dir__(self) -> list[str]:
+ from .flows import provider_ids
+
+ return [p.replace("-", "_") for p in provider_ids()]
+
+ def __iter__(self):
+ from .flows import descriptor, provider_ids
+
+ return (descriptor(p) for p in provider_ids())
+
+
+providers = _Providers()
diff --git a/dspy/_vendor/lm15/login/bound.py b/dspy/_vendor/lm15/login/bound.py
new file mode 100644
index 000000000..28b759780
--- /dev/null
+++ b/dspy/_vendor/lm15/login/bound.py
@@ -0,0 +1,223 @@
+"""
+lm15.login.bound — model choices and the bound client (AUTH-23).
+
+A :class:`BoundClient` is what ``connect()`` returns: one connection id,
+one generation, one route, one model. It follows that connection's
+credential renewals and nothing else — a replacement or logout makes it
+fail ``connection_changed`` / ``login_required`` instead of quietly
+switching who pays (R4). It builds ordinary canonical ``Request`` values
+and returns ordinary ``Response`` / stream events through an ordinary
+router; it keeps no conversation, runs no tool loop, retries nothing.
+
+Model choices are evidence-bearing (AUTH-23): each says where it came from
+(``application`` = a ``ModelRegistry`` the caller supplied, ``provider`` =
+the account's own list fetched now, ``manual`` = an id the caller typed)
+and, for a requested capability, whether that is ``supported``,
+``unsupported`` or ``unknown``. Nothing here ranks models, probes with a
+paid prompt, or enables a provider policy.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime, timezone
+from typing import Any, Iterable, Iterator, Sequence
+
+from ..errors import AuthOperationError
+from ..types import Config, Message, Request, Response, StreamEvent, Tool
+from .manager import Auth
+from .types import Connection, ModelChoice, ModelSelection
+
+__all__ = ["BoundClient", "model_choices", "pinned_auth"]
+
+_CAPABILITIES = {"reasoning", "vision", "structured-output"}
+
+
+def _now_iso() -> str:
+ return datetime.now(tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _capability(info: Any, name: str) -> str:
+ inference = getattr(info, "inference", None)
+ if inference is None:
+ return "unknown"
+ if name == "reasoning":
+ return "supported" if inference.supports_reasoning else "unsupported"
+ if name == "vision":
+ return "supported" if "image" in inference.input_modalities else "unsupported"
+ return "unknown" # structured output is not recorded in ModelInfo today; say so
+
+
+def model_choices(
+ auth: Auth,
+ provider: str,
+ *,
+ refresh: bool = False,
+ capability: str | None = None,
+ include_unknown: bool = False,
+ registry: Any = None,
+ router_config: Any = None,
+) -> tuple[ModelChoice, ...]:
+ """The models the saved connection on ``provider`` can select.
+
+ ``refresh=False`` reads only a caller-supplied ``ModelRegistry``
+ (``application`` source); ``refresh=True`` fetches the account's own
+ list with the saved credential (``provider`` source; renews if due; no
+ inference). With ``capability``, only ``supported`` choices are
+ returned unless ``include_unknown`` is set (AUTH-23).
+ """
+ if capability is not None and capability not in _CAPABILITIES:
+ raise ValueError(f"capability must be one of {sorted(_CAPABILITIES)}")
+ status = auth.status(provider)
+ connection = status.connection
+ if connection is None:
+ raise AuthOperationError(
+ f"{provider}: no saved connection to list models for", reason="login_required", stage="catalog",
+ recovery="restart_login", provider=provider,
+ )
+ infos: list[Any] = []
+ source = "application"
+ fetched: str | None = None
+ if refresh:
+ from ..router import LMRouter, RouterConfig
+
+ # List this saved account's models, not a config-supplied identity's.
+ config = replace(router_config or RouterConfig(), auth=auth, api_keys=None, credentials=None)
+ router = LMRouter(config)
+ try:
+ lm = router.lm(f"{connection.provider}:catalog")
+ infos = list(lm.list_models())
+ finally:
+ router.close()
+ source, fetched = "provider", _now_iso()
+ elif registry is not None:
+ infos = list(registry.list(connection.provider))
+ choices: list[ModelChoice] = []
+ for info in infos:
+ capabilities = {capability: _capability(info, capability)} if capability else {}
+ choice = ModelChoice(provider=connection.provider, model=info.id, connection_id=connection.id, source=source,
+ label=info.id, fetched_at=fetched, capabilities=capabilities)
+ if capability and capabilities[capability] == "unsupported":
+ continue
+ if capability and capabilities[capability] == "unknown" and not include_unknown:
+ continue
+ choices.append(choice)
+ return tuple(choices)
+
+
+class _PinnedAuth(Auth):
+ """The same scope, with every request-time resolution checked against
+ one ``(connection_id, generation)``. Shares the store; owns nothing."""
+
+ def __init__(self, base: Auth, selection: ModelSelection) -> None:
+ self.store = base.store
+ self._clock = base._clock
+ self._monotonic = base._monotonic
+ self._opener = base._opener
+ self._sleep = base._sleep
+ self._active = base._active
+ self._lock = base._lock
+ self._closed = False
+ self._pin = (selection.connection_id, selection.identity_generation)
+
+ def request_auth(self, provider: str, *, pinned: tuple[str, str] | None = None): # type: ignore[override]
+ return super().request_auth(provider, pinned=self._pin)
+
+ def credential_provider(self, provider: str, *, pinned: tuple[str, str] | None = None): # type: ignore[override]
+ return super().credential_provider(provider, pinned=self._pin)
+
+
+def pinned_auth(auth: Auth, selection: ModelSelection) -> Auth:
+ return _PinnedAuth(auth, selection)
+
+
+class BoundClient:
+ """One connection, one model; canonical requests and responses."""
+
+ def __init__(self, auth: Auth, selection: ModelSelection, *, router_config: Any = None) -> None:
+ from ..router import LMRouter, RouterConfig
+
+ self.auth = auth
+ self.selection = selection
+ base = router_config if router_config is not None else RouterConfig()
+ if base.auth is not None and base.auth is not auth:
+ raise ValueError("router_config.auth must be this client's Auth or None")
+ # The selected connection owns identity; retain only execution settings.
+ self._router = LMRouter(replace(base, auth=pinned_auth(auth, selection), api_keys=None, credentials=None))
+
+ def __repr__(self) -> str:
+ return f"BoundClient({self.selection.routed!r}, connection={self.selection.connection_id!r})"
+
+ @property
+ def provider(self) -> str:
+ return self.selection.provider
+
+ @property
+ def model(self) -> str:
+ return self.selection.model
+
+ @property
+ def connection(self) -> Connection | None:
+ return self.auth.status(self.selection.provider).connection
+
+ # ─── requests ─────────────────────────────────────────────────────
+
+ def _model(self, model: str) -> str:
+ if model not in (self.selection.routed, self.selection.model):
+ raise AuthOperationError(
+ f"this client is bound to {self.selection.routed!r}; the request names {model!r}",
+ reason="selection_mismatch", stage="dispatch", recovery="none", provider=self.provider,
+ )
+ return self.selection.routed
+
+ def request(self, messages: Iterable[Message] | str, *, tools: Sequence[Tool] | None = None,
+ config: Config | None = None, system: str | None = None, **fields: Any) -> Request:
+ """An ordinary canonical Request with the selected routed model.
+ ``messages`` may be a single user string for the short path."""
+ if isinstance(messages, str):
+ messages = (Message.user(messages),)
+ model = self._model(fields.pop("model", self.selection.routed))
+ kwargs: dict[str, Any] = {"model": model, "messages": tuple(messages)}
+ if tools:
+ kwargs["tools"] = tuple(tools)
+ if config is not None:
+ kwargs["config"] = config
+ if system is not None:
+ kwargs["system"] = system
+ kwargs.update(fields)
+ return Request(**kwargs)
+
+ def _coerce(self, request: Request | None, messages: Any, kwargs: dict[str, Any]) -> Request:
+ if request is not None:
+ if messages is not None or kwargs:
+ raise AuthOperationError(
+ "pass either a Request or messages/keywords, not both", reason="selection_mismatch",
+ stage="dispatch", recovery="none", provider=self.provider,
+ )
+ model = self._model(request.model)
+ return replace(request, model=model) if request.model != model else request
+ if messages is None:
+ raise TypeError("complete()/stream() need a Request or messages=")
+ return self.request(messages, **kwargs)
+
+ def complete(self, request: Request | None = None, *, messages: Any = None, **kwargs: Any) -> Response:
+ return self._router.complete(self._coerce(request, messages, kwargs))
+
+ def stream(self, request: Request | None = None, *, messages: Any = None, **kwargs: Any) -> Iterator[StreamEvent]:
+ return self._router.stream(self._coerce(request, messages, kwargs))
+
+ def plan(self, request: Request | None = None, *, messages: Any = None, **kwargs: Any) -> Any:
+ return self._router.plan(self._coerce(request, messages, kwargs))
+
+ # ─── lifecycle ────────────────────────────────────────────────────
+
+ def close(self) -> None:
+ """Release this client's own transport. Not a logout; the Auth
+ stays the caller's."""
+ self._router.close()
+
+ def __enter__(self) -> "BoundClient":
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ self.close()
diff --git a/dspy/_vendor/lm15/login/declared.py b/dspy/_vendor/lm15/login/declared.py
new file mode 100644
index 000000000..c650954da
--- /dev/null
+++ b/dspy/_vendor/lm15/login/declared.py
@@ -0,0 +1,65 @@
+"""
+lm15.login.declared — routes that exist only for a managed connection.
+
+``kimi-code`` (Kimi Code subscription: Anthropic Messages wire at
+``api.kimi.com/coding``) and ``github-copilot`` (Copilot: Chat Completions
+wire at the account's Copilot host) have no live wire receipt in
+lm15-contract, so they are **not** in the receipted provider registry
+(a registry row is a support claim; AUTH-26 forbids one without evidence).
+They are *declared providers*, the same mechanism an application uses for
+a gateway lm15 has never seen: routed, marked ``Resolution.declared``
+("no lm15 receipts"), and added to a router automatically only when that
+router carries a managed ``Auth`` — the only way to have a credential
+for them. Nothing here reads a credential.
+"""
+
+from __future__ import annotations
+
+from ..compat import AnthropicCompat, OpenAIChatCompat
+from ..features import AccessPolicy, EndpointSupport
+from ..registry import ProviderDefinition
+
+__all__ = ["DECLARED_PROVIDERS", "KIMI_CODE", "GITHUB_COPILOT", "KIMI_CODE_BASE_URL", "COPILOT_DEFAULT_BASE_URL"]
+
+KIMI_CODE_BASE_URL = "https://api.kimi.com/coding"
+COPILOT_DEFAULT_BASE_URL = "https://api.individual.githubcopilot.com"
+
+KIMI_CODE = ProviderDefinition.anthropic(
+ AccessPolicy(
+ provider="kimi-code",
+ supports=EndpointSupport(complete=True, stream=True),
+ auth_modes=("bearer",),
+ env_keys=(),
+ auth_scheme=("bearer",),
+ base_url=KIMI_CODE_BASE_URL,
+ ),
+ compat=AnthropicCompat(),
+ note="Kimi Code subscription over the Anthropic Messages wire (managed login only; no lm15 wire receipt yet)",
+)
+
+GITHUB_COPILOT = ProviderDefinition.chat(
+ AccessPolicy(
+ provider="github-copilot",
+ supports=EndpointSupport(complete=True, stream=True, models=True),
+ auth_modes=("bearer",),
+ env_keys=(),
+ auth_scheme=("bearer",),
+ headers=(
+ ("User-Agent", "GitHubCopilotChat/0.35.0"),
+ ("Editor-Version", "vscode/1.107.0"),
+ ("Editor-Plugin-Version", "copilot-chat/0.35.0"),
+ ("Copilot-Integration-Id", "vscode-chat"),
+ ),
+ base_url=COPILOT_DEFAULT_BASE_URL,
+ ),
+ compat=OpenAIChatCompat(
+ instruction_role="system",
+ max_tokens_field="max_completion_tokens",
+ stream_usage="include",
+ thinking_format="reasoning_effort",
+ ),
+ note="GitHub Copilot over the Chat Completions wire (managed login only; the account's host comes from the token; "
+ "no lm15 wire receipt yet)",
+)
+
+DECLARED_PROVIDERS: tuple[ProviderDefinition, ...] = (KIMI_CODE, GITHUB_COPILOT)
diff --git a/dspy/_vendor/lm15/login/engine.py b/dspy/_vendor/lm15/login/engine.py
new file mode 100644
index 000000000..1aede5ef2
--- /dev/null
+++ b/dspy/_vendor/lm15/login/engine.py
@@ -0,0 +1,740 @@
+"""
+lm15.login.engine — the machinery every provider flow runs on.
+
+spec/auth.md AUTH-18 (connected login, device polling, browser/OAuth
+protections), AUTH-20 (bounded exchanges, uncertainty), AUTH-21 (what a
+diagnostic may carry). Provider flows (``lm15.login.flows``) describe
+*their* protocol; this module supplies the parts that must be identical
+for all of them:
+
+- :class:`LoginContext` — one attempt's deadline, cancellation and UI, plus
+ the clock/sleep/HTTP seams tests inject;
+- :func:`http_json` / :func:`http_form` — bounded (30 s, 1 MiB), TLS-only
+ exchanges whose failures never carry a token or a reflected provider
+ string into an exception;
+- :func:`run_device_flow` — RFC 8628 polling with the ratified pacing
+ (provider interval or 5 s; ``slow_down`` adds at least 5 s; never
+ decreases; deadline never extended);
+- :class:`CallbackListener` — a one-shot loopback listener for
+ authorization-code returns: loopback bind only, exact path, state checked
+ on success *and* error returns, bounded request size, no access log;
+- :func:`race_callback_and_manual` — the listener raced against a manual
+ paste prompt, the loser dismissed;
+- :func:`parse_manual_return` — a pasted redirect URL or bare code, checked
+ against the attempt's registered return context.
+
+Nothing here knows a provider's URL, client id or token shape.
+"""
+
+from __future__ import annotations
+
+import html
+import http.client
+import json
+import secrets
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import Any, Callable
+from urllib.parse import parse_qsl, urlsplit
+
+from .._version import __version__
+from ..errors import AuthError, AuthOperationError, RateLimitError, ServerError, TransportError
+from .types import AuthUI, InfoNotice, ManualCodePrompt, Notice, Prompt
+
+__all__ = [
+ "ATTEMPT_LIFETIME_S",
+ "AUTH_RESPONSE_LIMIT",
+ "CallbackListener",
+ "CallbackReturn",
+ "DeviceStep",
+ "EXCHANGE_TIMEOUT_S",
+ "HttpReply",
+ "LoginCancelled",
+ "LoginContext",
+ "LoginDenied",
+ "LoginExpired",
+ "http_form",
+ "http_json",
+ "parse_manual_return",
+ "await_return",
+ "race_callback_and_manual",
+ "run_device_flow",
+]
+
+ATTEMPT_LIFETIME_S = 15 * 60 # AUTH-18, R9
+EXCHANGE_TIMEOUT_S = 30.0 # AUTH-20.5, R9
+DEVICE_DEFAULT_INTERVAL_S = 5.0 # RFC 8628 §3.2
+DEVICE_SLOW_DOWN_STEP_S = 5.0 # RFC 8628 §3.5
+AUTH_RESPONSE_LIMIT = 1024 * 1024 # AUTH-18: 1 MiB auth HTTP body
+CALLBACK_TARGET_LIMIT = 8 * 1024 # AUTH-18: 8 KiB request target
+CALLBACK_HEADER_LIMIT = 32 * 1024 # AUTH-18: 32 KiB callback headers
+
+
+# ─── Outcomes the engine raises; the manager maps them (AUTH-24) ──────
+
+
+class LoginCancelled(Exception):
+ """The caller, the UI or the deadline stopped the attempt. Not an
+ LM15Error: the conformance outcome is ``cancelled`` (AUTH-24)."""
+
+
+class LoginExpired(Exception):
+ """The attempt's 15-minute (or provider) deadline passed."""
+
+
+class LoginDenied(Exception):
+ """A validated provider denial (``access_denied``, ``invalid_grant`` on
+ a code exchange, a device code the provider says expired). The message
+ is ours; provider text is never copied into it."""
+
+ def __init__(self, message: str, *, status: int | None = None,
+ provider_code: str | None = None, stage: str = "authorization") -> None:
+ super().__init__(message)
+ self.status = status
+ self.provider_code = provider_code
+ self.stage = stage
+
+
+# ─── The attempt context ───────────────────────────────────────────────
+
+
+@dataclass
+class LoginContext:
+ """Everything a flow may touch during one attempt.
+
+ ``deadline`` is monotonic; ``cancel`` is the caller's event; ``ui`` is
+ the application's adapter. ``clock``/``sleep``/``opener`` are seams:
+ tests inject them, production leaves the defaults.
+ """
+
+ ui: AuthUI
+ deadline: float
+ cancel: threading.Event | None = None
+ provider: str = ""
+ clock: Callable[[], float] = time.monotonic
+ wall_clock: Callable[[], float] = time.time
+ opener: Callable[[urllib.request.Request, float], Any] | None = None
+ sleep: Callable[[float], None] | None = None # test seam; production waits on the cancel event
+ _prompts_open: list[Prompt] = field(default_factory=list, repr=False)
+
+ def remaining(self) -> float:
+ return self.deadline - self.clock()
+
+ def check(self) -> None:
+ """Raise if the attempt should stop. Called before every external
+ step and before every wait."""
+ if self.cancel is not None and self.cancel.is_set():
+ raise LoginCancelled("login cancelled")
+ if self.remaining() <= 0:
+ raise LoginExpired("login attempt deadline reached")
+
+ def wait(self, seconds: float) -> None:
+ """Sleep, but wake on cancel; never past the deadline."""
+ self.check()
+ seconds = min(max(seconds, 0.0), max(self.remaining(), 0.0))
+ if seconds <= 0:
+ self.check()
+ return
+ if self.sleep is not None:
+ self.sleep(seconds)
+ elif self.cancel is not None:
+ if self.cancel.wait(seconds):
+ raise LoginCancelled("login cancelled")
+ else:
+ time.sleep(seconds)
+ self.check()
+
+ def notify(self, notice: Notice) -> None:
+ self.ui.notify(notice)
+
+ def prompt(self, prompt: Prompt) -> str:
+ self.check()
+ try:
+ answer = self.ui.prompt(prompt)
+ except (KeyboardInterrupt, EOFError) as exc:
+ raise LoginCancelled("login cancelled at the prompt") from exc
+ if not isinstance(answer, str):
+ raise TypeError("AuthUI.prompt must return a str")
+ return answer
+
+ def budget(self) -> float:
+ """The network budget for one exchange: 30 s, bounded by the deadline."""
+ return max(0.1, min(EXCHANGE_TIMEOUT_S, self.remaining()))
+
+
+# ─── Bounded HTTP (AUTH-18/20/21) ──────────────────────────────────────
+
+
+# Only these fixed protocol words can leave a private auth response. Never
+# reflect arbitrary error descriptions, URLs, header values or response bodies.
+_OAUTH_ERROR_CODES = frozenset({
+ "invalid_request", "invalid_client", "invalid_grant", "unauthorized_client",
+ "unsupported_grant_type", "invalid_scope", "access_denied", "server_error",
+ "temporarily_unavailable", "authorization_pending", "slow_down", "expired_token",
+})
+
+
+@dataclass(frozen=True, slots=True)
+class HttpReply:
+ status: int
+ body: dict[str, Any] = field(repr=False) # may hold tokens: never rendered
+ ok: bool = False
+ response_format: str = "unknown"
+ oauth_error: str | None = None
+ security_challenge: bool = False
+
+ def failure_summary(self) -> str:
+ details = [f"HTTP {self.status}", f"response={self.response_format}"]
+ if self.oauth_error:
+ details.append(f"OAuth error={self.oauth_error}")
+ else:
+ details.append("no recognized OAuth error code; cause not established")
+ if self.security_challenge:
+ details.append("response explicitly marked as a security challenge")
+ elif self.response_format == "html":
+ details.append("HTML alone does not establish a security block")
+ return "; ".join(details)
+
+
+def _auth_json_members(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+ result: dict[str, Any] = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError("duplicate member in auth response")
+ result[key] = value
+ return result
+
+
+def _reject_auth_number(value: str) -> None:
+ raise ValueError("non-finite number in auth response")
+
+
+def _tls_only(url: str) -> None:
+ parsed = urllib.parse.urlsplit(url)
+ if parsed.scheme != "https" or not parsed.netloc:
+ raise AuthOperationError(
+ "refusing a credential-bearing exchange over a non-HTTPS URL",
+ reason="method_unavailable", stage="exchange", recovery="operator_action",
+ )
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+ """AUTH-20.9: an unexpected redirect with credentials is refused."""
+
+ def redirect_request(self, req, fp, code, msg, headers, newurl): # noqa: D401
+ return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect())
+
+
+def _send(ctx: LoginContext, request: urllib.request.Request) -> HttpReply:
+ _tls_only(request.full_url)
+ # Identify this SDK, not urllib (some auth endpoints reject that default).
+ # Keep an explicit provider-required identification, e.g. Copilot's headers.
+ if not request.has_header("User-agent"):
+ request.add_header("User-Agent", f"lm15/{__version__}")
+ timeout = ctx.budget()
+ opener = ctx.opener
+ response_headers: Any = {}
+ try:
+ if opener is not None:
+ response = opener(request, timeout)
+ else:
+ response = _OPENER.open(request, timeout=timeout) # noqa: S310 - TLS enforced above
+ with response:
+ status = getattr(response, "status", None) or response.getcode()
+ response_headers = getattr(response, "headers", None) or {}
+ raw = response.read(AUTH_RESPONSE_LIMIT + 1)
+ except urllib.error.HTTPError as exc:
+ status = exc.code
+ response_headers = exc.headers or {}
+ try:
+ raw = exc.read(AUTH_RESPONSE_LIMIT + 1)
+ except Exception:
+ raw = b""
+ finally:
+ exc.close()
+ except (urllib.error.URLError, http.client.HTTPException, OSError, TimeoutError) as exc:
+ # The URL is safe; the exception text can contain anything the
+ # network stack saw, so only its class is named. ``exchange_uncertain``
+ # is AUTH-20.6's distinction: a refused connection or a DNS failure
+ # never reached the provider (safe to retry deliberately); a timeout
+ # or a dropped connection after sending may have (indeterminate).
+ error = TransportError(
+ f"{ctx.provider or 'auth'}: network failure during an authentication exchange "
+ f"({type(exc).__name__}) to {request.full_url}",
+ provider=ctx.provider or None,
+ )
+ error.exchange_uncertain = _uncertain(exc)
+ raise error from None
+ if len(raw) > AUTH_RESPONSE_LIMIT:
+ raise AuthError(
+ f"{ctx.provider or 'auth'}: authentication response exceeded {AUTH_RESPONSE_LIMIT} bytes; refused",
+ provider=ctx.provider or None,
+ )
+ body: dict[str, Any] = {}
+ # Map headers to fixed categories; never return their raw values.
+ content_type = response_headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+ response_format = "empty"
+ oauth_error = None
+ if raw:
+ response_format = "text_or_binary"
+ if content_type in ("text/html", "application/xhtml+xml"):
+ response_format = "html"
+ elif content_type == "application/json" or content_type.endswith("+json"):
+ response_format = "invalid_json"
+ try:
+ parsed = json.loads(raw.decode("utf-8"), object_pairs_hook=_auth_json_members,
+ parse_constant=_reject_auth_number)
+ except (ValueError, UnicodeDecodeError, RecursionError):
+ parsed = None
+ else:
+ response_format = "json"
+ if isinstance(parsed, dict):
+ body = parsed
+ candidate = parsed.get("error")
+ if isinstance(candidate, dict):
+ candidate = candidate.get("code", candidate.get("type"))
+ if isinstance(candidate, str) and candidate in _OAUTH_ERROR_CODES:
+ oauth_error = candidate
+ security_challenge = response_headers.get("cf-mitigated", "").strip().lower() == "challenge"
+ if status == 429:
+ raise RateLimitError(
+ f"{ctx.provider or 'auth'}: the authentication server answered HTTP {status}",
+ provider=ctx.provider or None, status=status,
+ )
+ if status >= 500:
+ raise ServerError(
+ f"{ctx.provider or 'auth'}: the authentication server answered HTTP {status}",
+ provider=ctx.provider or None, status=status,
+ )
+ return HttpReply(status=status, body=body, ok=200 <= status < 300,
+ response_format=response_format, oauth_error=oauth_error,
+ security_challenge=security_challenge)
+
+
+def _uncertain(exc: BaseException) -> bool:
+ import socket
+
+ reason = getattr(exc, "reason", exc)
+ if isinstance(reason, (socket.gaierror, ConnectionRefusedError)):
+ return False
+ if isinstance(reason, (TimeoutError, socket.timeout, http.client.RemoteDisconnected, ConnectionResetError, BrokenPipeError)):
+ return True
+ return True # unknown: conservative
+
+
+def http_json(ctx: LoginContext, url: str, payload: dict[str, Any], *, headers: dict[str, str] | None = None,
+ method: str = "POST") -> HttpReply:
+ data = json.dumps(payload).encode("utf-8") if method != "GET" else None
+ request = urllib.request.Request(
+ url, data=data, method=method,
+ headers={"Content-Type": "application/json", "Accept": "application/json", **(headers or {})},
+ )
+ return _send(ctx, request)
+
+
+def http_form(ctx: LoginContext, url: str, payload: dict[str, str], *, headers: dict[str, str] | None = None) -> HttpReply:
+ request = urllib.request.Request(
+ url, data=urllib.parse.urlencode(payload).encode("utf-8"), method="POST",
+ headers={"Content-Type": "application/x-www-form-urlencoded", "Accept": "application/json", **(headers or {})},
+ )
+ return _send(ctx, request)
+
+
+def http_get(ctx: LoginContext, url: str, *, headers: dict[str, str] | None = None) -> HttpReply:
+ request = urllib.request.Request(url, method="GET", headers={"Accept": "application/json", **(headers or {})})
+ return _send(ctx, request)
+
+
+# ─── Device flow (RFC 8628, AUTH-18) ───────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceStep:
+ """What one poll observed. ``complete`` carries the flow's value."""
+
+ status: str # pending | slow_down | complete | denied | expired
+ value: Any = field(default=None, repr=False)
+ interval_s: float | None = None
+
+
+def run_device_flow(
+ ctx: LoginContext,
+ poll: Callable[[], DeviceStep],
+ *,
+ interval_s: float | None,
+ expires_in_s: float | None,
+ wait_before_first_poll: bool = True,
+) -> Any:
+ """Poll until complete. Pacing per AUTH-18: the provider's interval or
+ 5 s; ``slow_down`` never shortens the interval and adds at least 5 s;
+ the provider's expiry bounds the attempt but never extends it."""
+ interval = float(interval_s) if interval_s and interval_s > 0 else DEVICE_DEFAULT_INTERVAL_S
+ interval = max(interval, 1.0)
+ if expires_in_s is not None and expires_in_s > 0:
+ ctx.deadline = min(ctx.deadline, ctx.clock() + float(expires_in_s))
+ if wait_before_first_poll:
+ ctx.wait(interval)
+ while True:
+ ctx.check()
+ step = poll()
+ if step.status == "complete":
+ return step.value
+ if step.status == "denied":
+ raise LoginDenied("the provider reported that authorization was denied")
+ if step.status == "expired":
+ raise LoginExpired("the provider reported that the device code expired")
+ if step.status == "slow_down":
+ proposed = step.interval_s if step.interval_s and step.interval_s > 0 else 0.0
+ interval = max(interval + DEVICE_SLOW_DOWN_STEP_S, proposed)
+ elif step.status != "pending":
+ raise TypeError(f"device poll returned unknown status {step.status!r}")
+ ctx.wait(interval)
+
+
+# ─── Loopback callback listener (AUTH-18 browser protections) ─────────
+
+
+@dataclass(frozen=True, slots=True)
+class CallbackReturn:
+ code: str = field(repr=False)
+ state: str | None = None
+
+
+_PAGE = (
+ "<!doctype html><meta charset='utf-8'><meta name='referrer' content='no-referrer'>"
+ "<title>{title}</title><p>{message}</p>"
+)
+
+
+class CallbackListener:
+ """One-shot loopback listener for an authorization-code return.
+
+ ``bind_host`` is the address the socket binds (``127.0.0.1`` or ``::1``;
+ nothing else is accepted). ``redirect_uri`` is the *registered* return
+ URI the provider was told (it may say ``localhost``): the two are
+ deliberately separate values (AUTH-18). ``port=0`` picks an ephemeral
+ port; a registered fixed port that is busy raises ``method_unavailable``
+ so the caller can offer manual return instead.
+ """
+
+ def __init__(self, *, path: str, expected_state: str | None, bind_host: str = "127.0.0.1",
+ port: int = 0, redirect_host: str | None = None) -> None:
+ if bind_host not in ("127.0.0.1", "::1"):
+ raise AuthOperationError(
+ f"callback listener may bind loopback only, not {bind_host!r}",
+ reason="method_unavailable", stage="reservation", recovery="operator_action",
+ )
+ if not path.startswith("/"):
+ raise ValueError("callback path must start with '/'")
+ self._path = path
+ self._expected_state = expected_state
+ self._result: CallbackReturn | None = None
+ self._denied = False
+ self._done = threading.Event()
+ self._lock = threading.Lock()
+ listener = self
+
+ class _Handler(BaseHTTPRequestHandler):
+ server_version = "lm15"
+ sys_version = ""
+
+ def log_message(self, *_args: Any) -> None: # AUTH-21: no access log, URLs carry codes
+ pass
+
+ def do_GET(self) -> None: # noqa: N802
+ if len(self.requestline) > CALLBACK_TARGET_LIMIT or sum(
+ len(k) + len(v) for k, v in self.headers.items()
+ ) > CALLBACK_HEADER_LIMIT:
+ self._page(414, "Rejected", "Request too large.")
+ return
+ split = urlsplit(self.path)
+ if split.path != listener._path:
+ self._page(404, "Not found", "Callback route not found.")
+ return
+ with listener._lock:
+ if listener._done.is_set():
+ self._page(409, "Already used", "This sign-in return was already handled.")
+ return
+ params = parse_qsl(split.query, keep_blank_values=True)
+ names = [k for k, _ in params]
+ if len(names) != len(set(names)):
+ self._page(400, "Rejected", "Sign-in return was not accepted.")
+ return
+ query = dict(params)
+ state = query.get("state")
+ if listener._expected_state is not None and state != listener._expected_state:
+ # Wrong state on a success OR an error return: generic
+ # rejection, and the legitimate wait continues.
+ self._page(400, "Rejected", "Sign-in return was not accepted.")
+ return
+ has_code = bool(query.get("code"))
+ has_error = "error" in query
+ if has_code == has_error:
+ # both, or neither: invalid
+ self._page(400, "Rejected", "Sign-in return was not accepted.")
+ return
+ if has_error:
+ listener._denied = True
+ listener._done.set()
+ self._page(400, "Not completed", "Sign-in was not completed.")
+ return
+ listener._result = CallbackReturn(code=query["code"], state=state)
+ listener._done.set()
+ self._page(200, "Signed in", "Sign-in completed. You can close this window.")
+
+ def _page(self, status: int, title: str, message: str) -> None:
+ body = _PAGE.format(title=html.escape(title), message=html.escape(message)).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.send_header("Referrer-Policy", "no-referrer")
+ self.end_headers()
+ self.wfile.write(body)
+
+ family_server = HTTPServer
+ if bind_host == "::1":
+ import socket
+
+ class _V6(HTTPServer):
+ address_family = socket.AF_INET6
+
+ family_server = _V6
+ try:
+ self._server = family_server((bind_host, port), _Handler)
+ except OSError as exc:
+ raise AuthOperationError(
+ f"could not listen on {bind_host}:{port or 'ephemeral'} for the sign-in return "
+ f"({exc.strerror or type(exc).__name__}); another program may be using the port",
+ reason="method_unavailable", stage="reservation", recovery="choose_method",
+ ) from None
+ self._server.timeout = 0.25
+ self._bind_host = bind_host
+ self._redirect_host = redirect_host or bind_host
+ self._thread: threading.Thread | None = None
+
+ @property
+ def port(self) -> int:
+ return int(self._server.server_address[1])
+
+ @property
+ def redirect_uri(self) -> str:
+ host = self._redirect_host
+ if ":" in host and not host.startswith("["):
+ host = f"[{host}]"
+ return f"http://{host}:{self.port}{self._path}"
+
+ def start(self) -> None:
+ def serve() -> None:
+ while not self._done.is_set() and not self._closed:
+ try:
+ self._server.handle_request()
+ except Exception:
+ if self._closed:
+ return
+ self._closed = False
+ self._thread = threading.Thread(target=serve, name="lm15-login-callback", daemon=True)
+ self._thread.start()
+
+ def wait(self, ctx: LoginContext) -> CallbackReturn | None:
+ """Block until a return arrives, the attempt is cancelled or the
+ deadline passes. ``None`` means the listener was stopped by the
+ caller (the manual prompt won)."""
+ while not self._done.is_set():
+ if self._closed:
+ return None
+ ctx.check()
+ self._done.wait(0.25)
+ if self._denied:
+ raise LoginDenied("the provider returned an error to the sign-in callback")
+ return self._result
+
+ def stop(self) -> None:
+ self._closed = True
+ self._done.set()
+ try:
+ self._server.server_close()
+ except Exception:
+ pass
+
+ _closed = True
+
+ def __enter__(self) -> "CallbackListener":
+ self.start()
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ self.stop()
+
+
+# ─── Manual return parsing (AUTH-18) ───────────────────────────────────
+
+
+def parse_manual_return(text: str, *, expected_state: str | None, allow_bare_code: bool,
+ registered_path: str | None, registered_uri: str | None = None) -> CallbackReturn:
+ """Validate a manual return, including state on provider error callbacks.
+
+ When registered_uri is supplied, a full URL must match its scheme, host,
+ effective port and path. A bare code is allowed only for profiles that
+ explicitly permit it; it is not permission for a URL to omit its state.
+ No pasted value is included in an exception.
+ """
+ value = (text or "").strip()
+ if not value:
+ raise AuthOperationError("nothing was pasted", reason="invalid_login_state", stage="interaction",
+ recovery="provide_input")
+ if len(value) > CALLBACK_TARGET_LIMIT:
+ raise AuthOperationError("pasted return is too long", reason="invalid_login_state", stage="interaction",
+ recovery="provide_input")
+ def invalid(message: str) -> AuthOperationError:
+ return AuthOperationError(message, reason="invalid_login_state", stage="interaction",
+ recovery="provide_input")
+
+ code: str | None = None
+ state: str | None = None
+ params: list[tuple[str, str]] | None = None
+ bare = False
+ if "://" in value:
+ try:
+ split = urlsplit(value)
+ if split.username is not None or split.password is not None or split.fragment:
+ raise ValueError("unexpected URL components")
+ if registered_path is not None and split.path != registered_path:
+ raise ValueError("wrong callback path")
+ if registered_uri is not None:
+ expected = urlsplit(registered_uri)
+
+ def address(url):
+ port = url.port if url.port is not None else {"https": 443, "http": 80}.get(url.scheme)
+ return url.scheme, url.hostname, port, url.path
+
+ if address(split) != address(expected):
+ raise ValueError("wrong callback destination")
+ params = parse_qsl(split.query, keep_blank_values=True)
+ except ValueError:
+ raise invalid("the pasted URL is not this sign-in's registered return URL") from None
+ elif value.startswith(("code=", "state=", "error=")):
+ params = parse_qsl(value, keep_blank_values=True)
+ elif "#" in value:
+ code, _, state = value.partition("#")
+ else:
+ code, bare = value, True
+
+ denied = False
+ if params is not None:
+ names = [key for key, _ in params]
+ if len(names) != len(set(names)):
+ raise invalid("the pasted return repeats a parameter")
+ query = dict(params)
+ if "code" in query and "error" in query:
+ raise invalid("the pasted return contains both a code and an error")
+ denied = "error" in query
+ code, state = query.get("code"), query.get("state")
+
+ if bare and not allow_bare_code:
+ raise invalid("paste the complete code#state or return URL, not the code alone")
+ if expected_state is not None:
+ if state is None:
+ if not (bare and allow_bare_code):
+ raise invalid("this provider's return must carry its state value")
+ elif not secrets.compare_digest(state.encode("utf-8"), expected_state.encode("utf-8")):
+ raise invalid("the pasted return does not belong to this sign-in attempt")
+ # A wrong-state error must never terminate the legitimate attempt as denied.
+ if denied:
+ raise LoginDenied("the validated pasted return carries a provider error")
+ if not code:
+ raise invalid("no authorization code in the pasted text")
+ return CallbackReturn(code=code, state=state)
+
+
+# ─── Listener vs manual prompt (AUTH-16) ───────────────────────────────
+
+
+def race_callback_and_manual(
+ ctx: LoginContext,
+ listener: CallbackListener | None,
+ prompt: ManualCodePrompt,
+ *,
+ keep_listener: bool = False,
+) -> tuple[CallbackReturn | None, str | None]:
+ """Wait for whichever arrives first: the loopback return or a pasted
+ value. Returns ``(callback, None)`` or ``(None, pasted_text)``. The
+ loser is dismissed; a stale manual answer after a callback win is
+ ignored (AUTH-16)."""
+ if listener is None:
+ return None, ctx.prompt(prompt)
+
+ manual_box: dict[str, Any] = {}
+ manual_done = threading.Event()
+
+ def ask() -> None:
+ try:
+ manual_box["value"] = ctx.ui.prompt(prompt)
+ except (KeyboardInterrupt, EOFError):
+ manual_box["cancelled"] = True
+ except BaseException as exc: # a UI bug is a sanitized failure, not a crash into headless mode
+ manual_box["error"] = type(exc).__name__
+ finally:
+ manual_done.set()
+
+ thread = threading.Thread(target=ask, name="lm15-login-manual", daemon=True)
+ thread.start()
+ try:
+ while True:
+ ctx.check()
+ if listener._done.is_set():
+ result = listener.wait(ctx)
+ dismiss = getattr(ctx.ui, "dismiss", None)
+ if callable(dismiss):
+ dismiss(prompt)
+ return result, None
+ if manual_done.is_set():
+ if not keep_listener or "value" not in manual_box:
+ listener.stop()
+ if manual_box.get("cancelled"):
+ raise LoginCancelled("login cancelled at the prompt")
+ if "error" in manual_box:
+ raise AuthOperationError(
+ f"the application's UI failed while prompting ({manual_box['error']})",
+ reason="interaction_required", stage="interaction", recovery="operator_action",
+ )
+ return None, manual_box.get("value")
+ manual_done.wait(0.25)
+ finally:
+ if not (keep_listener and "value" in manual_box and not listener._done.is_set()):
+ listener.stop()
+
+
+def await_return(
+ ctx: LoginContext,
+ listener: CallbackListener | None,
+ prompt: ManualCodePrompt,
+ parse: Callable[[str], CallbackReturn],
+) -> CallbackReturn:
+ """The authorization return, from the listener or a paste, validated.
+
+ A paste that fails validation (wrong state, wrong URL, a bare code the
+ profile does not accept) is rejected with a notice and the legitimate
+ wait goes on — the listener keeps listening and the person is asked
+ again (AUTH-18: a wrong return "does not terminate the legitimate
+ wait"; AUTH-24 ``invalid_login_state``). Cancellation and the deadline
+ still end it.
+ """
+ while True:
+ returned, pasted = race_callback_and_manual(ctx, listener, prompt, keep_listener=True)
+ if returned is not None:
+ return returned
+ try:
+ return parse(pasted or "")
+ except AuthOperationError as exc:
+ if exc.reason != "invalid_login_state":
+ raise
+ ctx.notify(InfoNotice(f"{exc}. Try again."))
diff --git a/dspy/_vendor/lm15/login/flows/__init__.py b/dspy/_vendor/lm15/login/flows/__init__.py
new file mode 100644
index 000000000..c30cde7e9
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/__init__.py
@@ -0,0 +1,171 @@
+"""
+lm15.login.flows — the provider table the manager consults.
+
+One :class:`ProviderFlow` per provider LM15 can connect. Account flows are
+hand-written per provider (their protocols differ in ways a generic OAuth
+machine would hide badly — D-3 in the decision log); key, env, external and
+local recipes are generated from the provider registry so every route the
+router knows can be connected the same way.
+
+``descriptor(provider)`` and ``flow(provider)`` are the only entry points.
+Descriptors are built once, lazily, from data; nothing here reads a
+credential file, the network or the environment (AUTH-13.2).
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from ...registry import PROVIDERS, canonical_provider
+from ..types import LoginMethod, MethodField, ProviderDescriptor, SelectOption
+from .base import LoginResult, Material, ProviderFlow, RequestAuth
+from .recipes import EXTERNAL_SOURCES, RecipeFlow, api_key_method, env_method, external_method
+
+__all__ = ["ProviderFlow", "LoginResult", "RequestAuth", "Material", "descriptor", "flow", "provider_ids",
+ "RADIUS_ID"]
+
+RADIUS_ID = "radius"
+
+# Providers whose account login LM15 implements natively (R11's inventory).
+_ACCOUNT_FLOW_MODULES = {
+ "xai": "xai", "claude-code": "claude", "openai-codex": "codex", "openrouter": "openrouter",
+ "meta": "meta", "kimi-code": "kimi", "github-copilot": "copilot",
+}
+
+_SERVICE_LABELS = {
+ "anthropic": "Anthropic", "claude-code": "Anthropic", "openai": "OpenAI", "openai-chat": "OpenAI",
+ "openai-codex": "OpenAI", "gemini": "Google", "vertex": "Google Cloud", "vertex-anthropic": "Google Cloud",
+ "vertex-express": "Google Cloud", "azure": "Microsoft Azure", "azure-chat": "Microsoft Azure",
+ "azure-anthropic": "Microsoft Azure", "aws-anthropic": "AWS", "bedrock-anthropic": "AWS",
+ "bedrock-chat": "AWS", "bedrock-mantle-chat": "AWS", "meta": "Meta", "meta-chat": "Meta",
+ "meta-anthropic": "Meta", "moonshotai": "Moonshot AI", "moonshotai-anthropic": "Moonshot AI",
+ "moonshotai-responses": "Moonshot AI", "kimi-code": "Moonshot AI", "deepseek": "DeepSeek",
+ "deepseek-anthropic": "DeepSeek", "groq": "Groq", "openrouter": "OpenRouter", "xai": "xAI",
+ "zai": "Z.AI", "typesafe": "TypeSafe", "ollama": "Local", "vllm": "Local", "sglang": "Local",
+ "github-copilot": "GitHub", "deepinfra": "DeepInfra", "together": "Together AI", "fireworks": "Fireworks AI",
+ "parasail": "Parasail",
+}
+
+
+def _account_flow(provider: str) -> ProviderFlow | None:
+ module_name = _ACCOUNT_FLOW_MODULES.get(provider)
+ if module_name is None:
+ return None
+ import importlib
+
+ module = importlib.import_module(f".{module_name}", __package__)
+ for name in dir(module):
+ candidate = getattr(module, name)
+ if isinstance(candidate, type) and issubclass(candidate, ProviderFlow) and candidate is not ProviderFlow:
+ return candidate()
+ raise RuntimeError(f"no flow class in lm15.login.flows.{module_name}")
+
+
+def _recipe_methods(provider: str) -> tuple[LoginMethod, ...]:
+ definition = PROVIDERS.get(provider)
+ methods: list[LoginMethod] = []
+ for source, (route, _label) in EXTERNAL_SOURCES.items():
+ if route == provider:
+ methods.append(external_method(source))
+ if definition is None:
+ return tuple(methods)
+ access = definition.access
+ if access.cloud_chain:
+ from ...features import NAMED_CREDENTIALS
+
+ methods.append(LoginMethod(
+ id="cloud", label="Use a named cloud identity", kind="cloud_identity", flow="source_recipe",
+ fields=(MethodField(id="named", label="Identity", type="select",
+ options=tuple(SelectOption(n, n) for n in NAMED_CREDENTIALS)),),
+ billing_note="Billed to that cloud account.",
+ ))
+ if definition.placeholder_key is not None:
+ methods.append(LoginMethod(
+ id="local", label="Local server (no key needed)", kind="local_server", flow="source_recipe",
+ fields=(MethodField(id="base_url", label="Server URL", required=False),),
+ ))
+ return tuple(methods)
+ if access.credential_policy in ("key", "oauth-unless-explicit", "connection", "aws-chain", "azure-chain", "gcp-chain"):
+ if access.credential_policy != "connection" or provider in _ACCOUNT_FLOW_MODULES:
+ methods.append(api_key_method(definition.console_url))
+ if access.env_keys:
+ methods.append(env_method(tuple(access.env_keys)))
+ return tuple(methods)
+
+
+@lru_cache(maxsize=None)
+def _table() -> dict[str, tuple[ProviderDescriptor, ProviderFlow, ProviderFlow | None]]:
+ table: dict[str, tuple[ProviderDescriptor, ProviderFlow, ProviderFlow | None]] = {}
+ ids = sorted(set(PROVIDERS) | set(_ACCOUNT_FLOW_MODULES))
+ for provider in ids:
+ account = _account_flow(provider)
+ recipe_methods = _recipe_methods(provider)
+ if account is not None:
+ base = account.descriptor
+ # The account flow's own api_key method (if any) is replaced by
+ # the registry-derived recipe methods so every provider shares
+ # one api_key/env implementation.
+ own = tuple(m for m in base.methods if m.kind == "account" and not m.id.startswith("external:"))
+ descriptor = ProviderDescriptor(
+ id=base.id, label=base.label, service=base.service, routes=base.routes,
+ methods=own + recipe_methods, docs_url=base.docs_url,
+ console_url=base.console_url or (PROVIDERS[provider].console_url if provider in PROVIDERS else None),
+ )
+ else:
+ definition = PROVIDERS[provider]
+ descriptor = ProviderDescriptor(
+ id=provider, label=provider, service=_SERVICE_LABELS.get(provider, provider),
+ routes=(provider,), methods=recipe_methods, console_url=definition.console_url,
+ )
+ recipe = RecipeFlow(provider, descriptor)
+ table[provider] = (descriptor, recipe, account)
+ # Radius: named in R11's inventory; its gateway wire protocol is not in
+ # lm15-python, so login alone would advertise a model connection that
+ # cannot make a request (AUTH-26). Listed, unavailable, honest.
+ table[RADIUS_ID] = (
+ ProviderDescriptor(
+ id=RADIUS_ID, label="Radius", service="Radius", routes=(),
+ methods=(LoginMethod(id="browser", label="Sign in with Radius", kind="account", flow="authorization_code",
+ availability="unavailable",
+ reason="Radius's model protocol is not implemented in lm15-python; login without "
+ "inference would be a false 'supported' claim"),),
+ ),
+ RecipeFlow(RADIUS_ID, ProviderDescriptor(id=RADIUS_ID, label="Radius", service="Radius", routes=(), methods=())),
+ None,
+ )
+ return table
+
+
+def provider_ids() -> tuple[str, ...]:
+ return tuple(sorted(_table()))
+
+
+def descriptor(provider: str) -> ProviderDescriptor:
+ canonical = canonical_provider(provider)
+ try:
+ return _table()[canonical][0]
+ except KeyError:
+ raise KeyError(provider) from None
+
+
+def flow(provider: str, method_id: str) -> ProviderFlow:
+ """The flow that implements ``method_id`` for ``provider``: the account
+ flow for its own methods, the recipe flow for the generated ones."""
+ canonical = canonical_provider(provider)
+ _descriptor, recipe, account = _table()[canonical]
+ if account is not None and any(m.id == method_id for m in account.descriptor.methods if m.kind == "account"):
+ return account
+ return recipe
+
+
+def flow_for_material(provider: str, material: Material) -> ProviderFlow:
+ canonical = canonical_provider(provider)
+ _descriptor, recipe, account = _table()[canonical]
+ kind = material.get("type")
+ if kind in ("api_key", "env", "external", "local", "cloud") and not material.get("minted"):
+ return recipe
+ if kind == "api_key" and material.get("minted") and account is not None:
+ return account
+ if account is not None:
+ return account
+ return recipe
diff --git a/dspy/_vendor/lm15/login/flows/base.py b/dspy/_vendor/lm15/login/flows/base.py
new file mode 100644
index 000000000..3ea1638b3
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/base.py
@@ -0,0 +1,109 @@
+"""
+lm15.login.flows.base — what a provider flow is.
+
+A flow describes one provider's login protocol and nothing else. The
+engine owns deadlines, cancellation, UI, HTTP bounds and device pacing; the
+store owns persistence; the manager owns lifecycle. A flow answers four
+questions:
+
+- ``login``: run the chosen method and return :class:`LoginResult`;
+- ``renew``: given the saved material, produce fresh material or raise
+ :class:`~lm15.login.engine.LoginDenied` (permanent: the manager marks
+ ``needs_login``);
+- ``request_auth``: derive what a request needs from valid material
+ (credential, extra headers, a credential-dependent base URL);
+- ``expiry``: read the material's actual expiry.
+
+Material is the provider-private dict saved under the provider's key in
+the store. For OAuth providers it follows the Pi/lm15 convention
+``{"type": "oauth", "access", "refresh", "expires"}`` so the entry stays
+readable by the legacy loader (xAI) and by Pi; ``expires`` is the actual
+expiry in epoch milliseconds (AUTH-20.2), ``issued_at`` its issue time,
+and ``lifetime_s`` the granted lifetime — the three numbers the ratified
+renewal lead (``min(300 s, lifetime / 10)``) is computed from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..engine import LoginContext
+from ..types import LoginMethod, ProviderDescriptor
+
+__all__ = ["ProviderFlow", "LoginResult", "RequestAuth", "oauth_material", "material_expiry_ms"]
+
+Material = dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class LoginResult:
+ material: Material = field(repr=False)
+ label: str
+ account_label: str | None = None
+ renewal: str = "refresh_token" # refresh_token | remint | none | external | recipe
+ settings: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class RequestAuth:
+ """What the adapter sends. ``credential`` is a str or an AUTH-2 value."""
+
+ credential: Any = field(repr=False)
+ headers: dict[str, str] = field(default_factory=dict)
+ base_url: str | None = None
+ account_id: str | None = None
+ named: str | None = None # a saved cloud recipe: the named identity to run (AUTH-15)
+
+
+def oauth_material(*, access: str, refresh: str | None, expires_in_s: float | None, now_ms: int,
+ extra: dict[str, Any] | None = None) -> Material:
+ """Build OAuth material with the actual expiry and the numbers the
+ renewal lead needs. ``expires_in_s=None`` records ``unknown``."""
+ material: Material = {"type": "oauth", "access": access}
+ if refresh:
+ material["refresh"] = refresh
+ material["issued_at"] = now_ms
+ if expires_in_s is not None and expires_in_s > 0:
+ material["lifetime_s"] = float(expires_in_s)
+ material["expires"] = int(now_ms + expires_in_s * 1000)
+ if extra:
+ material.update(extra)
+ return material
+
+
+def material_expiry_ms(material: Material) -> int | None:
+ value = material.get("expires")
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
+ return None
+ return int(value)
+
+
+class ProviderFlow:
+ """Subclass per provider. ``descriptor`` is the AUTH-13 description."""
+
+ descriptor: ProviderDescriptor
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ raise NotImplementedError
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ raise NotImplementedError
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ raise NotImplementedError
+
+ def expiry(self, material: Material) -> int | str | None:
+ """Actual expiry in epoch ms, ``"never"``, or ``None`` for unknown."""
+ if material.get("type") == "api_key":
+ return "never"
+ return material_expiry_ms(material)
+
+ def lifetime_s(self, material: Material) -> float | None:
+ value = material.get("lifetime_s")
+ if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0:
+ return float(value)
+ issued, expires = material.get("issued_at"), material_expiry_ms(material)
+ if isinstance(issued, (int, float)) and not isinstance(issued, bool) and expires:
+ return max((expires - int(issued)) / 1000.0, 0.0)
+ return None
diff --git a/dspy/_vendor/lm15/login/flows/claude.py b/dspy/_vendor/lm15/login/flows/claude.py
new file mode 100644
index 000000000..5b0c0c470
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/claude.py
@@ -0,0 +1,162 @@
+"""
+lm15.login.flows.claude — Claude subscription login owned by LM15.
+
+``browser`` uses Claude's hosted return page and asks for the displayed
+code#state (or the complete return URL). No local listener is needed: the
+browser and Python may run on different machines. This matches the observed
+Claude Code 2.1.280 manual login on 2026-09-23. ``loopback`` retains the
+older local callback flow from the Pi 0.87.0 implementation reference.
+
+**Availability: unverified** (AUTH-13.5, R1). Hosted LM15 login, inference,
+fresh-process persistence and an early renewal were observed on 2026-09-23.
+Provider permission and billing remain unresolved; loopback has no live LM15
+receipt. Both methods still need explicit opt-in. Existing externally owned
+CLI credentials remain available through ``lm15.login.flows.recipes``.
+"""
+
+from __future__ import annotations
+
+import secrets
+from typing import Any
+
+from ...auth import CLAUDE_CODE_CLIENT_ID
+from ...authkit import PKCEPair, generate_pkce, pkce_challenge
+from ...credentials import BearerToken
+from ...errors import AuthOperationError
+from ..engine import (
+ CallbackListener,
+ LoginContext,
+ LoginDenied,
+ ManualCodePrompt,
+ http_json,
+ await_return,
+ parse_manual_return,
+)
+from ..types import AuthUrlNotice, InfoNotice, LoginMethod, ProgressNotice, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth, oauth_material
+
+CLIENT_ID = CLAUDE_CODE_CLIENT_ID
+AUTHORIZE_URL = "https://claude.com/cai/oauth/authorize"
+LOOPBACK_AUTHORIZE_URL = "https://claude.ai/oauth/authorize"
+TOKEN_URL = "https://platform.claude.com/v1/oauth/token"
+CALLBACK_PORT = 53692
+CALLBACK_PATH = "/callback"
+REDIRECT_URI = "https://platform.claude.com/oauth/code/callback"
+LOOPBACK_REDIRECT_URI = f"http://localhost:{CALLBACK_PORT}{CALLBACK_PATH}"
+SCOPES = "org:create_api_key user:profile user:inference user:sessions:claude_code user:mcp_servers user:file_upload"
+
+METHOD_BROWSER = LoginMethod(
+ id="browser", label="Sign in with Claude (paste code from hosted page)", kind="account", flow="authorization_code",
+ availability="unverified",
+ reason="LM15 hosted login, inference, persistence and early renewal observed 2026-09-23; permission and billing remain unverified",
+ delivery=("manual",), subscription=True,
+ billing_note="Provider permission and included usage must be verified separately for your account.",
+)
+METHOD_LOOPBACK = LoginMethod(
+ id="loopback", label="Sign in with Claude (local browser callback)", kind="account", flow="authorization_code",
+ availability="unverified", reason="no live LM15 receipt for this local callback flow",
+ delivery=("loopback", "manual"), subscription=True,
+ billing_note=METHOD_BROWSER.billing_note,
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="claude-code", label="Claude (subscription)", service="Anthropic", routes=("claude-code",),
+ methods=(METHOD_BROWSER, METHOD_LOOPBACK,),
+ docs_url="https://docs.claude.com",
+)
+
+
+def _tokens(body: dict[str, Any], *, now_ms: int) -> Material:
+ access, refresh, expires_in = body.get("access_token"), body.get("refresh_token"), body.get("expires_in")
+ if not isinstance(access, str) or not access or not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("Claude token response is missing required fields")
+ lifetime = float(expires_in) if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool) and expires_in > 0 else None
+ return oauth_material(access=access, refresh=refresh, expires_in_s=lifetime, now_ms=now_ms)
+
+
+class ClaudeFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id not in ("browser", "loopback"):
+ raise AuthOperationError("Unknown Claude login method", reason="method_unavailable",
+ stage="discovery", recovery="choose_method", provider="claude-code")
+ ctx.check()
+ hosted = method.id == "browser"
+ # 32 random bytes -> 43 characters, as in the captured native flow.
+ # Independent state remains essential; it is not the PKCE verifier.
+ verifier = secrets.token_urlsafe(32)
+ pkce = PKCEPair(verifier=verifier, challenge=pkce_challenge(verifier)) if hosted else generate_pkce()
+ state = secrets.token_urlsafe(32)
+ redirect_uri = REDIRECT_URI if hosted else LOOPBACK_REDIRECT_URI
+ authorize_url = AUTHORIZE_URL if hosted else LOOPBACK_AUTHORIZE_URL
+ listener: CallbackListener | None = None
+ try:
+ if not hosted:
+ try:
+ listener = CallbackListener(path=CALLBACK_PATH, expected_state=state, port=CALLBACK_PORT,
+ redirect_host="localhost")
+ listener.start()
+ except AuthOperationError as exc:
+ if exc.reason != "method_unavailable":
+ raise
+ ctx.notify(InfoNotice(f"Could not listen on port {CALLBACK_PORT}; "
+ "paste the full redirect URL when the browser finishes."))
+ query = {
+ "code": "true", "client_id": CLIENT_ID, "response_type": "code", "redirect_uri": redirect_uri,
+ "scope": SCOPES, "code_challenge": pkce.challenge, "code_challenge_method": "S256", "state": state,
+ }
+ import urllib.parse
+
+ url = f"{authorize_url}?{urllib.parse.urlencode(query)}"
+ instructions = (
+ "Sign in to Claude in your browser. On the Authentication code page, copy the whole "
+ "displayed code (including #state) and paste it here. The full return URL also works. "
+ "Your browser may be on another machine; no localhost connection is needed."
+ if hosted else
+ "Sign in to Claude in your browser. If the local callback cannot be reached, "
+ "paste the full redirect URL (or code#state) here."
+ )
+ ctx.notify(AuthUrlNotice(url=url, instructions=instructions))
+ prompt = ManualCodePrompt(
+ field_id="return", label="Paste the full code#state or return URL here",
+ accepted="the full return URL, or code#state (a bare code without state is not accepted)",
+ )
+ returned = await_return(ctx, listener, prompt, lambda pasted: parse_manual_return(
+ pasted, expected_state=state, allow_bare_code=False,
+ registered_path=urllib.parse.urlsplit(redirect_uri).path, registered_uri=redirect_uri,
+ ))
+ ctx.check()
+ ctx.notify(ProgressNotice(stage="exchange", message="Exchanging the authorization code…"))
+ reply = http_json(ctx, TOKEN_URL, {
+ "grant_type": "authorization_code", "code": returned.code, "redirect_uri": redirect_uri,
+ "client_id": CLIENT_ID, "code_verifier": pkce.verifier, "state": state,
+ })
+ if not reply.ok:
+ raise LoginDenied(
+ f"Claude authorization-code exchange failed: {reply.failure_summary()}. "
+ "The authorization code will not be retried automatically.",
+ status=reply.status, provider_code=reply.oauth_error, stage="exchange",
+ )
+ ctx.check()
+ return LoginResult(material=_tokens(reply.body, now_ms=int(ctx.wall_clock() * 1000)),
+ label="Claude subscription", renewal="refresh_token")
+ finally:
+ if listener is not None:
+ listener.stop()
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ refresh = material.get("refresh")
+ if not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("Claude credential has no refresh token")
+ reply = http_json(ctx, TOKEN_URL, {"grant_type": "refresh_token", "client_id": CLIENT_ID, "refresh_token": refresh})
+ if not reply.ok:
+ raise LoginDenied(
+ f"Claude token renewal failed: {reply.failure_summary()}",
+ status=reply.status, provider_code=reply.oauth_error, stage="renewal",
+ )
+ return LoginResult(material=_tokens(reply.body, now_ms=int(ctx.wall_clock() * 1000)),
+ label="Claude subscription", renewal="refresh_token")
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ return RequestAuth(credential=BearerToken(material["access"]))
diff --git a/dspy/_vendor/lm15/login/flows/codex.py b/dspy/_vendor/lm15/login/flows/codex.py
new file mode 100644
index 000000000..4c9db0b5f
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/codex.py
@@ -0,0 +1,205 @@
+"""
+lm15.login.flows.codex — ChatGPT (Codex) subscription login owned by LM15.
+
+Two methods: ``browser`` (authorization-code + PKCE, loopback return on the
+registered ``localhost:1455`` redirect, manual paste alternative) and
+``device`` (OpenAI's device-authorization endpoints, which return an
+authorization code + verifier pair that is then exchanged like the browser
+flow). Pi 0.87.0 ``oauth/openai-codex.ts`` is the implementation
+reference; the client id is the Codex CLI's.
+
+**Availability: unverified** (AUTH-13.5, R1). On 2026-09-23, browser login,
+model discovery, inference, fresh-process persistence and early renewal worked
+with a managed grant. Device login and inference also worked with a separate
+memory-only grant. Provider permission and billing remain unresolved; device
+renewal/persistence were not separately exercised. Existing CLI access remains
+available via the external source.
+"""
+
+from __future__ import annotations
+
+import secrets
+import urllib.parse
+from typing import Any
+
+from ...auth import extract_chatgpt_account_id, jwt_expires_at_ms
+from ...authkit import generate_pkce
+from ...credentials import BearerToken
+from ..engine import (
+ CallbackListener,
+ DeviceStep,
+ LoginContext,
+ LoginDenied,
+ ManualCodePrompt,
+ http_form,
+ http_json,
+ await_return,
+ parse_manual_return,
+ run_device_flow,
+)
+from ..types import AuthUrlNotice, DeviceCodeNotice, InfoNotice, LoginMethod, ProgressNotice, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth, oauth_material
+
+CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann"
+AUTH_BASE = "https://auth.openai.com"
+AUTHORIZE_URL = f"{AUTH_BASE}/oauth/authorize"
+TOKEN_URL = f"{AUTH_BASE}/oauth/token"
+CALLBACK_PORT = 1455
+CALLBACK_PATH = "/auth/callback"
+REDIRECT_URI = f"http://localhost:{CALLBACK_PORT}{CALLBACK_PATH}"
+DEVICE_USER_CODE_URL = f"{AUTH_BASE}/api/accounts/deviceauth/usercode"
+DEVICE_TOKEN_URL = f"{AUTH_BASE}/api/accounts/deviceauth/token"
+DEVICE_VERIFICATION_URL = f"{AUTH_BASE}/codex/device"
+DEVICE_REDIRECT_URI = f"{AUTH_BASE}/deviceauth/callback"
+DEVICE_TIMEOUT_S = 15 * 60
+SCOPE = "openid profile email offline_access"
+
+_UNVERIFIED = "provider permission and billing remain unverified"
+
+METHOD_BROWSER = LoginMethod(
+ id="browser", label="Sign in with ChatGPT (browser)", kind="account", flow="authorization_code",
+ availability="unverified", reason="Browser login, inference, persistence and early renewal observed 2026-09-23; " + _UNVERIFIED,
+ delivery=("loopback", "manual"), subscription=True,
+)
+METHOD_DEVICE = LoginMethod(
+ id="device", label="Sign in with ChatGPT (device code, for SSH/headless)", kind="account", flow="device_code",
+ availability="unverified", reason="Device login and inference observed 2026-09-23; " + _UNVERIFIED,
+ delivery=("device",), subscription=True,
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="openai-codex", label="ChatGPT (subscription)", service="OpenAI", routes=("openai-codex",),
+ methods=(METHOD_BROWSER, METHOD_DEVICE),
+)
+
+
+def _tokens(body: dict[str, Any], *, now_ms: int) -> Material:
+ access, refresh, expires_in = body.get("access_token"), body.get("refresh_token"), body.get("expires_in")
+ if not isinstance(access, str) or not access or not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("ChatGPT token response is missing required fields")
+ lifetime = float(expires_in) if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool) and expires_in > 0 else None
+ if lifetime is None:
+ exp = jwt_expires_at_ms(access)
+ if exp is not None:
+ lifetime = max((exp + 5 * 60 * 1000 - now_ms) / 1000.0, 0.0) or None
+ account = extract_chatgpt_account_id(access)
+ if not account:
+ raise LoginDenied("ChatGPT token carries no account id")
+ extra: dict[str, Any] = {"accountId": account}
+ id_token = body.get("id_token")
+ if isinstance(id_token, str) and id_token:
+ extra["id_token"] = id_token
+ return oauth_material(access=access, refresh=refresh, expires_in_s=lifetime, now_ms=now_ms, extra=extra)
+
+
+class CodexFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id == "device":
+ return self._login_device(ctx)
+ if method.id == "browser":
+ return self._login_browser(ctx)
+ raise ValueError(method.id)
+
+ def _exchange(self, ctx: LoginContext, code: str, verifier: str, redirect_uri: str) -> LoginResult:
+ ctx.notify(ProgressNotice(stage="exchange", message="Exchanging the authorization code…"))
+ reply = http_form(ctx, TOKEN_URL, {
+ "grant_type": "authorization_code", "client_id": CLIENT_ID, "code": code,
+ "code_verifier": verifier, "redirect_uri": redirect_uri,
+ })
+ if not reply.ok:
+ raise LoginDenied(f"ChatGPT rejected the authorization code (HTTP {reply.status})")
+ material = _tokens(reply.body, now_ms=int(ctx.wall_clock() * 1000))
+ return LoginResult(material=material, label="ChatGPT subscription", renewal="refresh_token",
+ account_label=material.get("accountId"))
+
+ def _login_browser(self, ctx: LoginContext) -> LoginResult:
+ pkce = generate_pkce()
+ state = secrets.token_hex(16)
+ listener: CallbackListener | None
+ try:
+ listener = CallbackListener(path=CALLBACK_PATH, expected_state=state, port=CALLBACK_PORT,
+ redirect_host="localhost")
+ listener.start()
+ except Exception as exc:
+ listener = None
+ ctx.notify(InfoNotice(f"Could not listen on port {CALLBACK_PORT} ({type(exc).__name__}); "
+ "paste the redirect URL when the browser finishes."))
+ try:
+ query = {
+ "response_type": "code", "client_id": CLIENT_ID, "redirect_uri": REDIRECT_URI, "scope": SCOPE,
+ "code_challenge": pkce.challenge, "code_challenge_method": "S256", "state": state,
+ "id_token_add_organizations": "true", "codex_cli_simplified_flow": "true", "originator": "lm15",
+ }
+ url = f"{AUTHORIZE_URL}?{urllib.parse.urlencode(query)}"
+ ctx.notify(AuthUrlNotice(url=url, instructions=(
+ "Sign in to ChatGPT in your browser. If the browser is on another machine, paste the final "
+ "redirect URL back here.")))
+ prompt = ManualCodePrompt(field_id="return", label="Paste the redirect URL here (or wait for the browser)")
+ returned = await_return(ctx, listener, prompt, lambda pasted: parse_manual_return(
+ pasted, expected_state=state, allow_bare_code=False, registered_path=CALLBACK_PATH))
+ return self._exchange(ctx, returned.code, pkce.verifier, REDIRECT_URI)
+ finally:
+ if listener is not None:
+ listener.stop()
+
+ def _login_device(self, ctx: LoginContext) -> LoginResult:
+ reply = http_json(ctx, DEVICE_USER_CODE_URL, {"client_id": CLIENT_ID})
+ if not reply.ok:
+ if reply.status == 404:
+ raise LoginDenied("ChatGPT device-code login is not enabled for this server; use the browser method")
+ raise LoginDenied(f"ChatGPT refused to start a device authorization (HTTP {reply.status})")
+ body = reply.body
+ device_id, user_code = body.get("device_auth_id"), body.get("user_code")
+ interval = body.get("interval")
+ if isinstance(interval, str):
+ try:
+ interval = float(interval.strip())
+ except ValueError:
+ interval = None
+ if not isinstance(device_id, str) or not device_id or not isinstance(user_code, str) or not user_code:
+ raise LoginDenied("ChatGPT device authorization response is missing required fields")
+ interval_s = float(interval) if isinstance(interval, (int, float)) and not isinstance(interval, bool) and interval >= 0 else None
+ ctx.notify(DeviceCodeNotice(user_code=user_code, verification_url=DEVICE_VERIFICATION_URL,
+ expires_in_s=DEVICE_TIMEOUT_S, interval_s=interval_s or 5.0))
+
+ def poll() -> DeviceStep:
+ reply = http_json(ctx, DEVICE_TOKEN_URL, {"device_auth_id": device_id, "user_code": user_code})
+ if reply.ok:
+ code, verifier = reply.body.get("authorization_code"), reply.body.get("code_verifier")
+ if not isinstance(code, str) or not code or not isinstance(verifier, str) or not verifier:
+ raise LoginDenied("ChatGPT device token response is missing required fields")
+ return DeviceStep("complete", (code, verifier))
+ if reply.status in (403, 404):
+ return DeviceStep("pending")
+ error = reply.body.get("error")
+ error_code = error.get("code") if isinstance(error, dict) else error
+ if error_code == "deviceauth_authorization_pending":
+ return DeviceStep("pending")
+ if error_code == "slow_down":
+ return DeviceStep("slow_down")
+ raise LoginDenied(f"ChatGPT device authorization failed (HTTP {reply.status})")
+
+ code, verifier = run_device_flow(ctx, poll, interval_s=interval_s, expires_in_s=DEVICE_TIMEOUT_S,
+ wait_before_first_poll=True)
+ return self._exchange(ctx, code, verifier, DEVICE_REDIRECT_URI)
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ refresh = material.get("refresh")
+ if not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("ChatGPT credential has no refresh token")
+ reply = http_form(ctx, TOKEN_URL, {"grant_type": "refresh_token", "refresh_token": refresh, "client_id": CLIENT_ID})
+ if not reply.ok:
+ raise LoginDenied(f"ChatGPT rejected the refresh token (HTTP {reply.status})")
+ body = dict(reply.body)
+ if not body.get("refresh_token"):
+ body["refresh_token"] = refresh # OpenAI may omit it when it does not rotate
+ material = _tokens(body, now_ms=int(ctx.wall_clock() * 1000))
+ return LoginResult(material=material, label="ChatGPT subscription", renewal="refresh_token",
+ account_label=material.get("accountId"))
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ account = material.get("accountId") or extract_chatgpt_account_id(material["access"])
+ return RequestAuth(credential=BearerToken(material["access"]),
+ headers={"chatgpt-account-id": account} if account else {}, account_id=account)
diff --git a/dspy/_vendor/lm15/login/flows/copilot.py b/dspy/_vendor/lm15/login/flows/copilot.py
new file mode 100644
index 000000000..355ba25a3
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/copilot.py
@@ -0,0 +1,177 @@
+"""
+lm15.login.flows.copilot — GitHub Copilot login.
+
+GitHub's device flow (``login/device/code``) yields a GitHub token, which
+is stored as ``refresh``; each request-time renewal exchanges it at
+``copilot_internal/v2/token`` for a short-lived Copilot token whose
+``proxy-ep`` field names the account's API host (AUTH-20.9: that host is
+validated against GitHub's own domains before it is used as a base URL).
+Enterprise accounts supply their GHE domain as a method field; it becomes
+a provider *instance* setting, not a guess.
+
+Deliberately **not** done here (AUTH-17, D17): Pi enables account model
+policies during login (``POST /models/{id}/policy``). That changes account
+settings; LM15 does not do it inside authentication. A future explicit
+``enable_models`` operation may.
+
+**Availability: unverified** pending provider-permission review. On
+2026-09-23: github.com device login, Copilot token exchange, account model
+catalog (59 models), gpt-4.1 inference, fresh-process persistence and one early
+renewal were observed live. The ``github-copilot`` route remains a declared
+provider (no contract wire receipt yet). GitHub requires a person to click
+**Authorize** on the consent page; automation must not bypass that.
+"""
+
+from __future__ import annotations
+
+import re
+import urllib.parse
+from typing import Any
+
+from ...credentials import BearerToken
+from ..engine import DeviceStep, LoginContext, LoginDenied, http_form, http_get, run_device_flow
+from ..types import DeviceCodeNotice, LoginMethod, MethodField, ProgressNotice, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth
+
+CLIENT_ID = "Iv1.b507a08c87ecfe98" # GitHub Copilot Chat's public OAuth app id
+COPILOT_HEADERS = {
+ "User-Agent": "GitHubCopilotChat/0.35.0",
+ "Editor-Version": "vscode/1.107.0",
+ "Editor-Plugin-Version": "copilot-chat/0.35.0",
+ "Copilot-Integration-Id": "vscode-chat",
+}
+DEFAULT_DOMAIN = "github.com"
+DEFAULT_API_BASE = "https://api.individual.githubcopilot.com"
+
+METHOD_DEVICE = LoginMethod(
+ id="device", label="Sign in with GitHub (Copilot subscription)", kind="account", flow="device_code",
+ availability="unverified",
+ reason="Login, catalog, inference, persistence and early renewal observed 2026-09-23; permission review pending",
+ delivery=("device",), subscription=True,
+ fields=(MethodField(id="enterprise_domain", label="GitHub Enterprise domain (blank for github.com)",
+ required=False, help="e.g. company.ghe.com"),),
+ billing_note="Some models require enabling on your account first; LM15 does not change that setting during login.",
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="github-copilot", label="GitHub Copilot", service="GitHub", routes=("github-copilot",),
+ methods=(METHOD_DEVICE,),
+)
+
+
+def _domain(settings: dict[str, str]) -> str:
+ raw = (settings.get("enterprise_domain") or "").strip()
+ if not raw:
+ return DEFAULT_DOMAIN
+ parsed = urllib.parse.urlsplit(raw if "://" in raw else f"https://{raw}")
+ host = parsed.hostname
+ if not host or not re.fullmatch(r"[a-z0-9.-]+", host):
+ raise LoginDenied("invalid GitHub Enterprise domain")
+ return host
+
+
+def _urls(domain: str) -> dict[str, str]:
+ return {
+ "device": f"https://{domain}/login/device/code",
+ "token": f"https://{domain}/login/oauth/access_token",
+ "copilot": f"https://api.{domain}/copilot_internal/v2/token",
+ }
+
+
+def base_url_for(material: Material, settings: dict[str, str]) -> str:
+ """The account's API host from the Copilot token, validated against
+ GitHub's domains; never an arbitrary host a token string names."""
+ token = material.get("access", "")
+ match = re.search(r"proxy-ep=([^;]+)", token if isinstance(token, str) else "")
+ domain = _domain(settings)
+ if match:
+ host = match.group(1).strip().lower()
+ api_host = re.sub(r"^proxy\.", "api.", host)
+ allowed = (".githubcopilot.com",) if domain == DEFAULT_DOMAIN else (f".{domain}", ".githubcopilot.com")
+ if re.fullmatch(r"[a-z0-9.-]+", api_host) and any(api_host.endswith(suffix) for suffix in allowed):
+ return f"https://{api_host}"
+ if domain != DEFAULT_DOMAIN:
+ return f"https://copilot-api.{domain}"
+ return DEFAULT_API_BASE
+
+
+def _exchange(ctx: LoginContext, github_token: str, settings: dict[str, str]) -> Material:
+ reply = http_get(ctx, _urls(_domain(settings))["copilot"], headers={
+ "Authorization": f"Bearer {github_token}", **COPILOT_HEADERS,
+ })
+ if reply.status in (401, 403):
+ raise LoginDenied("GitHub rejected the token for Copilot; sign in again")
+ if not reply.ok:
+ raise LoginDenied(f"Copilot token exchange failed (HTTP {reply.status})")
+ token, expires_at = reply.body.get("token"), reply.body.get("expires_at")
+ if not isinstance(token, str) or not token or not isinstance(expires_at, (int, float)) or isinstance(expires_at, bool):
+ raise LoginDenied("Copilot token response is missing required fields")
+ now_ms = int(ctx.wall_clock() * 1000)
+ expires_ms = int(expires_at * 1000)
+ return {"type": "oauth", "access": token, "refresh": github_token, "issued_at": now_ms,
+ "lifetime_s": max((expires_ms - now_ms) / 1000.0, 1.0), "expires": expires_ms}
+
+
+class CopilotFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ merged = dict(settings)
+ if answers.get("enterprise_domain"):
+ merged["enterprise_domain"] = answers["enterprise_domain"]
+ domain = _domain(merged)
+ urls = _urls(domain)
+ reply = http_form(ctx, urls["device"], {"client_id": CLIENT_ID, "scope": "read:user"},
+ headers={"User-Agent": COPILOT_HEADERS["User-Agent"]})
+ if not reply.ok:
+ raise LoginDenied(f"GitHub refused to start a device authorization (HTTP {reply.status})")
+ body = reply.body
+ device_code, user_code, verification = body.get("device_code"), body.get("user_code"), body.get("verification_uri")
+ if not isinstance(device_code, str) or not isinstance(user_code, str) or not isinstance(verification, str):
+ raise LoginDenied("GitHub device authorization response is missing required fields")
+ parsed = urllib.parse.urlsplit(verification)
+ if parsed.scheme not in ("https", "http") or not parsed.netloc:
+ raise LoginDenied("GitHub returned an untrusted verification URL")
+ interval = body.get("interval")
+ expires_in = body.get("expires_in")
+ interval_s = float(interval) if isinstance(interval, (int, float)) and not isinstance(interval, bool) and interval > 0 else None
+ expires_s = float(expires_in) if isinstance(expires_in, (int, float)) and not isinstance(expires_in, bool) and expires_in > 0 else None
+ ctx.notify(DeviceCodeNotice(user_code=user_code, verification_url=verification,
+ expires_in_s=expires_s or 900.0, interval_s=interval_s or 5.0))
+
+ def poll() -> DeviceStep:
+ reply = http_form(ctx, urls["token"], {
+ "client_id": CLIENT_ID, "device_code": device_code,
+ "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+ }, headers={"User-Agent": COPILOT_HEADERS["User-Agent"]})
+ token = reply.body.get("access_token")
+ if isinstance(token, str) and token:
+ return DeviceStep("complete", token)
+ error = reply.body.get("error")
+ if error == "authorization_pending":
+ return DeviceStep("pending")
+ if error == "slow_down":
+ value = reply.body.get("interval")
+ return DeviceStep("slow_down", interval_s=float(value) if isinstance(value, (int, float)) and value > 0 else None)
+ if error == "expired_token":
+ return DeviceStep("expired")
+ if error == "access_denied":
+ return DeviceStep("denied")
+ raise LoginDenied(f"GitHub device authorization failed (HTTP {reply.status})")
+
+ github_token = run_device_flow(ctx, poll, interval_s=interval_s, expires_in_s=expires_s)
+ ctx.notify(ProgressNotice(stage="exchange", message="Exchanging the GitHub token for a Copilot token…"))
+ material = _exchange(ctx, github_token, merged)
+ label = "GitHub Copilot" if domain == DEFAULT_DOMAIN else f"GitHub Copilot ({domain})"
+ return LoginResult(material=material, label=label, renewal="remint",
+ settings={"enterprise_domain": domain} if domain != DEFAULT_DOMAIN else {})
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ github_token = material.get("refresh")
+ if not isinstance(github_token, str) or not github_token:
+ raise LoginDenied("Copilot credential has no GitHub token to renew with")
+ return LoginResult(material=_exchange(ctx, github_token, settings), label="GitHub Copilot", renewal="remint")
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ return RequestAuth(credential=BearerToken(material["access"]), headers=dict(COPILOT_HEADERS),
+ base_url=base_url_for(material, settings))
diff --git a/dspy/_vendor/lm15/login/flows/kimi.py b/dspy/_vendor/lm15/login/flows/kimi.py
new file mode 100644
index 000000000..d5aa6068e
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/kimi.py
@@ -0,0 +1,122 @@
+"""
+lm15.login.flows.kimi — Kimi Code (subscription) device login.
+
+RFC 8628 against ``auth.kimi.com`` (JSON replies). The access token
+authenticates ``https://api.kimi.com/coding`` as a bearer — a different
+host from the metered ``moonshotai`` route, so this is its own route,
+``kimi-code``, bound to that base URL. Pi 0.87.0 ``oauth/kimi-coding.ts``
+is the implementation reference.
+
+**Availability: unverified** (no live LM15 receipt; the ``kimi-code`` route
+is registered but has no wire receipt either — AUTH-26 says so).
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+from ...credentials import BearerToken
+from ..engine import DeviceStep, LoginContext, LoginDenied, http_form, run_device_flow
+from ..types import DeviceCodeNotice, LoginMethod, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth, oauth_material
+
+CLIENT_ID = "17e5f671-d194-4dfb-9706-5516cb48c098"
+DEFAULT_OAUTH_HOST = "https://auth.kimi.com"
+DEVICE_TIMEOUT_S = 15 * 60.0
+
+METHOD_DEVICE = LoginMethod(
+ id="device", label="Sign in with Kimi Code (subscription)", kind="account", flow="device_code",
+ availability="unverified", reason="no live receipt yet", delivery=("device",), subscription=True,
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="kimi-code", label="Kimi Code (subscription)", service="Moonshot AI", routes=("kimi-code",),
+ methods=(METHOD_DEVICE,),
+)
+
+
+def _http_url(value: Any) -> str | None:
+ if not isinstance(value, str) or not value:
+ return None
+ parsed = urllib.parse.urlsplit(value)
+ return value if parsed.scheme in ("https", "http") and parsed.netloc else None
+
+
+def _positive(value: Any) -> float | None:
+ return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0 else None
+
+
+def _tokens(body: dict[str, Any], *, now_ms: int) -> Material:
+ access, refresh, expires_in = body.get("access_token"), body.get("refresh_token"), body.get("expires_in")
+ if not isinstance(access, str) or not access or not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("Kimi Code token response is missing required fields")
+ return oauth_material(access=access, refresh=refresh, expires_in_s=_positive(expires_in), now_ms=now_ms)
+
+
+def _host(settings: dict[str, str]) -> str:
+ return (settings.get("oauth_host") or DEFAULT_OAUTH_HOST).rstrip("/")
+
+
+class KimiFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ host = _host(settings)
+ reply = http_form(ctx, f"{host}/api/oauth/device_authorization", {"client_id": CLIENT_ID})
+ if not reply.ok:
+ raise LoginDenied(f"Kimi Code refused to start a device authorization (HTTP {reply.status})")
+ body = reply.body
+ device_code, user_code = body.get("device_code"), body.get("user_code")
+ verification = _http_url(body.get("verification_uri_complete")) or _http_url(body.get("verification_uri"))
+ if not isinstance(device_code, str) or not device_code or not isinstance(user_code, str) or not user_code or not verification:
+ raise LoginDenied("Kimi Code device authorization response is missing required fields")
+ interval, expires_in = _positive(body.get("interval")), _positive(body.get("expires_in")) or DEVICE_TIMEOUT_S
+ ctx.notify(DeviceCodeNotice(user_code=user_code, verification_url=verification,
+ expires_in_s=expires_in, interval_s=interval or 5.0))
+
+ def poll() -> DeviceStep:
+ reply = http_form(ctx, f"{host}/api/oauth/token", {
+ "client_id": CLIENT_ID, "device_code": device_code,
+ "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+ })
+ if reply.ok and isinstance(reply.body.get("access_token"), str):
+ return DeviceStep("complete", _tokens(reply.body, now_ms=int(ctx.wall_clock() * 1000)))
+ error = reply.body.get("error")
+ if error == "authorization_pending":
+ return DeviceStep("pending")
+ if error == "slow_down":
+ return DeviceStep("slow_down", interval_s=_positive(reply.body.get("interval")))
+ if error == "expired_token":
+ return DeviceStep("expired")
+ if error == "access_denied":
+ return DeviceStep("denied")
+ raise LoginDenied(f"Kimi Code device token request failed (HTTP {reply.status})")
+
+ material = run_device_flow(ctx, poll, interval_s=interval, expires_in_s=expires_in)
+ return LoginResult(material=material, label="Kimi Code subscription", renewal="refresh_token",
+ settings={"oauth_host": host} if host != DEFAULT_OAUTH_HOST else {})
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ refresh = material.get("refresh")
+ if not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("Kimi Code credential has no refresh token")
+ reply = http_form(ctx, f"{_host(settings)}/api/oauth/token", {
+ "client_id": CLIENT_ID, "grant_type": "refresh_token", "refresh_token": refresh,
+ })
+ if reply.status in (401, 403) or reply.body.get("error") == "invalid_grant":
+ raise LoginDenied(f"Kimi Code rejected the refresh token (HTTP {reply.status})")
+ if not reply.ok:
+ # 429/5xx are transient: the engine already raised ServerError for
+ # 5xx; a 429 here is reported as a denial of *this* renewal, not
+ # of the credential, by not marking needs_login (the manager only
+ # marks on LoginDenied).
+ from ...errors import RateLimitError
+
+ raise RateLimitError(f"Kimi Code rate-limited the token refresh (HTTP {reply.status})",
+ provider="kimi-code", status=reply.status)
+ return LoginResult(material=_tokens(reply.body, now_ms=int(ctx.wall_clock() * 1000)),
+ label="Kimi Code subscription", renewal="refresh_token")
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ return RequestAuth(credential=BearerToken(material["access"]))
diff --git a/dspy/_vendor/lm15/login/flows/meta.py b/dspy/_vendor/lm15/login/flows/meta.py
new file mode 100644
index 000000000..fc68d29f9
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/meta.py
@@ -0,0 +1,174 @@
+"""
+lm15.login.flows.meta — Meta (Muse Code subscription) device login + key mint.
+
+RFC 8628 device authorization against ``auth.meta.com`` (JSON replies);
+the identity token it returns is **not** accepted for inference, so it is
+exchanged at the Muse Code key-mint endpoint for the account's Muse Code
+Model API key. Renewal is a re-mint with the stored identity token
+(``renewal="remint"``); the identity token itself is not renewable, so a
+401/403 from the mint is a permanent rejection (``needs_login``). Muse
+Code 1.4.6 is the reference (Pi 0.87.0 ``oauth/meta.ts`` was the first).
+
+Live 2026-10-12 (lm15-contract ``receipts/2026-10-12-muse-code/``): the
+mint answers the same key on every call, so a re-mint never revokes the
+key Muse Code itself holds; the reply also names the API address
+(``base_url``) and the subscription (``is_subs_active``,
+``subs_tier_name``). The key serves all three Meta wires, and
+``muse-wonder-full-1.0`` (Power and Maximum Usage plans only) answers on
+it. The address is used as given when it is an https ``meta.ai`` host and
+refused otherwise: the key is never sent anywhere else.
+
+**Availability: unverified.** Meta's Model API terms (2026-10-09, § 3.2)
+say the Muse Code key "may not be used to access the Services outside the
+coding harness"; lm15 is not that harness. The descriptor says so.
+"""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import Any
+
+from ...credentials import ApiKey
+from ..engine import DeviceStep, LoginContext, LoginDenied, http_form, http_json, run_device_flow
+from ..types import DeviceCodeNotice, LoginMethod, ProgressNotice, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth
+
+CLIENT_ID = "1031625952748946" # Muse Code CLI
+DEVICE_AUTHORIZATION_URL = "https://auth.meta.com/oidc/device/authorization/"
+DEVICE_TOKEN_URL = "https://auth.meta.com/oidc/device/token/"
+KEY_MINT_URL = "https://api.meta.ai/muse-code/key"
+KEY_LIFETIME_S = 24 * 60 * 60.0 # no expiry in the reply; a daily re-mint is free (same key, 2026-10-12)
+TERMS_NOTE = ("Meta's Model API terms (§ 3.2) reserve the Muse Code key for Muse Code; using it here is outside "
+ "those terms and puts the Meta account at risk. Subscription traffic is Contributor mode by default "
+ "(Meta may train on it).")
+
+METHOD_DEVICE = LoginMethod(
+ id="device", label="Sign in with Meta (Muse subscription)", kind="account", flow="device_code",
+ availability="unverified", reason="login, mint and inference observed 2026-10-12; " + TERMS_NOTE,
+ delivery=("device",), subscription=True,
+ billing_note="Billed to the Muse Code plan when it is active (muse-wonder-full-1.0 needs Power or Maximum "
+ "Usage); without one, Meta bills the key pay-as-you-go.",
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="meta", label="Meta", service="Meta", routes=("meta", "meta-chat", "meta-anthropic"),
+ methods=(
+ METHOD_DEVICE,
+ LoginMethod(id="api_key", label="API key from dev.meta.ai", kind="api_key", flow="form"),
+ ),
+ console_url="https://dev.meta.ai",
+)
+
+
+def _http_url(value: Any) -> str | None:
+ if not isinstance(value, str) or not value:
+ return None
+ parsed = urllib.parse.urlsplit(value)
+ return value if parsed.scheme in ("https", "http") and parsed.netloc else None
+
+
+def _positive(value: Any) -> float | None:
+ return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0 else None
+
+
+def _api_base(value: Any) -> str | None:
+ """The mint's ``base_url`` when the key may go there: https, a
+ ``meta.ai`` host, no credentials in the URL. ``None`` when absent."""
+ if value is None:
+ return None
+ parsed = urllib.parse.urlsplit(value) if isinstance(value, str) else None
+ host = (parsed.hostname or "") if parsed else ""
+ if parsed is None or parsed.scheme != "https" or parsed.username or parsed.password or parsed.query \
+ or not (host == "meta.ai" or host.endswith(".meta.ai")):
+ raise LoginDenied("Meta named an API address outside meta.ai for the minted key; refusing to send it there")
+ return value.rstrip("/")
+
+
+def _plan(body: dict[str, Any]) -> str | None:
+ """Display text for the account's plan; ``None`` when the reply is silent."""
+ active = body.get("is_subs_active")
+ if active is True:
+ tier = body.get("subs_tier_name")
+ return tier if isinstance(tier, str) and tier else "Muse Code subscription"
+ if active is False:
+ return "no Muse Code subscription (pay-as-you-go)"
+ return None
+
+
+def _result(material: Material, body: dict[str, Any]) -> LoginResult:
+ return LoginResult(material=material, label="Meta (Muse subscription)", account_label=_plan(body),
+ renewal="remint")
+
+
+def _mint(ctx: LoginContext, identity_token: str) -> tuple[Material, dict[str, Any]]:
+ ctx.notify(ProgressNotice(stage="exchange", message="Enabling Meta Model API access…"))
+ reply = http_json(ctx, KEY_MINT_URL, {}, headers={
+ "Authorization": f"Bearer {identity_token}", "x-api-version": "1.0.0",
+ })
+ if reply.status in (401, 403):
+ raise LoginDenied("Meta session is no longer valid; sign in again")
+ if not reply.ok:
+ raise LoginDenied(f"Meta API key mint failed (HTTP {reply.status})")
+ key = reply.body.get("api_key")
+ if not isinstance(key, str) or not key:
+ action = _http_url(reply.body.get("action_url"))
+ raise LoginDenied("Meta did not issue an API key" + (f"; complete setup at {action}" if action else ""))
+ base_url = _api_base(reply.body.get("base_url"))
+ now_ms = int(ctx.wall_clock() * 1000)
+ material: Material = {"type": "oauth", "access": key, "refresh": identity_token, "issued_at": now_ms,
+ "lifetime_s": KEY_LIFETIME_S, "expires": int(now_ms + KEY_LIFETIME_S * 1000)}
+ if base_url is not None:
+ material["base_url"] = base_url
+ return material, reply.body
+
+
+class MetaFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id != "device":
+ raise ValueError(method.id)
+ reply = http_form(ctx, DEVICE_AUTHORIZATION_URL, {"client_id": CLIENT_ID})
+ if not reply.ok:
+ raise LoginDenied(f"Meta refused to start a device authorization (HTTP {reply.status})")
+ body = reply.body
+ device_code, user_code = body.get("device_code"), body.get("user_code")
+ verification = _http_url(body.get("verification_uri_complete")) or _http_url(body.get("verification_uri"))
+ if not isinstance(device_code, str) or not device_code or not isinstance(user_code, str) or not user_code or not verification:
+ raise LoginDenied("Meta device authorization response is missing required fields")
+ interval, expires_in = _positive(body.get("interval")), _positive(body.get("expires_in"))
+ ctx.notify(DeviceCodeNotice(user_code=user_code, verification_url=verification,
+ expires_in_s=expires_in or 900.0, interval_s=interval or 5.0))
+
+ def poll() -> DeviceStep:
+ reply = http_form(ctx, DEVICE_TOKEN_URL, {
+ "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+ "device_code": device_code, "client_id": CLIENT_ID,
+ })
+ token = reply.body.get("access_token")
+ if reply.ok and isinstance(token, str) and token:
+ return DeviceStep("complete", token)
+ error = reply.body.get("error")
+ if error == "authorization_pending":
+ return DeviceStep("pending")
+ if error == "slow_down":
+ return DeviceStep("slow_down", interval_s=_positive(reply.body.get("interval")))
+ if error == "access_denied":
+ return DeviceStep("denied")
+ if error == "expired_token":
+ return DeviceStep("expired")
+ raise LoginDenied(f"Meta device token request failed (HTTP {reply.status})")
+
+ identity = run_device_flow(ctx, poll, interval_s=interval, expires_in_s=expires_in)
+ return _result(*_mint(ctx, identity))
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ identity = material.get("refresh")
+ if not isinstance(identity, str) or not identity:
+ raise LoginDenied("Meta credential has no identity token to re-mint with")
+ return _result(*_mint(ctx, identity))
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ base_url = material.get("base_url")
+ return RequestAuth(credential=ApiKey(material["access"]),
+ base_url=base_url if isinstance(base_url, str) and base_url else None)
diff --git a/dspy/_vendor/lm15/login/flows/openrouter.py b/dspy/_vendor/lm15/login/flows/openrouter.py
new file mode 100644
index 000000000..4acf9e9f1
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/openrouter.py
@@ -0,0 +1,104 @@
+"""
+lm15.login.flows.openrouter — OpenRouter sign-in that mints an API key.
+
+PKCE (S256) authorization at ``openrouter.ai/auth``; the return code is
+exchanged at ``/api/v1/auth/keys`` for a **permanent, user-controlled API
+key**, not an expiring token pair (AUTH-12: an account flow may produce a
+key). The callback is a one-shot loopback listener on an ephemeral port
+with a random path, raced against a manual paste. No client id: OpenRouter
+binds the key to the callback URL and the PKCE verifier.
+
+**Availability: unverified** pending broader conformance/support review.
+Browser key issuance, limit inspection, model discovery, inference and
+fresh-process persistence were observed on 2026-09-23 with a $1-limited key.
+``kind=account`` means an authorization journey, not a subscription: requests
+spend the user's OpenRouter credits (AUTH-13.7).
+"""
+
+from __future__ import annotations
+
+import secrets
+import urllib.parse
+from typing import Any
+
+from ...authkit import generate_pkce
+from ...credentials import ApiKey
+from ..engine import (
+ CallbackListener,
+ LoginContext,
+ LoginDenied,
+ ManualCodePrompt,
+ http_json,
+ await_return,
+ parse_manual_return,
+)
+from ..types import AuthUrlNotice, LoginMethod, ProgressNotice, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth
+
+AUTHORIZE_URL = "https://openrouter.ai/auth"
+KEY_URL = "https://openrouter.ai/api/v1/auth/keys"
+
+METHOD_BROWSER = LoginMethod(
+ id="browser", label="Sign in with OpenRouter (creates an API key for this app)", kind="account",
+ flow="authorization_code", availability="unverified",
+ reason="Login, key limit, inference and persistence observed 2026-09-23; broader support review pending",
+ delivery=("loopback", "manual"), subscription=False,
+ billing_note="The minted key spends your OpenRouter credits like any other key.",
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="openrouter", label="OpenRouter", service="OpenRouter", routes=("openrouter",),
+ methods=(
+ METHOD_BROWSER,
+ LoginMethod(id="api_key", label="API key from openrouter.ai/keys", kind="api_key", flow="form"),
+ ),
+ console_url="https://openrouter.ai/keys",
+)
+
+
+def _exchange(ctx: LoginContext, code: str, verifier: str) -> Material:
+ reply = http_json(ctx, KEY_URL, {"code": code, "code_verifier": verifier, "code_challenge_method": "S256"})
+ if not reply.ok:
+ raise LoginDenied(f"OpenRouter rejected the authorization code (HTTP {reply.status})")
+ key = reply.body.get("key")
+ if not isinstance(key, str) or not key:
+ raise LoginDenied("OpenRouter returned no key")
+ return {"type": "api_key", "key": key, "minted": True}
+
+
+class OpenRouterFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id != "browser":
+ raise ValueError(method.id)
+ pkce = generate_pkce()
+ path = f"/oauth/callback/{secrets.token_urlsafe(24)}"
+ # No state parameter in OpenRouter's protocol: the one-time random
+ # callback path plus PKCE is the evidenced equivalent binding (AUTH-18).
+ listener = CallbackListener(path=path, expected_state=None, port=0)
+ listener.start()
+ try:
+ query = {"callback_url": listener.redirect_uri, "code_challenge": pkce.challenge, "code_challenge_method": "S256"}
+ url = f"{AUTHORIZE_URL}?{urllib.parse.urlencode(query)}"
+ ctx.notify(AuthUrlNotice(url=url, instructions=(
+ "Sign in to OpenRouter in your browser and approve the key. If the browser is on another "
+ "machine, paste the final redirect URL back here.")))
+ prompt = ManualCodePrompt(field_id="return", label="Paste the redirect URL or code here (or wait for the browser)",
+ accepted="the full redirect URL, or the code")
+ returned = await_return(ctx, listener, prompt, lambda pasted: parse_manual_return(
+ pasted, expected_state=None, allow_bare_code=True, registered_path=path))
+ ctx.notify(ProgressNotice(stage="exchange", message="Exchanging the code for an API key…"))
+ return LoginResult(material=_exchange(ctx, returned.code, pkce.verifier), label="OpenRouter (minted key)",
+ renewal="none")
+ finally:
+ listener.stop()
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ return LoginResult(material=dict(material), label="OpenRouter (minted key)", renewal="none")
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ return RequestAuth(credential=ApiKey(material["key"]))
+
+ def expiry(self, material: Material) -> int | str | None:
+ return "never"
diff --git a/dspy/_vendor/lm15/login/flows/recipes.py b/dspy/_vendor/lm15/login/flows/recipes.py
new file mode 100644
index 000000000..22d321f97
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/recipes.py
@@ -0,0 +1,169 @@
+"""
+lm15.login.flows.recipes — connections that are recipes, not tokens.
+
+Four kinds (AUTH-12 ``Connection.kind`` and AUTH-15's "recipe, not a
+captured token"):
+
+- ``api_key`` — a literal key the user typed or pasted (AUTH-16: literal
+ text, no interpolation). Stored as ``{"type": "api_key", "key": ...}``.
+- ``env`` — *use the key from this environment variable*. Stores the
+ variable's name, never its value; read at request time from the process
+ environment. This is how ``connect()`` offers an ambient key as an
+ explicit choice without copying it (R2/R3).
+- ``external`` — *use the login another tool owns*: the Claude Code CLI
+ (``~/.claude/.credentials.json``), the Codex CLI (``~/.codex/auth.json``),
+ or the Pi agent's xAI store. The file stays the owner; LM15 reads and
+ renews through the legacy loaders exactly as the unmanaged router does
+ (R1: existing access preserved, nothing copied). Availability is
+ ``supported`` because it is the path proven live since 2026-08-31.
+- ``local_server`` — a keyless local engine (ollama, vllm, sglang): records
+ the base URL and the preset's placeholder key.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ...credentials import ApiKey, BearerToken
+from ..engine import LoginContext, LoginDenied
+from ..types import LoginMethod, MethodField, ProviderDescriptor, SelectOption
+from .base import LoginResult, Material, ProviderFlow, RequestAuth
+
+EXTERNAL_SOURCES: dict[str, tuple[str, str]] = {
+ # source id -> (provider route, human label)
+ "claude-code-cli": ("claude-code", "your Claude Code login (~/.claude/.credentials.json)"),
+ "codex-cli": ("openai-codex", "your Codex CLI login (~/.codex/auth.json)"),
+ "pi-xai": ("xai", "your Pi agent xAI login (~/.pi/agent/auth.json)"),
+}
+
+
+def api_key_method(console_url: str | None = None) -> LoginMethod:
+ return LoginMethod(
+ id="api_key", label="Paste an API key", kind="api_key", flow="form",
+ fields=(MethodField(id="key", label="API key", type="secret"),),
+ guidance=f"Create one at {console_url}" if console_url else None,
+ billing_note="Metered per token by the provider.",
+ )
+
+
+def env_method(env_keys: tuple[str, ...]) -> LoginMethod:
+ return LoginMethod(
+ id="env", label=f"Use the key in ${env_keys[0]} from the environment", kind="api_key", flow="source_recipe",
+ fields=(MethodField(id="name", label="Environment variable", type="select",
+ options=tuple(SelectOption(k, f"${k}") for k in env_keys)),),
+ billing_note="Metered per token by the provider; the variable's value is read at request time, never saved.",
+ )
+
+
+def external_method(source: str) -> LoginMethod:
+ route, label = EXTERNAL_SOURCES[source]
+ return LoginMethod(
+ id=f"external:{source}", label=f"Use {label}", kind="account", flow="source_recipe",
+ availability="supported", subscription=True,
+ billing_note="Whatever that tool's login is entitled to; LM15 reads and renews it in place and copies nothing.",
+ guidance="Sign in with that tool first if it says no credential is present.",
+ )
+
+
+class RecipeFlow(ProviderFlow):
+ """One instance serves every provider: the material says what to do."""
+
+ def __init__(self, provider: str, descriptor: ProviderDescriptor) -> None:
+ self.provider = provider
+ self.descriptor = descriptor
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id == "api_key":
+ key = answers.get("key", "")
+ if not isinstance(key, str) or not key.strip():
+ raise LoginDenied("no API key was entered")
+ return LoginResult(material={"type": "api_key", "key": key.strip()}, label=f"{self.provider} API key",
+ renewal="none")
+ if method.id == "env":
+ name = answers.get("name", "")
+ if not name:
+ raise LoginDenied("no environment variable was chosen")
+ return LoginResult(material={"type": "env", "name": name}, label=f"{self.provider} key from ${name}",
+ renewal="recipe")
+ if method.id.startswith("external:"):
+ source = method.id.split(":", 1)[1]
+ if source not in EXTERNAL_SOURCES:
+ raise LoginDenied(f"unknown external source {source!r}")
+ _probe_external(source) # fail now, typed, if that tool has no login
+ return LoginResult(material={"type": "external", "source": source},
+ label=f"{self.provider} via {EXTERNAL_SOURCES[source][1]}", renewal="external")
+ if method.id == "cloud":
+ named = answers.get("named", "")
+ from ...features import NAMED_CREDENTIALS
+
+ if named not in NAMED_CREDENTIALS:
+ raise LoginDenied(f"choose one of {', '.join(NAMED_CREDENTIALS)}")
+ return LoginResult(material={"type": "cloud", "named": named}, label=f"{self.provider} via {named} identity",
+ renewal="recipe")
+ if method.id == "local":
+ base_url = answers.get("base_url") or settings.get("base_url") or ""
+ return LoginResult(material={"type": "local", "base_url": base_url, "key": answers.get("key") or "local"},
+ label=f"{self.provider} local server", renewal="none",
+ settings={"base_url": base_url} if base_url else {})
+ raise ValueError(method.id)
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ # Recipes have nothing to renew: the external loaders renew in place
+ # at request time; keys and env names do not expire.
+ return LoginResult(material=dict(material), label=self.provider, renewal=material.get("type", "none"))
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ kind = material.get("type")
+ if kind == "api_key":
+ return RequestAuth(credential=ApiKey(material["key"]))
+ if kind == "env":
+ name = material["name"]
+ value = os.environ.get(name, "")
+ if not value:
+ raise LoginDenied(f"${name} is not set in this process's environment")
+ return RequestAuth(credential=ApiKey(value))
+ if kind == "external":
+ return _external_auth(material["source"])
+ if kind == "local":
+ return RequestAuth(credential=ApiKey(material.get("key") or "local"), base_url=material.get("base_url") or None)
+ if kind == "cloud":
+ return RequestAuth(credential=None, named=material["named"])
+ raise LoginDenied(f"unknown connection material {kind!r}")
+
+ def expiry(self, material: Material) -> int | str | None:
+ kind = material.get("type")
+ if kind in ("api_key", "env", "local", "cloud"):
+ return "never"
+ return None # external: the owning tool knows
+
+
+def _probe_external(source: str) -> None:
+ from ... import auth as legacy
+
+ route = EXTERNAL_SOURCES[source][0]
+ if source == "claude-code-cli":
+ legacy.load_claude_code_credential()
+ elif source == "codex-cli":
+ legacy.load_codex_cli_credential()
+ elif source == "pi-xai":
+ legacy.load_xai_credential(legacy.PI_AGENT_AUTH_PATH)
+ else:
+ raise LoginDenied(f"unknown external source for {route}")
+
+
+def _external_auth(source: str) -> RequestAuth:
+ """Resolve through the legacy loader: locked, double-checked renewal
+ written back to the owning file (spec/auth.md AUTH-3/4)."""
+ from ... import auth as legacy
+
+ if source == "claude-code-cli":
+ return RequestAuth(credential=BearerToken(legacy.get_claude_code_access_token()))
+ if source == "codex-cli":
+ credential = legacy.get_codex_cli_access_token()
+ account = credential.account_id or legacy.extract_chatgpt_account_id(credential.access_token)
+ return RequestAuth(credential=BearerToken(credential.access_token),
+ headers={"chatgpt-account-id": account} if account else {}, account_id=account)
+ if source == "pi-xai":
+ return RequestAuth(credential=BearerToken(legacy.get_xai_access_token(legacy.PI_AGENT_AUTH_PATH)))
+ raise LoginDenied(f"unknown external source {source!r}")
diff --git a/dspy/_vendor/lm15/login/flows/xai.py b/dspy/_vendor/lm15/login/flows/xai.py
new file mode 100644
index 000000000..9d8d782ce
--- /dev/null
+++ b/dspy/_vendor/lm15/login/flows/xai.py
@@ -0,0 +1,130 @@
+"""
+lm15.login.flows.xai — xAI subscription login (RFC 8628 device code).
+
+Migrated from ``lm15.auth`` on 2026-09-22 (R2, R12): same protocol, same
+client id, same store entry (``{"xai": {"type": "oauth", ...}}``), new
+machinery underneath. ``lm15.auth.login_xai`` still exists and now runs
+this flow, so the legacy entry point and the managed manager share one
+implementation. Live receipt: the device flow, renewal and inference were
+validated before this migration through ``lm15.auth`` (2026-09-01); the
+managed path re-uses those exact requests and is marked ``supported`` on
+that basis. The managed path itself was then observed live on 2026-09-22/23:
+device login, inference, streaming, logout blocking the env key, fresh-process
+persistence and one early refresh-token renewal (HTTP 200).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...credentials import BearerToken
+from ..engine import DeviceStep, LoginContext, LoginDenied, http_form, run_device_flow
+from ..types import DeviceCodeNotice, LoginMethod, ProviderDescriptor
+from .base import LoginResult, Material, ProviderFlow, RequestAuth, oauth_material
+
+CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828"
+DEVICE_CODE_URL = "https://auth.x.ai/oauth2/device/code"
+TOKEN_URL = "https://auth.x.ai/oauth2/token"
+SCOPE = "openid profile email offline_access grok-cli:access api:access"
+DEFAULT_LIFETIME_S = 3600.0 # xAI omits expires_in on some replies; the value Pi and lm15 assumed since 2026-09-01
+
+METHOD_DEVICE = LoginMethod(
+ id="device", label="Sign in with SuperGrok or X Premium", kind="account", flow="device_code",
+ availability="supported", delivery=("device",), subscription=True,
+ billing_note="Subscription access per xAI's own recommendation (2026-09-01); the API key path is metered.",
+)
+
+DESCRIPTOR = ProviderDescriptor(
+ id="xai", label="xAI", service="xAI", routes=("xai",),
+ methods=(
+ METHOD_DEVICE,
+ LoginMethod(id="api_key", label="API key from console.x.ai", kind="api_key", flow="form",
+ fields=(), billing_note="Metered per token."),
+ ),
+ console_url="https://console.x.ai",
+)
+
+
+def _https(value: Any) -> str:
+ import urllib.parse
+
+ if isinstance(value, str):
+ parsed = urllib.parse.urlsplit(value)
+ if parsed.scheme == "https" and parsed.netloc:
+ return value
+ raise LoginDenied("xAI returned an untrusted verification URL")
+
+
+def _positive(value: Any) -> float | None:
+ return float(value) if isinstance(value, (int, float)) and not isinstance(value, bool) and value > 0 else None
+
+
+def _material_from_token(body: dict[str, Any], *, now_ms: int, previous_refresh: str | None) -> Material:
+ access = body.get("access_token")
+ if not isinstance(access, str) or not access:
+ raise LoginDenied("xAI token response carried no access token")
+ refresh = body.get("refresh_token")
+ if not isinstance(refresh, str) or not refresh:
+ refresh = previous_refresh # xAI may omit it when it does not rotate
+ lifetime = _positive(body.get("expires_in")) or DEFAULT_LIFETIME_S
+ return oauth_material(access=access, refresh=refresh, expires_in_s=lifetime, now_ms=now_ms)
+
+
+class XaiFlow(ProviderFlow):
+ descriptor = DESCRIPTOR
+
+ def login(self, ctx: LoginContext, method: LoginMethod, settings: dict[str, str], answers: dict[str, str]) -> LoginResult:
+ if method.id != "device":
+ raise ValueError(method.id)
+ reply = http_form(ctx, DEVICE_CODE_URL, {"client_id": CLIENT_ID, "scope": SCOPE, "referrer": "lm15"})
+ if not reply.ok:
+ raise LoginDenied(f"xAI refused to start a device authorization (HTTP {reply.status})")
+ body = reply.body
+ device_code, user_code = body.get("device_code"), body.get("user_code")
+ if not isinstance(device_code, str) or not device_code or not isinstance(user_code, str) or not user_code:
+ raise LoginDenied("xAI device authorization response is missing required fields")
+ verification = _https(body.get("verification_uri"))
+ complete = body.get("verification_uri_complete")
+ target = _https(complete) if isinstance(complete, str) and complete else verification
+ interval, expires_in = _positive(body.get("interval")), _positive(body.get("expires_in"))
+ ctx.notify(DeviceCodeNotice(user_code=user_code, verification_url=target,
+ expires_in_s=expires_in or 900.0, interval_s=interval or 5.0))
+
+ def poll() -> DeviceStep:
+ reply = http_form(ctx, TOKEN_URL, {
+ "grant_type": "urn:ietf:params:oauth:grant-type:device_code",
+ "client_id": CLIENT_ID, "device_code": device_code,
+ })
+ if reply.ok:
+ return DeviceStep("complete", _material_from_token(reply.body, now_ms=int(ctx.wall_clock() * 1000),
+ previous_refresh=None))
+ error = reply.body.get("error")
+ if error == "authorization_pending":
+ return DeviceStep("pending")
+ if error == "slow_down":
+ return DeviceStep("slow_down", interval_s=_positive(reply.body.get("interval")))
+ if error in ("access_denied", "authorization_denied"):
+ return DeviceStep("denied")
+ if error == "expired_token":
+ return DeviceStep("expired")
+ raise LoginDenied(f"xAI device token polling failed (HTTP {reply.status})")
+
+ material = run_device_flow(ctx, poll, interval_s=interval, expires_in_s=expires_in)
+ return LoginResult(material=material, label="xAI subscription", renewal="refresh_token")
+
+ def renew(self, ctx: LoginContext, material: Material, settings: dict[str, str]) -> LoginResult:
+ refresh = material.get("refresh")
+ if not isinstance(refresh, str) or not refresh:
+ raise LoginDenied("xAI credential has no refresh token")
+ reply = http_form(ctx, TOKEN_URL, {"grant_type": "refresh_token", "client_id": CLIENT_ID, "refresh_token": refresh})
+ if not reply.ok:
+ if reply.status in (400, 401, 403):
+ raise LoginDenied(f"xAI rejected the refresh token (HTTP {reply.status})")
+ raise LoginDenied(f"xAI refresh failed (HTTP {reply.status})")
+ return LoginResult(
+ material=_material_from_token(reply.body, now_ms=int(ctx.wall_clock() * 1000), previous_refresh=refresh),
+ label="xAI subscription", renewal="refresh_token",
+ )
+
+ def request_auth(self, material: Material, settings: dict[str, str]) -> RequestAuth:
+ return RequestAuth(credential=BearerToken(material["access"]))
diff --git a/dspy/_vendor/lm15/login/manager.py b/dspy/_vendor/lm15/login/manager.py
new file mode 100644
index 000000000..aa1584dfc
--- /dev/null
+++ b/dspy/_vendor/lm15/login/manager.py
@@ -0,0 +1,1078 @@
+"""
+lm15.login.manager — ``Auth``: one scope's connections, and their lifecycle.
+
+spec/auth.md AUTH-14 (construction is inert; scope is explicit), AUTH-17
+(what each operation may touch), AUTH-19 (generations, replacement, logout,
+cancellation ordered against commit), AUTH-20 (renewal under the lock with a
+durable in-flight marker; uncertainty is never retried blind), AUTH-24 (typed
+outcomes).
+
+Slots. A slot is one provider route in this scope (v1: instance is always
+``public``; a provider-specific setting such as a GHE domain travels on the
+connection). Each slot record in the store's ``_lm15.slots`` carries an
+*identity generation* (bumped on every new connection and on logout, never
+reused) and a *credential revision* (bumped on every renewal). A bound
+client pins ``(connection_id, generation)``; a general managed router
+consults the slot's current connection on every request.
+
+Legacy entries. A provider entry without a slot record (an xAI login made
+by ``lm15.auth.login_xai`` before 2026-09-22, or by Pi) is read as a
+connection with generation ``1`` and a stable id derived from the
+provider; the record is written on the first managed commit that touches
+the slot, so a file that was never touched by the manager is never
+rewritten.
+"""
+
+from __future__ import annotations
+
+import os
+import secrets
+import threading
+import time
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+from ..errors import AuthError, AuthOperationError, LM15Error, RateLimitError, ServerError, TransportError
+from .engine import ATTEMPT_LIFETIME_S, LoginCancelled, LoginContext, LoginDenied, LoginExpired
+from .flows import Material, RequestAuth, descriptor as _descriptor, flow as _flow, flow_for_material, provider_ids
+from .store import META_KEY, STORE_VERSION, FileStore, MemoryStore, Store
+from .types import AuthUI, Connection, ConnectionStatus, LoginMethod, ProviderDescriptor, SecretPrompt, SelectOption, \
+ SelectPrompt, TextPrompt, Verification
+
+__all__ = ["Auth", "AsyncAuth", "ForgetResult", "RENEWAL_LEAD_S"]
+
+RENEWAL_LEAD_S = 300.0 # AUTH-20.3: min(300 s, lifetime / 10)
+
+
+def _now_iso(clock: Callable[[], float]) -> str:
+ return datetime.fromtimestamp(clock(), tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _iso_ms(ms: int) -> str:
+ return datetime.fromtimestamp(ms / 1000.0, tz=timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+@dataclass(frozen=True, slots=True)
+class ForgetResult:
+ provider: str
+ forgot: bool
+ routes: tuple[str, ...]
+ identity_generation: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _RequestSnapshot(RequestAuth):
+ connection: Connection
+ route: str
+
+
+@dataclass
+class _Slot:
+ """A slot record as the manager reasons about it (non-secret)."""
+
+ provider: str
+ generation: int = 0
+ connection_id: str | None = None
+ revision: int = 0
+ kind: str = "account"
+ method_id: str = ""
+ instance_id: str = "public"
+ label: str = ""
+ account_label: str | None = None
+ created_at: str = ""
+ routes: tuple[str, ...] = ()
+ settings: dict[str, str] = field(default_factory=dict)
+ state: str = "ready" # ready | needs_login | indeterminate
+ renewal: str = "refresh_token"
+ logged_out: bool = False
+ renewal_in_flight: dict[str, Any] | None = None
+ attempt: dict[str, Any] | None = None
+ verification: dict[str, Any] | None = None
+ previous_ids: tuple[str, ...] = () # ids this slot held before (never reused; logout by an old id is a no-op)
+ legacy: bool = False # synthesized from an entry with no record
+
+ @classmethod
+ def from_record(cls, provider: str, record: dict[str, Any]) -> "_Slot":
+ def s(key: str, default: Any = "") -> Any:
+ value = record.get(key, default)
+ return value if value is not None else default
+
+ return cls(
+ provider=provider,
+ generation=int(s("generation", "0")), connection_id=record.get("connection_id"),
+ revision=int(s("revision", "0")), kind=s("kind", "account"), method_id=s("method_id"),
+ instance_id=s("instance_id", "public"), label=s("label"), account_label=record.get("account_label"),
+ created_at=s("created_at"), routes=tuple(s("routes", ())), settings=dict(s("settings", {})),
+ state=s("state", "ready"), renewal=s("renewal", "refresh_token"), logged_out=bool(record.get("logged_out")),
+ renewal_in_flight=record.get("renewal_in_flight"), attempt=record.get("attempt"),
+ verification=record.get("verification"), previous_ids=tuple(s("previous_ids", ())),
+ )
+
+ def to_record(self) -> dict[str, Any]:
+ record: dict[str, Any] = {
+ "generation": str(self.generation), "connection_id": self.connection_id, "revision": str(self.revision),
+ "kind": self.kind, "method_id": self.method_id, "instance_id": self.instance_id, "label": self.label,
+ "created_at": self.created_at, "routes": list(self.routes), "settings": dict(self.settings),
+ "state": self.state, "renewal": self.renewal,
+ }
+ if self.account_label:
+ record["account_label"] = self.account_label
+ if self.logged_out:
+ record["logged_out"] = True
+ if self.renewal_in_flight:
+ record["renewal_in_flight"] = self.renewal_in_flight
+ if self.attempt:
+ record["attempt"] = self.attempt
+ if self.verification:
+ record["verification"] = self.verification
+ if self.previous_ids:
+ record["previous_ids"] = list(self.previous_ids[-8:])
+ return record
+
+ def connection(self) -> Connection | None:
+ if not self.connection_id:
+ return None
+ return Connection(
+ id=self.connection_id, provider=self.provider, instance_id=self.instance_id, kind=self.kind,
+ method_id=self.method_id, routes=self.routes or (self.provider,), label=self.label or self.provider,
+ created_at=self.created_at, identity_generation=str(self.generation),
+ credential_revision=str(self.revision), settings=dict(self.settings), account_label=self.account_label,
+ )
+
+
+_LEGACY_METHOD = {"xai": "device", "claude-code": "external:claude-code-cli", "openai-codex": "external:codex-cli"}
+
+
+class Auth:
+ """A scope's connections. ``Auth.local()`` for the private file,
+ ``Auth.memory()`` for a process-lifetime store, ``Auth(store)`` for an
+ application-supplied one. Construction reads nothing (AUTH-14)."""
+
+ def __init__(self, store: Store, *, clock: Callable[[], float] = time.time,
+ monotonic: Callable[[], float] = time.monotonic, opener: Any = None,
+ sleep: Callable[[float], None] | None = None) -> None:
+ if not isinstance(store, Store):
+ raise TypeError("Auth(store) takes a lm15.login.Store")
+ self.store = store
+ self._clock = clock
+ self._monotonic = monotonic
+ self._opener = opener
+ self._sleep = sleep
+ self._active: dict[str, tuple[str, threading.Event]] = {} # provider -> (attempt id, cancel event)
+ self._lock = threading.RLock()
+ self._closed = False
+
+ @classmethod
+ def local(cls, path: str | os.PathLike[str] | None = None) -> "Auth":
+ return cls(FileStore(path))
+
+ @classmethod
+ def memory(cls) -> "Auth":
+ return cls(MemoryStore())
+
+ def __repr__(self) -> str:
+ return f"Auth({self.store!r})"
+
+ # ─── discovery (AUTH-13): definitions only ─────────────────────────
+
+ def providers(self) -> tuple[ProviderDescriptor, ...]:
+ return tuple(_descriptor(p) for p in provider_ids())
+
+ def methods(self, provider: str) -> tuple[LoginMethod, ...]:
+ return self.descriptor(provider).methods
+
+ def descriptor(self, provider: str) -> ProviderDescriptor:
+ try:
+ return _descriptor(provider)
+ except KeyError:
+ raise AuthOperationError(
+ f"{provider!r} is not a provider lm15 can connect; see Auth.providers()",
+ reason="method_unavailable", stage="discovery", recovery="choose_method",
+ provider=provider,
+ ) from None
+
+ # ─── store views ───────────────────────────────────────────────────
+
+ def _view(self, document: dict[str, Any], provider: str) -> tuple[_Slot, Material | None]:
+ meta = document.get(META_KEY) or {}
+ record = (meta.get("slots") or {}).get(provider)
+ material = document.get(provider)
+ if not isinstance(material, dict):
+ material = None
+ if record is not None:
+ return _Slot.from_record(provider, record), material
+ slot = _Slot(provider=provider)
+ if material is not None:
+ # A legacy entry: read as generation 1 with a stable id.
+ kind = "account" if material.get("type") == "oauth" else "api_key"
+ slot = _Slot(
+ provider=provider, generation=1, connection_id=f"legacy-{provider}", revision=1, kind=kind,
+ method_id=_LEGACY_METHOD.get(provider, "api_key"), label=f"{provider} (existing login)",
+ routes=(provider,), legacy=True,
+ renewal="refresh_token" if material.get("type") == "oauth" else "none",
+ )
+ return slot, material
+
+ def _route_view(self, document: dict[str, Any], provider: str) -> tuple[_Slot, Material | None]:
+ """An explicit route slot wins; otherwise use its advertised owner."""
+ slots = (document.get(META_KEY) or {}).get("slots") or {}
+ if provider in document or provider in slots:
+ return self._view(document, provider)
+ owners = [owner for owner, record in slots.items()
+ if provider in record.get("routes", ()) and provider in self.descriptor(owner).routes]
+ if len(owners) > 1:
+ raise AuthOperationError(
+ f"{provider}: multiple saved connections advertise this route; select a connection",
+ reason="connection_changed", stage="resolution", recovery="select_connection", provider=provider,
+ )
+ return self._view(document, owners[0] if owners else provider)
+
+ @staticmethod
+ def _put(document: dict[str, Any], slot: _Slot, material: Material | None) -> dict[str, Any]:
+ meta = document.setdefault(META_KEY, {"version": STORE_VERSION, "slots": {}})
+ meta.setdefault("version", STORE_VERSION)
+ meta.setdefault("slots", {})[slot.provider] = slot.to_record()
+ if material is None:
+ document.pop(slot.provider, None)
+ else:
+ document[slot.provider] = material
+ return document
+
+ # ─── inspection (AUTH-17: store reads only) ────────────────────────
+
+ def connections(self) -> tuple[Connection, ...]:
+ document = self.store.read()
+ providers = set(provider_ids())
+ found: list[Connection] = []
+ for key in sorted(document):
+ if key == META_KEY or key not in providers:
+ continue
+ slot, _ = self._view(document, key)
+ connection = slot.connection()
+ if connection is not None:
+ found.append(connection)
+ for key, record in ((document.get(META_KEY) or {}).get("slots") or {}).items():
+ if key in document:
+ continue
+ slot = _Slot.from_record(key, record)
+ connection = slot.connection()
+ if connection is not None:
+ found.append(connection)
+ return tuple(found)
+
+ def status(self, provider: str) -> ConnectionStatus:
+ provider = self.descriptor(provider).id
+ slot, material = self._route_view(self.store.read(), provider)
+ connection = slot.connection()
+ verification = None
+ if slot.verification:
+ verification = Verification(**slot.verification)
+ if connection is None:
+ return ConnectionStatus(provider=provider, presence="absent", usability="unknown",
+ logged_out=slot.logged_out,
+ detail="signed out; sign in again or pass a key explicitly" if slot.logged_out else None)
+ usability, expires, detail = self._usability(slot, material)
+ return ConnectionStatus(provider=provider, presence="saved", usability=usability, connection=connection,
+ expires_at=expires, verification=verification, detail=detail)
+
+ def _usability(self, slot: _Slot, material: Material | None) -> tuple[str, str | None, str | None]:
+ if slot.state == "needs_login":
+ return "needs_login", None, "the provider rejected the saved credential; sign in again"
+ if slot.state == "indeterminate" or slot.renewal_in_flight:
+ return "indeterminate", None, "a renewal was interrupted; sign in again to be safe"
+ if material is None:
+ return "needs_login", None, "credential material is missing"
+ flow = flow_for_material(slot.provider, material)
+ expiry = flow.expiry(material)
+ if expiry == "never":
+ return "ready", "never", None
+ if expiry is None:
+ return ("ready", "unknown", None) if material.get("type") == "external" else ("unknown", "unknown", None)
+ now_ms = int(self._clock() * 1000)
+ if now_ms >= expiry - self._lead_ms(flow.lifetime_s(material)):
+ if not self._renewable(slot, material):
+ return "needs_login", _iso_ms(expiry), "expired and not renewable"
+ return "renewal_due", _iso_ms(expiry), None
+ return "ready", _iso_ms(expiry), None
+
+ @staticmethod
+ def _lead_ms(lifetime_s: float | None) -> int:
+ lead = RENEWAL_LEAD_S if lifetime_s is None else min(RENEWAL_LEAD_S, lifetime_s / 10.0)
+ return int(lead * 1000)
+
+ @staticmethod
+ def _renewable(slot: _Slot, material: Material) -> bool:
+ if slot.renewal in ("none", "recipe"):
+ return False
+ return bool(material.get("refresh"))
+
+ # ─── login (AUTH-16/17/18/19) ──────────────────────────────────────
+
+ def login(
+ self,
+ provider: str,
+ method: str | LoginMethod | None = None,
+ *,
+ ui: AuthUI,
+ settings: dict[str, str] | None = None,
+ answers: dict[str, str] | None = None,
+ replace: str | None = None,
+ cancel: threading.Event | None = None,
+ lifetime_s: float = ATTEMPT_LIFETIME_S,
+ allow_unverified: bool = False,
+ ) -> Connection:
+ """Run one login to completion and save the connection.
+
+ ``method`` is a method id or descriptor; omitted, the UI is asked
+ when more than one selectable method remains (AUTH-13.6). ``replace``
+ names the connection id being replaced; without it an occupied slot
+ is ``connection_exists``. ``cancel`` is an event the caller may set
+ from another thread; Ctrl-C at a prompt cancels too. The login is
+ saved before this returns; a later failure elsewhere never undoes it.
+ """
+ self._check_open()
+ descriptor = self.descriptor(provider)
+ provider = descriptor.id
+ if not isinstance(lifetime_s, (int, float)) or lifetime_s <= 0:
+ raise ValueError("lifetime_s must be a positive number of seconds")
+ chosen = self._choose_method(descriptor, method, ui, allow_unverified=allow_unverified)
+ answers = dict(answers or {})
+ settings = dict(settings or {})
+ cancel = cancel or threading.Event()
+ deadline = self._monotonic() + float(lifetime_s)
+ ctx = LoginContext(ui=ui, deadline=deadline, cancel=cancel, provider=provider, clock=self._monotonic,
+ wall_clock=self._clock, opener=self._opener, sleep=self._sleep)
+ attempt_id = f"at_{secrets.token_urlsafe(16)}"
+ # Reservation (AUTH-17/18): storage proven writable, one active
+ # attempt per slot, generation observed — before any browser opens.
+ self.store.reserve()
+ try:
+ expected = self._reserve(provider, attempt_id, replace, lifetime_s, cancel=cancel)
+ for field_ in chosen.fields:
+ if field_.id not in answers:
+ if not field_.required and field_.type != "select":
+ answers[field_.id] = ctx.prompt(TextPrompt(field_.id, field_.label))
+ elif field_.type == "secret":
+ answers[field_.id] = ctx.prompt(SecretPrompt(field_.id, field_.label))
+ elif field_.type == "select":
+ answers[field_.id] = ctx.prompt(SelectPrompt(field_.id, field_.label, field_.options))
+ else:
+ answers[field_.id] = ctx.prompt(TextPrompt(field_.id, field_.label))
+ flow = _flow(provider, chosen.id)
+ try:
+ result = flow.login(ctx, chosen, settings, answers)
+ ctx.check()
+ except LoginCancelled:
+ self._release(provider, attempt_id)
+ raise
+ except LoginExpired as exc:
+ self._release(provider, attempt_id)
+ raise AuthOperationError(
+ f"{provider}: the sign-in was not completed within {int(lifetime_s // 60)} minutes; start again",
+ reason="login_expired", stage="polling", recovery="restart_login", provider=provider,
+ attempt_id=attempt_id, method_id=chosen.id,
+ ) from exc
+ except LoginDenied as exc:
+ self._release(provider, attempt_id)
+ raise AuthOperationError(
+ f"{provider}: {exc}", reason="login_denied", stage=exc.stage, recovery="restart_login",
+ provider=provider, attempt_id=attempt_id, method_id=chosen.id,
+ status=exc.status, provider_code=exc.provider_code,
+ ) from None
+ except TransportError as exc:
+ self._release(provider, attempt_id)
+ if getattr(exc, "exchange_uncertain", False):
+ raise AuthOperationError(
+ f"{provider}: the network failed after the authorization code may have been sent; the code "
+ "is one-use, so sign in again rather than retry",
+ reason="indeterminate", stage="exchange", commit_state="not_committed",
+ recovery="restart_login", provider=provider, attempt_id=attempt_id, method_id=chosen.id,
+ ) from exc
+ raise
+ except LM15Error:
+ self._release(provider, attempt_id)
+ raise
+ return self._commit(provider, attempt_id, expected, chosen, result, settings)
+ except BaseException:
+ # Any exit without a saved connection ends the attempt — Ctrl-C
+ # (a notebook's cancel) while waiting on the provider or at a
+ # field prompt included — so its reservation must not outlive it
+ # and block the next sign-in. Releasing an attempt that is no
+ # longer this one's is a no-op.
+ self._release(provider, attempt_id)
+ raise
+ finally:
+ with self._lock:
+ active = self._active.get(provider)
+ if active is not None and active[0] == attempt_id:
+ self._active.pop(provider)
+
+ def _choose_method(self, descriptor: ProviderDescriptor, method: str | LoginMethod | None, ui: AuthUI, *,
+ allow_unverified: bool) -> LoginMethod:
+ if isinstance(method, LoginMethod):
+ method = method.id
+ if method is not None:
+ try:
+ chosen = descriptor.method(method)
+ except KeyError:
+ raise AuthOperationError(
+ f"{descriptor.id}: no login method {method!r}; see Auth.methods({descriptor.id!r})",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=descriptor.id,
+ ) from None
+ if chosen.availability == "unavailable":
+ raise AuthOperationError(
+ f"{descriptor.id}: method {method!r} is unavailable: {chosen.reason}",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=descriptor.id,
+ method_id=method,
+ )
+ if chosen.availability == "unverified" and not allow_unverified:
+ raise AuthOperationError(
+ f"{descriptor.id}: method {method!r} has no live receipt yet ({chosen.reason}); pass "
+ "allow_unverified=True to try it knowing that",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=descriptor.id,
+ method_id=method,
+ )
+ return chosen
+ candidates = [m for m in descriptor.methods if m.availability == "supported"
+ or (allow_unverified and m.availability == "unverified")]
+ if not candidates:
+ raise AuthOperationError(
+ f"{descriptor.id}: no selectable login method here",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=descriptor.id,
+ )
+ if len(candidates) == 1:
+ return candidates[0]
+ options = tuple(SelectOption(m.id, m.label, m.billing_note or m.reason) for m in candidates)
+ try:
+ answer = ui.prompt(SelectPrompt("method", f"How do you want to connect to {descriptor.label}?", options))
+ except (KeyboardInterrupt, EOFError):
+ raise LoginCancelled("login cancelled at the method prompt") from None
+ for candidate in candidates:
+ if candidate.id == answer:
+ return candidate
+ raise AuthOperationError(
+ f"{descriptor.id}: the UI answered {answer!r}, which is not one of the offered method ids",
+ reason="invalid_login_state", stage="interaction", recovery="choose_method", provider=descriptor.id,
+ )
+
+ def _reserve(self, provider: str, attempt_id: str, replace: str | None, lifetime_s: float,
+ *, cancel: threading.Event | None = None) -> int:
+ """Reserve the slot's single active attempt; return the generation
+ the commit must find."""
+ now = self._clock()
+
+ def reserve(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, provider)
+ pending = slot.attempt
+ if pending and pending.get("id") != attempt_id:
+ started = float(pending.get("started_at_s", 0))
+ budget = float(pending.get("lifetime_s", ATTEMPT_LIFETIME_S))
+ if now - started < budget:
+ raise AuthOperationError(
+ f"{provider}: another sign-in is already in progress in this scope; finish it or "
+ "cancel it (Auth.cancel_login)",
+ reason="login_in_progress", stage="reservation", recovery="inspect_attempt",
+ provider=provider, attempt_id=pending.get("id"),
+ )
+ if slot.connection_id and not replace:
+ raise AuthOperationError(
+ f"{provider}: a connection is already saved ({slot.connection_id}); pass replace=that id "
+ "to replace it, or logout first",
+ reason="connection_exists", stage="reservation", recovery="select_connection",
+ provider=provider, connection_id=slot.connection_id,
+ )
+ if replace and slot.connection_id != replace:
+ raise AuthOperationError(
+ f"{provider}: replace={replace!r} does not name the current connection; select again",
+ reason="connection_changed", stage="reservation", recovery="select_connection",
+ provider=provider, connection_id=slot.connection_id,
+ )
+ slot.attempt = {"id": attempt_id, "expected_generation": str(slot.generation),
+ "started_at_s": now, "lifetime_s": float(lifetime_s)}
+ if cancel is not None:
+ with self._lock:
+ if cancel.is_set():
+ raise LoginCancelled("login cancelled before reservation")
+ self._active[provider] = (attempt_id, cancel)
+ return self._put(document, slot, material)
+
+ document = self.store.mutate(reserve)
+ slot, _ = self._view(document, provider)
+ return slot.generation
+
+ def _release(self, provider: str, attempt_id: str) -> None:
+ def release(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, provider)
+ if not slot.attempt or slot.attempt.get("id") != attempt_id:
+ return None
+ slot.attempt = None
+ return self._put(document, slot, material)
+
+ try:
+ self.store.mutate(release)
+ except LM15Error:
+ pass # releasing a reservation must not mask the real failure
+
+ def _commit(self, provider: str, attempt_id: str, expected: int, method: LoginMethod, result: Any,
+ settings: dict[str, str]) -> Connection:
+ created = _now_iso(self._clock)
+ connection_id = f"cn_{secrets.token_urlsafe(12)}"
+ routes = tuple(self.descriptor(provider).routes) or (provider,)
+
+ def commit(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, _material = self._view(document, provider)
+ if not slot.attempt or slot.attempt.get("id") != attempt_id:
+ raise AuthOperationError(
+ f"{provider}: this sign-in was cancelled before it could be saved",
+ reason="invalid_login_state", stage="persistence", commit_state="not_committed",
+ recovery="restart_login", provider=provider, attempt_id=attempt_id,
+ )
+ if slot.generation != expected:
+ raise AuthOperationError(
+ f"{provider}: the saved connection changed while you were signing in; select again",
+ reason="connection_changed", stage="persistence", commit_state="not_committed",
+ recovery="select_connection", provider=provider, attempt_id=attempt_id,
+ )
+ merged = {**slot.settings, **settings, **result.settings} if slot.connection_id else {**settings, **result.settings}
+ previous = slot.previous_ids + ((slot.connection_id,) if slot.connection_id else ())
+ new = _Slot(
+ provider=provider, generation=slot.generation + 1, connection_id=connection_id, revision=1,
+ kind=method.kind, method_id=method.id, label=result.label, account_label=result.account_label,
+ created_at=created, routes=routes, settings=merged, state="ready", renewal=result.renewal,
+ previous_ids=previous,
+ )
+ return self._put(document, new, result.material)
+
+ try:
+ document = self.store.mutate(commit)
+ except AuthOperationError:
+ raise
+ except LM15Error as exc:
+ # A grant may exist at the provider; nothing usable is returned
+ # and nothing else is revoked as compensation (AUTH-19).
+ raise AuthOperationError(
+ f"{provider}: signed in, but the credential could not be saved ({exc.code}); repair the store and "
+ "sign in again",
+ reason="storage_unavailable", stage="persistence", commit_state="not_committed",
+ recovery="repair_storage", provider=provider, attempt_id=attempt_id,
+ ) from exc
+ slot, _ = self._view(document, provider)
+ connection = slot.connection()
+ assert connection is not None
+ return connection
+
+ def cancel_login(self, provider: str) -> str:
+ """Durably cancel the slot's active attempt. Returns ``"cancelled"``,
+ or ``"complete"`` when a commit already won (undo = logout), or
+ ``"none"`` when nothing was pending."""
+ provider = self.descriptor(provider).id
+ outcome = {"result": "none"}
+
+ def cancel(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, provider)
+ if not slot.attempt:
+ outcome["result"] = "complete" if slot.connection_id else "none"
+ return None
+ outcome["attempt_id"] = slot.attempt["id"]
+ slot.attempt = None
+ outcome["result"] = "cancelled"
+ return self._put(document, slot, material)
+
+ self.store.mutate(cancel) # the durable record first (AUTH-19) …
+ with self._lock:
+ active = self._active.get(provider)
+ if active is not None and active[0] == outcome.get("attempt_id"):
+ active[1].set() # … then the running attempt in this process
+ return outcome["result"]
+
+ def _cancel_login_attempt(self, provider: str, event: threading.Event) -> None:
+ """Cancel only this async caller's reservation, ordered against commit."""
+ provider = self.descriptor(provider).id
+
+ def cancel(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, provider)
+ with self._lock:
+ active = self._active.get(provider)
+ if active is None or active[1] is not event or not slot.attempt or slot.attempt.get("id") != active[0]:
+ return None
+ slot.attempt = None
+ return self._put(document, slot, material)
+
+ self.store.mutate(cancel)
+
+ # ─── setup without a provider round-trip (AUTH-17) ─────────────────
+
+ def set_api_key(self, provider: str, key: str, *, replace: str | None = None) -> Connection:
+ """Save a literal key (no interpolation, no verification)."""
+ if not isinstance(key, str) or not key.strip():
+ raise AuthOperationError("set_api_key: the key is empty", reason="interaction_required",
+ stage="interaction", recovery="provide_input", provider=provider)
+ return self.configure(provider, method="api_key", answers={"key": key}, replace=replace)
+
+ def configure(self, provider: str, *, method: str, answers: dict[str, str] | None = None,
+ settings: dict[str, str] | None = None, replace: str | None = None) -> Connection:
+ """Save a recipe connection: ``env`` (use ``$VAR`` at request time),
+ ``external:<source>`` (another tool's login, read in place),
+ ``cloud`` (a named cloud identity), ``local`` (a keyless server),
+ or ``api_key``. No credential is acquired and nothing is verified."""
+ self._check_open()
+ descriptor = self.descriptor(provider)
+ provider = descriptor.id
+ try:
+ chosen = descriptor.method(method)
+ except KeyError:
+ raise AuthOperationError(
+ f"{provider}: no setup method {method!r}; see Auth.methods({provider!r})",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=provider,
+ ) from None
+ if chosen.flow not in ("form", "source_recipe"):
+ raise AuthOperationError(
+ f"{provider}: {method!r} is an interactive login; use Auth.login",
+ reason="method_unavailable", stage="discovery", recovery="choose_method", provider=provider,
+ )
+ answers = dict(answers or {})
+ settings = dict(settings or {})
+ for field_ in chosen.fields:
+ if field_.required and not answers.get(field_.id):
+ raise AuthOperationError(
+ f"{provider}: {method!r} needs {field_.id!r}", reason="interaction_required",
+ stage="interaction", recovery="provide_input", provider=provider,
+ )
+ attempt_id = f"at_{secrets.token_urlsafe(16)}"
+ self.store.reserve()
+ expected = self._reserve(provider, attempt_id, replace, 60.0)
+ ctx = LoginContext(ui=_NoUI(), deadline=self._monotonic() + 60.0, provider=provider,
+ clock=self._monotonic, wall_clock=self._clock, opener=self._opener)
+ try:
+ result = _flow(provider, method).login(ctx, chosen, settings, answers)
+ except LoginDenied as exc:
+ self._release(provider, attempt_id)
+ raise AuthOperationError(f"{provider}: {exc}", reason="login_denied", stage="interaction",
+ recovery="provide_input", provider=provider) from None
+ except LM15Error:
+ self._release(provider, attempt_id)
+ raise
+ return self._commit(provider, attempt_id, expected, chosen, result, settings)
+
+ # ─── logout (AUTH-19) ──────────────────────────────────────────────
+
+ def logout(self, provider_or_connection: str) -> ForgetResult:
+ """Forget the connection locally: material removed, generation
+ bumped, pending attempt cancelled, a suppression marker kept so a
+ restart cannot fall back to an ambient key (R3). Never calls a
+ provider's revoke endpoint; never touches another tool's file."""
+ self._check_open()
+ provider, target_id = self._resolve_target(provider_or_connection)
+ outcome: dict[str, Any] = {}
+
+ def forget(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, provider)
+ if target_id is not None and slot.connection_id != target_id:
+ outcome.update(forgot=False, generation=slot.generation, routes=slot.routes)
+ return None # idempotent: a newer id occupying the slot is untouched
+ if slot.connection_id is None and not slot.attempt:
+ outcome.update(forgot=False, generation=slot.generation, routes=slot.routes)
+ if slot.legacy or slot.generation == 0:
+ return None
+ return None
+ if material is not None and material.get("type") == "external":
+ material_after: Material | None = None # the recipe goes; the tool's file is untouched
+ else:
+ material_after = None
+ new = _Slot(
+ provider=provider, generation=slot.generation + 1, connection_id=None, revision=0,
+ kind=slot.kind, method_id=slot.method_id, routes=slot.routes or (provider,), settings={},
+ state="ready", renewal="none", logged_out=True,
+ previous_ids=slot.previous_ids + ((slot.connection_id,) if slot.connection_id else ()),
+ )
+ outcome.update(forgot=True, generation=new.generation, routes=new.routes)
+ with self._lock:
+ active = self._active.get(provider)
+ if active is not None:
+ active[1].set()
+ return self._put(document, new, material_after)
+
+ self.store.mutate(forget)
+ return ForgetResult(provider=provider, forgot=bool(outcome.get("forgot")),
+ routes=tuple(outcome.get("routes") or (provider,)),
+ identity_generation=str(outcome.get("generation", 0)))
+
+ def _resolve_target(self, provider_or_connection: str) -> tuple[str, str | None]:
+ if provider_or_connection.startswith(("cn_", "legacy-")):
+ for connection in self.connections():
+ if connection.id == provider_or_connection:
+ return connection.provider, connection.id
+ document = self.store.read()
+ for key, record in ((document.get(META_KEY) or {}).get("slots") or {}).items():
+ if provider_or_connection in (record.get("previous_ids") or ()):
+ return key, provider_or_connection # an old id: logout is a no-op, never a newer id's removal
+ raise AuthOperationError(
+ "no saved connection has that id", reason="attempt_unavailable", stage="resolution",
+ recovery="select_connection",
+ )
+ provider = self.descriptor(provider_or_connection).id
+ slot, _ = self._route_view(self.store.read(), provider)
+ return slot.provider, None
+
+ # ─── verification (AUTH-17) ────────────────────────────────────────
+
+ def verify(self, provider: str, *, router_config: Any = None) -> Verification:
+ """An explicit, non-inference check: resolve (renewing if due) and
+ list models on the route. Not universal (some routes have no safe
+ check) and possibly metered by the provider."""
+ self._check_open()
+ provider = self.descriptor(provider).id
+ from ..registry import PROVIDERS
+
+ definition = PROVIDERS.get(provider)
+ if definition is None or not definition.supports.models:
+ return Verification(result="unverified", check="models", detail="this route has no safe non-inference check")
+ from ..router import LMRouter, RouterConfig
+ from .bound import pinned_auth
+ from .types import ModelSelection
+
+ config = router_config or RouterConfig()
+ from dataclasses import replace as _replace
+
+ slot, _ = self._route_view(self.store.read(), provider)
+ connection = slot.connection()
+ managed = self
+ if connection is not None:
+ selection = ModelSelection(provider=provider, model="verify", connection_id=connection.id,
+ identity_generation=connection.identity_generation)
+ managed = pinned_auth(self, selection)
+ # Verify the saved connection, never an explicit router-config key.
+ router = LMRouter(_replace(config, auth=managed, api_keys={}, credentials={}))
+ checked = _now_iso(self._clock)
+ try:
+ lm = router.lm(f"{provider}:verify")
+ lm.list_models()
+ result = Verification(result="valid", checked_at=checked, check="models")
+ except AuthError as exc:
+ result = Verification(result="rejected", checked_at=checked, check="models", detail=exc.code)
+ finally:
+ router.close()
+ if connection is not None:
+ self._record_verification(connection, result)
+ return result
+
+ def _record_verification(self, connection: Connection, result: Verification) -> None:
+ def record(document: dict[str, Any]) -> dict[str, Any] | None:
+ slot, material = self._view(document, connection.provider)
+ if slot.connection_id != connection.id or str(slot.generation) != connection.identity_generation:
+ return None
+ slot.verification = {"result": result.result, "checked_at": result.checked_at, "check": result.check,
+ "detail": result.detail}
+ return self._put(document, slot, material)
+
+ try:
+ self.store.mutate(record)
+ except LM15Error:
+ pass
+
+ # ─── request-time resolution (AUTH-15/20) ──────────────────────────
+
+ def request_auth(self, provider: str, *, pinned: tuple[str, str] | None = None) -> RequestAuth:
+ """What a request on ``provider`` sends now: the saved connection's
+ credential, renewed under the lock if due. ``pinned`` is a bound
+ client's ``(connection_id, generation)``; a mismatch is
+ ``connection_changed``, never a silent rebind (AUTH-20.1)."""
+ provider = self.descriptor(provider).id
+ route = provider
+ document = self.store.read()
+ slot, material = self._route_view(document, provider)
+ provider = slot.provider
+ if slot.renewal_in_flight and slot.state != "indeterminate":
+ # A sibling may be renewing right now (it holds the lock), or may
+ # have died mid-exchange. Only the lock can tell: wait for it,
+ # re-read, and reuse the sibling's result; a marker still there
+ # once we hold the lock is an interrupted renewal (AUTH-20.4).
+ return replace(self._renew(provider, pinned), route=route)
+ self._check_selected(provider, slot, material, pinned)
+ flow = flow_for_material(provider, material) # type: ignore[arg-type]
+ assert material is not None
+ expiry = flow.expiry(material)
+ if expiry in ("never", None):
+ return replace(self._auth_from(provider, flow, material, slot), route=route)
+ now_ms = int(self._clock() * 1000)
+ if now_ms < expiry - self._lead_ms(flow.lifetime_s(material)):
+ return replace(self._auth_from(provider, flow, material, slot), route=route)
+ return replace(self._renew(provider, pinned), route=route)
+
+ def _check_selected(self, provider: str, slot: _Slot, material: Material | None, pinned: tuple[str, str] | None) -> None:
+ if pinned is not None and (slot.connection_id != pinned[0] or str(slot.generation) != pinned[1]):
+ if slot.connection_id is None:
+ raise AuthOperationError(
+ f"{provider}: the connection this client was bound to was signed out; connect again",
+ reason="login_required", stage="resolution", recovery="restart_login", provider=provider,
+ connection_id=pinned[0],
+ )
+ raise AuthOperationError(
+ f"{provider}: the saved connection was replaced after this client was bound; connect again",
+ reason="connection_changed", stage="resolution", recovery="select_connection", provider=provider,
+ connection_id=pinned[0],
+ )
+ if slot.connection_id is None or material is None:
+ if slot.logged_out:
+ message = f"{provider}: signed out; sign in again (Auth.login) or pass a key explicitly (api_keys)"
+ else:
+ message = f"{provider}: no saved connection in this scope; sign in with Auth.login or connect()"
+ raise AuthOperationError(message, reason="login_required", stage="resolution",
+ recovery="restart_login", provider=provider)
+ if slot.state == "needs_login":
+ raise AuthOperationError(
+ f"{provider}: the saved credential was rejected by the provider; sign in again",
+ reason="login_required", stage="resolution", recovery="restart_login", provider=provider,
+ connection_id=slot.connection_id,
+ )
+ if slot.state == "indeterminate" or slot.renewal_in_flight:
+ raise AuthOperationError(
+ f"{provider}: a credential renewal was interrupted and its outcome is unknown; sign in again "
+ "rather than reuse a possibly consumed token",
+ reason="indeterminate", stage="resolution", commit_state="unknown", recovery="restart_login",
+ provider=provider, connection_id=slot.connection_id,
+ )
+
+ def _auth_from(self, provider: str, flow: Any, material: Material, slot: _Slot) -> _RequestSnapshot:
+ try:
+ value = flow.request_auth(material, slot.settings)
+ connection = slot.connection()
+ assert connection is not None
+ return _RequestSnapshot(
+ credential=value.credential, headers=dict(value.headers), base_url=value.base_url,
+ account_id=value.account_id, named=value.named, connection=connection, route=provider,
+ )
+ except LoginDenied as exc:
+ raise AuthOperationError(f"{provider}: {exc}", reason="login_required", stage="resolution",
+ recovery="restart_login", provider=provider,
+ connection_id=slot.connection_id) from None
+
+ def _admit(self, snapshot: _RequestSnapshot) -> None:
+ """Order local dispatch against replacement/logout, without renewing.
+
+ The lock is released before transport I/O. Logout after this admission
+ cannot recall an already admitted request (AUTH-19/20).
+ """
+ connection = snapshot.connection
+ with self.store.transaction() as txn:
+ slot, material = self._route_view(txn.read(), snapshot.route)
+ self._check_selected(snapshot.route, slot, material,
+ (connection.id, connection.identity_generation))
+
+ def _renew(self, provider: str, pinned: tuple[str, str] | None) -> _RequestSnapshot:
+ """AUTH-20.4: lock, re-read, reuse a sibling's fresh result, else
+ mark in-flight, exchange, write — all under the lock."""
+ ctx = LoginContext(ui=_NoUI(), deadline=self._monotonic() + 60.0, provider=provider, clock=self._monotonic,
+ wall_clock=self._clock, opener=self._opener)
+ with self.store.transaction() as txn:
+ document = txn.read()
+ slot, material = self._view(document, provider)
+ self._check_selected(provider, slot, material, pinned)
+ assert material is not None
+ flow = flow_for_material(provider, material)
+ expiry = flow.expiry(material)
+ now_ms = int(self._clock() * 1000)
+ if expiry in ("never", None) or now_ms < expiry - self._lead_ms(flow.lifetime_s(material)):
+ return self._auth_from(provider, flow, material, slot) # a sibling renewed while we waited
+ if not self._renewable(slot, material):
+ self._mark(txn, document, slot, material, state="needs_login", drop_material=True)
+ raise AuthOperationError(
+ f"{provider}: the saved credential expired and cannot be renewed; sign in again",
+ reason="credential_rejected", stage="renewal", commit_state="committed",
+ recovery="restart_login", provider=provider, connection_id=slot.connection_id,
+ )
+ # Durable in-flight marker before the possibly rotating exchange.
+ slot.renewal_in_flight = {"started_at": _now_iso(self._clock), "revision": str(slot.revision)}
+ txn.write(self._put(document, slot, material))
+ try:
+ result = flow.renew(ctx, material, slot.settings)
+ except LoginDenied as exc:
+ self._mark(txn, document, slot, material, state="needs_login", drop_material=True)
+ raise AuthOperationError(
+ f"{provider}: renewal failed ({exc}); sign in again",
+ reason="credential_rejected", stage="renewal", commit_state="committed",
+ recovery="restart_login", provider=provider, connection_id=slot.connection_id,
+ status=exc.status, provider_code=exc.provider_code,
+ ) from None
+ except (RateLimitError, ServerError) as exc:
+ self._mark(txn, document, slot, material, state="ready") # known safe: keep credentials
+ raise exc
+ except TransportError as exc:
+ if getattr(exc, "exchange_uncertain", False):
+ self._mark(txn, document, slot, material, state="indeterminate", keep_marker=True)
+ raise AuthOperationError(
+ f"{provider}: the renewal exchange timed out after it may have reached the provider; a "
+ "rotated token cannot be spent twice, so sign in again",
+ reason="indeterminate", stage="renewal", commit_state="unknown", recovery="restart_login",
+ provider=provider, connection_id=slot.connection_id,
+ ) from exc
+ self._mark(txn, document, slot, material, state="ready")
+ raise
+ except BaseException:
+ self._mark(txn, document, slot, material, state="indeterminate", keep_marker=True)
+ raise
+ previous_account = flow.request_auth(material, slot.settings).account_id
+ renewed_account = flow.request_auth(result.material, slot.settings).account_id
+ if previous_account is not None and renewed_account != previous_account:
+ self._mark(txn, document, slot, material, state="needs_login", drop_material=True)
+ raise AuthOperationError(
+ f"{provider}: renewal changed the selected account; sign in again",
+ reason="connection_changed", stage="renewal", commit_state="committed",
+ recovery="restart_login", provider=provider, connection_id=slot.connection_id,
+ )
+ slot.renewal_in_flight = None
+ slot.revision += 1
+ slot.state = "ready"
+ if result.account_label:
+ slot.account_label = result.account_label
+ txn.write(self._put(document, slot, result.material))
+ return self._auth_from(provider, flow, result.material, slot)
+
+ def _mark(self, txn: Any, document: dict[str, Any], slot: _Slot, material: Material | None, *, state: str,
+ drop_material: bool = False, keep_marker: bool = False) -> None:
+ slot.state = state
+ if not keep_marker:
+ slot.renewal_in_flight = None
+ txn.write(self._put(document, slot, None if drop_material else material))
+
+ def credential_provider(self, provider: str, *, pinned: tuple[str, str] | None = None) -> Callable[[], Any]:
+ """A zero-argument callable the adapters resolve per request
+ (AUTH-2): each call is :meth:`request_auth`."""
+ provider = self.descriptor(provider).id
+
+ def resolve() -> Any:
+ return self.request_auth(provider, pinned=pinned).credential
+
+ resolve.__name__ = f"lm15_managed_{provider}"
+ return resolve
+
+ # ─── housekeeping ─────────────────────────────────────────────────
+
+ def close(self) -> None:
+ """Cancel logins this manager is running; never a logout."""
+ with self._lock:
+ self._closed = True
+ events = list(self._active.values())
+ for _, event in events:
+ event.set()
+
+ def _check_open(self) -> None:
+ if self._closed:
+ raise AuthOperationError("this Auth was closed", reason="storage_unavailable", stage="resolution",
+ recovery="operator_action")
+
+ def __enter__(self) -> "Auth":
+ return self
+
+ def __exit__(self, *_exc: Any) -> None:
+ self.close()
+
+
+class _NoUI:
+ """A UI that cannot answer: any prompt is ``interaction_required``."""
+
+ def prompt(self, prompt: Any) -> str:
+ raise AuthOperationError(
+ "this operation needs a choice or input and no UI was supplied",
+ reason="interaction_required", stage="interaction", recovery="provide_input",
+ )
+
+ def notify(self, notice: Any) -> None:
+ return None
+
+
+class AsyncAuth:
+ """The same manager for ``async`` code (AUTH-22: Python gets a native
+ async entry point). Logins are long, interactive and I/O-bound, so
+ each operation runs the sync manager in a worker thread and awaits it;
+ nothing blocks the event loop and nothing pretends to be non-blocking
+ while doing blocking I/O. ``cancel`` events and the store are shared
+ with the wrapped :class:`Auth`, which ``RouterConfig(auth=...)`` and
+ ``AsyncLMRouter`` take directly (``AsyncAuth.sync``)."""
+
+ def __init__(self, sync: Auth) -> None:
+ self.sync = sync
+
+ @classmethod
+ def local(cls, path: str | os.PathLike[str] | None = None) -> "AsyncAuth":
+ return cls(Auth.local(path))
+
+ @classmethod
+ def memory(cls) -> "AsyncAuth":
+ return cls(Auth.memory())
+
+ def __repr__(self) -> str:
+ return f"AsyncAuth({self.sync.store!r})"
+
+ # definitions only: no thread needed
+ def providers(self):
+ return self.sync.providers()
+
+ def methods(self, provider: str):
+ return self.sync.methods(provider)
+
+ async def _run(self, fn: Callable[..., Any], *args: Any, **kwargs: Any) -> Any:
+ import asyncio
+ import functools
+
+ return await asyncio.to_thread(functools.partial(fn, *args, **kwargs))
+
+ async def connections(self):
+ return await self._run(self.sync.connections)
+
+ async def status(self, provider: str):
+ return await self._run(self.sync.status, provider)
+
+ async def login(self, provider: str, method: Any = None, **kwargs: Any):
+ import asyncio
+ from concurrent.futures import ThreadPoolExecutor
+
+ cancel = kwargs.get("cancel") or threading.Event()
+ kwargs["cancel"] = cancel
+ try:
+ return await self._run(self.sync.login, provider, method, **kwargs)
+ except asyncio.CancelledError:
+ cancel.set()
+ # A blocking login can occupy every default-executor worker.
+ # Durable cancellation must not queue behind those workers.
+ with ThreadPoolExecutor(max_workers=1) as executor:
+ cleanup = asyncio.get_running_loop().run_in_executor(
+ executor, self.sync._cancel_login_attempt, provider, cancel,
+ )
+ # Repeated cancellation must not let the reservation outlive
+ # CancelledError. The provider's worker need not return first.
+ while not cleanup.done():
+ try:
+ await asyncio.shield(cleanup)
+ except asyncio.CancelledError:
+ continue
+ cleanup.result()
+ raise
+
+ async def set_api_key(self, provider: str, key: str, **kwargs: Any):
+ return await self._run(self.sync.set_api_key, provider, key, **kwargs)
+
+ async def configure(self, provider: str, **kwargs: Any):
+ return await self._run(self.sync.configure, provider, **kwargs)
+
+ async def verify(self, provider: str, **kwargs: Any):
+ return await self._run(self.sync.verify, provider, **kwargs)
+
+ async def logout(self, provider_or_connection: str):
+ return await self._run(self.sync.logout, provider_or_connection)
+
+ async def cancel_login(self, provider: str):
+ return await self._run(self.sync.cancel_login, provider)
+
+ async def request_auth(self, provider: str, **kwargs: Any):
+ return await self._run(self.sync.request_auth, provider, **kwargs)
+
+ def close(self) -> None:
+ self.sync.close()
+
+ async def __aenter__(self) -> "AsyncAuth":
+ return self
+
+ async def __aexit__(self, *_exc: Any) -> None:
+ self.close()
diff --git a/dspy/_vendor/lm15/login/store.py b/dspy/_vendor/lm15/login/store.py
new file mode 100644
index 000000000..b1084c059
--- /dev/null
+++ b/dspy/_vendor/lm15/login/store.py
@@ -0,0 +1,275 @@
+"""
+lm15.login.store — the managed credential store (spec/auth.md AUTH-25).
+
+One document per scope. The document is the same JSON object the legacy
+xAI login already writes (``{"xai": {"type": "oauth", ...}}``, Pi's
+``auth.json`` convention) extended with one non-secret metadata block,
+``_lm15``::
+
+ {
+ "xai": {"type": "oauth", "access": "...", "refresh": "...", "expires": 1700000000000},
+ "claude-code": {"type": "oauth", ...},
+ "openrouter": {"type": "api_key", "key": "..."},
+ "_lm15": {
+ "version": 1,
+ "slots": {
+ "xai": {"generation": "3", "connection_id": "cn_...", "revision": "7", ...},
+ "gemini": {"generation": "2", "connection_id": null, "logged_out": true}
+ }
+ }
+ }
+
+Why one file and not a second one (decision stated in the 2026-09-22
+implementation report): the xAI subscription entry must remain the single
+copy the legacy loader, the router's ``oauth-unless-explicit`` chain and the
+managed manager all read and renew. A second file would have needed either
+a token copy (two owners of a rotating refresh token — forbidden by R1) or
+a plain ``LMRouter()`` that cannot see a ``connect()`` login. Provider
+entries keep their provider-specific private shape; ``_lm15`` holds only
+what AUTH-19/20/25 need: identity generations, credential revisions,
+renewal-in-flight markers, logout suppression markers and display metadata.
+
+Two stores implement the same document contract:
+
+- :class:`FileStore` — private (0600), atomic writes, cross-process advisory
+ lock on the canonical path (``lm15._authlock``). Default path is AUTH-8's
+ ``$LM15_CREDENTIALS_PATH`` / ``~/.config/lm15/credentials.json``.
+- :class:`MemoryStore` — process-lifetime, for tests and short-lived tools.
+
+Both expose one compound write path, :meth:`Store.mutate`, a serialized
+read-modify-write of the whole document. Every commit the manager makes
+(login, refresh, logout, replacement) is one ``mutate`` call, so credential
+material and slot metadata change together or not at all.
+
+An unreadable or unrecognised document is a typed
+:class:`~lm15.errors.AuthOperationError` (``storage_unavailable`` /
+``unsupported_store_version``), never an empty store and never overwritten.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import threading
+from pathlib import Path
+from typing import Any, Callable
+
+from .._authlock import hold_file_lock, write_private_json_atomic
+from ..errors import AuthOperationError
+
+__all__ = ["FileStore", "MemoryStore", "Store", "Transaction", "META_KEY", "STORE_VERSION", "default_store_path"]
+
+META_KEY = "_lm15"
+STORE_VERSION = 1
+
+Document = dict[str, Any]
+Mutation = Callable[[Document], "Document | None"]
+
+
+def default_store_path() -> Path:
+ """``$LM15_CREDENTIALS_PATH``, else ``$XDG_CONFIG_HOME/lm15/credentials.json``
+ (spec/auth.md AUTH-8). Read at call time, never at import."""
+ 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"
+
+
+def _storage_error(message: str, *, reason: str = "storage_unavailable", stage: str = "persistence") -> AuthOperationError:
+ return AuthOperationError(
+ message, reason=reason, stage=stage, commit_state="not_committed", recovery="repair_storage",
+ operation="store",
+ )
+
+
+def validate_document(data: Any, *, where: str) -> Document:
+ """Reject anything that is not the document shape above. Raises the
+ typed storage error; never returns a guess."""
+ if not isinstance(data, dict):
+ raise _storage_error(f"Credential store at {where} is not a JSON object; not touching it.")
+ meta = data.get(META_KEY)
+ if meta is not None:
+ if not isinstance(meta, dict):
+ raise _storage_error(f"Credential store at {where} has a malformed {META_KEY!r} block; not touching it.")
+ version = meta.get("version")
+ if version != STORE_VERSION:
+ raise _storage_error(
+ f"Credential store at {where} is managed-store version {version!r}; this lm15 reads version "
+ f"{STORE_VERSION}. Upgrade lm15 or point LM15_CREDENTIALS_PATH at another file.",
+ reason="unsupported_store_version",
+ )
+ slots = meta.get("slots", {})
+ if not isinstance(slots, dict) or any(not isinstance(v, dict) for v in slots.values()):
+ raise _storage_error(f"Credential store at {where} has malformed slot metadata; not touching it.")
+ for key, value in data.items():
+ if key != META_KEY and not isinstance(value, dict):
+ raise _storage_error(f"Credential store at {where}: entry {key!r} is not an object; not touching it.")
+ return data
+
+
+class Transaction:
+ """The store, locked. ``read`` gives a private copy of the document as
+ it is now; ``write`` replaces it atomically. A transaction may write
+ more than once (AUTH-20.4: a renewal marker before the exchange, the
+ result after it) — every write is durable on return."""
+
+ def read(self) -> Document:
+ raise NotImplementedError
+
+ def write(self, document: Document) -> None:
+ raise NotImplementedError
+
+
+class Store:
+ """The document contract both stores implement. Subclass, do not use."""
+
+ description: str = "store"
+
+ def read(self) -> Document:
+ """A private copy of the whole document. No lock; for status and
+ selection. Correctness-critical reads happen inside a transaction."""
+ raise NotImplementedError
+
+ def transaction(self):
+ """``with store.transaction() as txn:`` — exclusive, cross-process
+ where the backend supports it (the file store's canonical-path lock)."""
+ raise NotImplementedError
+
+ def mutate(self, fn: Mutation) -> Document:
+ """Serialized read-modify-write. ``fn`` gets a private copy of the
+ current document and returns the new one, or ``None`` to leave the
+ store untouched. Returns the post-write document (a copy)."""
+ with self.transaction() as txn:
+ current = txn.read()
+ replacement = fn(copy.deepcopy(current))
+ if replacement is None:
+ return current
+ txn.write(replacement)
+ return copy.deepcopy(replacement)
+
+ def reserve(self) -> None:
+ """AUTH-17: prove the store can be written before any external
+ authorization starts. Raises the typed storage error; never
+ substitutes another store."""
+ raise NotImplementedError
+
+ def __repr__(self) -> str: # never contents
+ return f"{type(self).__name__}({self.description})"
+
+
+class MemoryStore(Store):
+ """Process-lifetime document; ``Auth.memory()``."""
+
+ def __init__(self) -> None:
+ self._data: Document = {}
+ self._lock = threading.RLock()
+ self.description = "memory"
+
+ def read(self) -> Document:
+ with self._lock:
+ return copy.deepcopy(self._data)
+
+ def transaction(self):
+ store = self
+
+ class _Txn(Transaction):
+ def __enter__(self):
+ store._lock.acquire()
+ return self
+
+ def __exit__(self, *_exc):
+ store._lock.release()
+
+ def read(self) -> Document:
+ return copy.deepcopy(store._data)
+
+ def write(self, document: Document) -> None:
+ store._data = validate_document(copy.deepcopy(document), where="memory")
+
+ return _Txn()
+
+ def reserve(self) -> None:
+ return None
+
+
+class FileStore(Store):
+ """AUTH-8 private file; AUTH-4 locking and atomic writes."""
+
+ def __init__(self, path: str | os.PathLike[str] | None = None, *, lock_timeout_s: float = 30.0) -> None:
+ # Anchor the absolute path now (AUTH-14): a later chdir must not move
+ # the store. Nothing is read or created here.
+ chosen = Path(path).expanduser() if path is not None else default_store_path()
+ self.path = chosen if chosen.is_absolute() else Path(os.getcwd()) / chosen
+ self.lock_timeout_s = lock_timeout_s
+ self.description = str(self.path)
+
+ def _load(self) -> Document:
+ try:
+ text = self.path.read_text(encoding="utf-8")
+ except FileNotFoundError:
+ return {}
+ except OSError as exc:
+ raise _storage_error(f"Could not read credential store at {self.path}: {exc.strerror or exc}") from exc
+ try:
+ data = json.loads(text, object_pairs_hook=_reject_duplicate_members)
+ except ValueError as exc:
+ raise _storage_error(f"Credential store at {self.path} is not valid JSON; not touching it.") from exc
+ return validate_document(data, where=str(self.path))
+
+ def read(self) -> Document:
+ return self._load()
+
+ def transaction(self):
+ store = self
+
+ class _Txn(Transaction):
+ def __enter__(self):
+ self._guard = hold_file_lock(store.path, timeout_s=store.lock_timeout_s)
+ self._guard.__enter__()
+ return self
+
+ def __exit__(self, *exc):
+ return self._guard.__exit__(*exc)
+
+ def read(self) -> Document:
+ return store._load()
+
+ def write(self, document: Document) -> None:
+ validate_document(document, where=str(store.path))
+ try:
+ write_private_json_atomic(store.path, document)
+ except OSError as exc:
+ raise _storage_error(
+ f"Could not write credential store at {store.path}: {exc.strerror or exc}"
+ ) from exc
+
+ return _Txn()
+
+ def reserve(self) -> None:
+ """Take the lock once and touch nothing: proves the directory and the
+ lock directory are writable before a browser is opened."""
+ try:
+ self.path.parent.mkdir(parents=True, exist_ok=True)
+ except OSError as exc:
+ raise _storage_error(
+ f"Cannot create {self.path.parent} for the credential store: {exc.strerror or exc}",
+ stage="reservation",
+ ) from exc
+ if self.path.exists() and not os.access(self.path, os.W_OK):
+ raise _storage_error(f"Credential store at {self.path} is not writable.", stage="reservation")
+ with hold_file_lock(self.path, timeout_s=self.lock_timeout_s):
+ self._load()
+
+
+def _reject_duplicate_members(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+ """AUTH-25: a duplicate member name is an ambiguity a post-parse schema
+ cannot see; refuse before collapsing into a dict."""
+ result: dict[str, Any] = {}
+ for key, value in pairs:
+ if key in result:
+ raise ValueError(f"duplicate member {key!r}")
+ result[key] = value
+ return result
diff --git a/dspy/_vendor/lm15/login/terminal.py b/dspy/_vendor/lm15/login/terminal.py
new file mode 100644
index 000000000..23f02d6ee
--- /dev/null
+++ b/dspy/_vendor/lm15/login/terminal.py
@@ -0,0 +1,123 @@
+"""
+lm15.login.terminal — the terminal adapter for AUTH-16.
+
+Prints notices to stderr, asks with ``input()``/``getpass``. Opens a
+browser only when the application says so (``open_browser=True``): a URL
+is otherwise printed for the person to open, which is what a machine
+reached over SSH needs. Ctrl-C at a prompt cancels the login
+(``LoginCancelled``); nothing is retried.
+"""
+
+from __future__ import annotations
+
+import getpass
+import sys
+import threading
+from typing import Any, TextIO
+
+from .types import (
+ AuthUrlNotice,
+ DeviceCodeNotice,
+ InfoNotice,
+ ManualCodePrompt,
+ Notice,
+ ProgressNotice,
+ Prompt,
+ SecretPrompt,
+ SelectPrompt,
+ TextPrompt,
+)
+
+__all__ = ["TerminalUI"]
+
+
+class TerminalUI:
+ def __init__(self, *, out: TextIO | None = None, inp: Any = None, open_browser: bool = False) -> None:
+ self._out = out if out is not None else sys.stderr
+ self._input = inp if inp is not None else input
+ self._open_browser = open_browser
+ self._stale: set[int] = set()
+ self._manual_lock = threading.Lock()
+ # Keep the prompt alive so a later prompt cannot reuse its identity.
+ self._manual_reads: dict[int, tuple[Prompt, threading.Event]] = {}
+
+ def _say(self, text: str) -> None:
+ self._out.write(text + "\n")
+ self._out.flush()
+
+ def notify(self, notice: Notice) -> None:
+ if isinstance(notice, AuthUrlNotice):
+ self._say(f"\nOpen this link to sign in:\n {notice.url}\n{notice.instructions}")
+ if self._open_browser:
+ self._open(notice.url)
+ elif isinstance(notice, DeviceCodeNotice):
+ self._say(f"\nOpen {notice.verification_url}\nand enter this code: {notice.user_code}\n"
+ f"(the code is valid for about {int(notice.expires_in_s // 60)} minutes)")
+ if self._open_browser:
+ self._open(notice.verification_url)
+ elif isinstance(notice, ProgressNotice):
+ self._say(f"… {notice.message}")
+ elif isinstance(notice, InfoNotice):
+ links = "".join(f"\n {label}: {url}" for label, url in notice.links)
+ self._say(notice.message + links)
+
+ def _open(self, url: str) -> None:
+ if not url.startswith("https://"):
+ return # AUTH-18: never launch a scheme a provider chose
+ try:
+ import webbrowser
+
+ webbrowser.open(url, new=2)
+ except Exception:
+ pass
+
+ def prompt(self, prompt: Prompt) -> str:
+ if isinstance(prompt, SecretPrompt):
+ return getpass.getpass(f"{prompt.label}: ")
+ if isinstance(prompt, SelectPrompt):
+ self._say(f"\n{prompt.label}")
+ for index, option in enumerate(prompt.options, 1):
+ note = f" — {option.description}" if option.description else ""
+ self._say(f" {index}. {option.label}{note}")
+ while True:
+ raw = self._input("Choose a number: ").strip()
+ if raw.isdigit() and 1 <= int(raw) <= len(prompt.options):
+ return prompt.options[int(raw) - 1].id
+ for option in prompt.options:
+ if raw == option.id:
+ return option.id
+ self._say("Not one of the choices.")
+ if isinstance(prompt, ManualCodePrompt):
+ with self._manual_lock:
+ if id(prompt) in self._stale:
+ return ""
+ done = threading.Event()
+ self._manual_reads[id(prompt)] = (prompt, done)
+ try:
+ return self._input(f"{prompt.label}\n> ")
+ finally:
+ done.set()
+ if isinstance(prompt, TextPrompt):
+ hint = f" [{prompt.placeholder}]" if prompt.placeholder else ""
+ return self._input(f"{prompt.label}{hint}: ")
+ raise TypeError(f"unknown prompt {type(prompt).__name__}")
+
+ def dismiss(self, prompt: Prompt) -> None:
+ if not isinstance(prompt, ManualCodePrompt):
+ return
+ with self._manual_lock:
+ self._stale.add(id(prompt))
+ read = self._manual_reads.get(id(prompt))
+ if read is None:
+ # The callback can win before the manual thread starts.
+ done = threading.Event()
+ done.set()
+ self._manual_reads[id(prompt)] = (prompt, done)
+ return
+ done = read[1]
+ if done.is_set():
+ return
+ self._say("\n(the browser finished — press Enter to continue)")
+ # input() cannot be cancelled portably. Do not let the next prompt
+ # begin until this reader returns (or raises), releasing the terminal.
+ done.wait()
diff --git a/dspy/_vendor/lm15/login/types.py b/dspy/_vendor/lm15/login/types.py
new file mode 100644
index 000000000..4c53f38b7
--- /dev/null
+++ b/dspy/_vendor/lm15/login/types.py
@@ -0,0 +1,303 @@
+"""
+lm15.login.types — the public vocabulary of managed authentication.
+
+spec/auth.md AUTH-12 (vocabulary), AUTH-13 (descriptors), AUTH-16 (the UI
+boundary), AUTH-23 (model choices and selections), AUTH-24 (status). Every
+value here is secret-free by construction: a :class:`Connection` is
+metadata about a saved credential, never the credential. Objects that
+carry secrets live in the flows and the store and never cross this
+boundary.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol, runtime_checkable
+
+__all__ = [
+ "AuthUI",
+ "Availability",
+ "Connection",
+ "ConnectionKind",
+ "ConnectionStatus",
+ "DeviceCodeNotice",
+ "Flow",
+ "InfoNotice",
+ "LoginMethod",
+ "ManualCodePrompt",
+ "MethodField",
+ "ModelChoice",
+ "ModelSelection",
+ "Notice",
+ "ProgressNotice",
+ "Prompt",
+ "ProviderDescriptor",
+ "SecretPrompt",
+ "SelectOption",
+ "SelectPrompt",
+ "TextPrompt",
+ "Usability",
+ "Verification",
+ "AuthUrlNotice",
+]
+
+ConnectionKind = Literal["account", "api_key", "cloud_identity", "local_server"]
+Flow = Literal["authorization_code", "device_code", "form", "source_recipe"]
+Availability = Literal["supported", "unavailable", "unverified"]
+Usability = Literal["ready", "renewal_due", "needs_login", "indeterminate", "unknown"]
+
+
+# ─── Descriptors (AUTH-13) ─────────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class MethodField:
+ """One input a login method needs before it can start."""
+
+ id: str
+ label: str
+ type: Literal["text", "secret", "select"] = "text"
+ required: bool = True
+ options: tuple["SelectOption", ...] = ()
+ help: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class LoginMethod:
+ """A named way to establish a connection for a provider (AUTH-13.3).
+
+ ``availability`` is the SDK's honest statement: ``supported`` means the
+ implementation exists and has a recorded receipt; ``unverified`` means
+ the code exists but no live receipt does (excluded from default pickers;
+ explicit opt-in only); ``unavailable`` means it cannot run here, with
+ ``reason`` saying why. It never means "this account qualifies".
+ """
+
+ id: str
+ label: str
+ kind: ConnectionKind
+ flow: Flow
+ availability: Availability = "supported"
+ reason: str | None = None
+ fields: tuple[MethodField, ...] = ()
+ delivery: tuple[str, ...] = () # loopback | manual | device
+ subscription: bool = False # backed by a provider subscription, per provider docs
+ billing_note: str | None = None # known provider policy; never an entitlement promise
+ guidance: str | None = None
+
+ @property
+ def selectable(self) -> bool:
+ return self.availability != "unavailable"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderDescriptor:
+ """A provider a manager can connect (AUTH-13.1). ``id`` is the LM15
+ route; ``service`` is a presentation group only."""
+
+ id: str
+ label: str
+ service: str
+ routes: tuple[str, ...]
+ methods: tuple[LoginMethod, ...]
+ docs_url: str | None = None
+ console_url: str | None = None
+
+ def method(self, method_id: str) -> LoginMethod:
+ for method in self.methods:
+ if method.id == method_id:
+ return method
+ raise KeyError(method_id)
+
+
+# ─── Connections and status (AUTH-12, AUTH-24) ────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class Connection:
+ """Secret-free metadata for one saved credential in a scope."""
+
+ id: str
+ provider: str
+ instance_id: str
+ kind: ConnectionKind
+ method_id: str
+ routes: tuple[str, ...]
+ label: str
+ created_at: str
+ identity_generation: str
+ credential_revision: str
+ settings: dict[str, str] = field(default_factory=dict)
+ account_label: str | None = None # untrusted display text (AUTH-12)
+
+ def __repr__(self) -> str:
+ return (
+ f"Connection(id={self.id!r}, provider={self.provider!r}, kind={self.kind!r}, "
+ f"method={self.method_id!r}, label={self.label!r})"
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class Verification:
+ result: Literal["valid", "rejected", "unverified"]
+ checked_at: str | None = None
+ check: str | None = None
+ detail: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionStatus:
+ """AUTH-24: presence, usability and last verification are separate."""
+
+ provider: str
+ presence: Literal["saved", "absent"]
+ usability: Usability
+ connection: Connection | None = None
+ expires_at: str | None = None # RFC 3339, "never" or "unknown"
+ logged_out: bool = False
+ verification: Verification | None = None
+ detail: str | None = None
+
+ @property
+ def ready(self) -> bool:
+ return self.usability in ("ready", "renewal_due")
+
+
+# ─── The UI boundary (AUTH-16) ────────────────────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class SelectOption:
+ id: str
+ label: str
+ description: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TextPrompt:
+ field_id: str
+ label: str
+ placeholder: str | None = None
+ type: Literal["text"] = "text"
+
+
+@dataclass(frozen=True, slots=True)
+class SecretPrompt:
+ field_id: str
+ label: str
+ placeholder: str | None = None
+ type: Literal["secret"] = "secret"
+
+
+@dataclass(frozen=True, slots=True)
+class SelectPrompt:
+ field_id: str
+ label: str
+ options: tuple[SelectOption, ...]
+ type: Literal["select"] = "select"
+
+
+@dataclass(frozen=True, slots=True)
+class ManualCodePrompt:
+ """Paste the redirect URL or code when the browser cannot reach the
+ loopback listener. Raced against the listener: the engine cancels
+ whichever loses (AUTH-16)."""
+
+ field_id: str
+ label: str
+ accepted: str = "the full redirect URL, or the code"
+ type: Literal["manual_code"] = "manual_code"
+
+
+Prompt = TextPrompt | SecretPrompt | SelectPrompt | ManualCodePrompt
+
+
+@dataclass(frozen=True, slots=True)
+class AuthUrlNotice:
+ url: str
+ instructions: str
+ type: Literal["auth_url"] = "auth_url"
+
+
+@dataclass(frozen=True, slots=True)
+class DeviceCodeNotice:
+ user_code: str
+ verification_url: str
+ expires_in_s: float
+ interval_s: float
+ type: Literal["device_code"] = "device_code"
+
+
+@dataclass(frozen=True, slots=True)
+class ProgressNotice:
+ stage: str
+ message: str
+ type: Literal["progress"] = "progress"
+
+
+@dataclass(frozen=True, slots=True)
+class InfoNotice:
+ message: str
+ links: tuple[tuple[str, str], ...] = () # (label, url)
+ type: Literal["info"] = "info"
+
+
+Notice = AuthUrlNotice | DeviceCodeNotice | ProgressNotice | InfoNotice
+
+
+@runtime_checkable
+class AuthUI(Protocol):
+ """What an application supplies to let a login talk to a person.
+
+ ``prompt`` returns the answer (a ``SelectPrompt`` answer is the option
+ id); it raises :class:`lm15.login.LoginCancelled` to cancel. ``notify``
+ shows a notice and returns. A UI never opens a browser unless it is the
+ application's explicit choice to do so (``TerminalUI(open_browser=True)``).
+ """
+
+ def prompt(self, prompt: Prompt) -> str: ...
+
+ def notify(self, notice: Notice) -> None: ...
+
+ def dismiss(self, prompt: Prompt) -> None:
+ """Called when a displayed prompt became stale (the loopback callback
+ arrived while a manual prompt was showing). Optional."""
+
+
+# ─── Model choices and selections (AUTH-23) ───────────────────────────
+
+
+@dataclass(frozen=True, slots=True)
+class ModelChoice:
+ provider: str
+ model: str
+ connection_id: str
+ source: Literal["bundled", "cached", "provider", "application", "manual"]
+ label: str | None = None
+ fetched_at: str | None = None
+ capabilities: dict[str, Literal["supported", "unsupported", "unknown"]] = field(default_factory=dict)
+
+ @property
+ def routed(self) -> str:
+ return f"{self.provider}:{self.model}"
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSelection:
+ """An exact route + model bound to one connection id and generation."""
+
+ provider: str
+ model: str
+ connection_id: str
+ identity_generation: str
+ instance_id: str = "public"
+
+ @property
+ def routed(self) -> str:
+ return f"{self.provider}:{self.model}"
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "provider": self.provider, "model_id": self.model, "connection_id": self.connection_id,
+ "identity_generation": self.identity_generation, "instance_id": self.instance_id,
+ }
diff --git a/dspy/_vendor/lm15/models.py b/dspy/_vendor/lm15/models.py
index e8c927529..c84ac55bc 100644
--- a/dspy/_vendor/lm15/models.py
+++ b/dspy/_vendor/lm15/models.py
@@ -12,11 +12,14 @@ inference model. Fine-tune PROVENANCE stays describable through ModelOrigin
from __future__ import annotations
from dataclasses import dataclass, field
-from typing import Iterable
+from typing import TYPE_CHECKING, Any, Iterable
from .compat import CompatProfile
from .types import JsonObject
+if TYPE_CHECKING: # the generated __init__ signatures
+ from collections.abc import Sequence
+
# ─── Validation helpers ──────────────────────────────────────────────
@@ -133,6 +136,21 @@ class InferenceModelInfo:
pricing: InferencePricing | None = None
extensions: JsonObject | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ input_modalities: Sequence[str] = ...,
+ output_modalities: Sequence[str] = ...,
+ context_window: int | None = ...,
+ max_output_tokens: int | None = ...,
+ supports_reasoning: bool = ...,
+ reasoning_efforts: Sequence[str] = ...,
+ pricing: InferencePricing | None = ...,
+ extensions: dict[str, Any] | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
object.__setattr__(self, "input_modalities", tuple(self.input_modalities))
object.__setattr__(self, "output_modalities", tuple(self.output_modalities))
@@ -177,6 +195,21 @@ class ModelInfo:
compat: CompatProfile | None = None
extensions: JsonObject | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ id: str,
+ provider: str,
+ api_family: str,
+ aliases: Sequence[str] = ...,
+ origin: ModelOrigin = ...,
+ inference: InferenceModelInfo | None = ...,
+ compat: CompatProfile | None = ...,
+ extensions: dict[str, Any] | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_check_nonempty_text(self.id, "ModelInfo.id")
_check_nonempty_text(self.provider, "ModelInfo.provider")
diff --git a/dspy/_vendor/lm15/profiles.py b/dspy/_vendor/lm15/profiles.py
index e77422522..e0070a410 100644
--- a/dspy/_vendor/lm15/profiles.py
+++ b/dspy/_vendor/lm15/profiles.py
@@ -24,7 +24,7 @@ from __future__ import annotations
import warnings
from dataclasses import dataclass, field
-from typing import Any
+from typing import TYPE_CHECKING, Any
from .compat import (
CompatProfile,
@@ -43,6 +43,9 @@ from .models import (
)
from .types import JsonObject
+if TYPE_CHECKING: # the generated __init__ signatures
+ from collections.abc import Mapping, Sequence
+
# Re-export commonly used model/compat classes from lm15.profiles for ergonomic
# imports while keeping their implementation in compat.py/models.py.
@@ -121,6 +124,17 @@ class ProviderProfile:
models: tuple[ModelInfo, ...] = ()
extensions: JsonObject | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ provider: str,
+ endpoints: Mapping[str, EndpointProfile] = ...,
+ models: Sequence[ModelInfo] = ...,
+ extensions: JsonObject | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_deprecated("ProviderProfile")
_check_nonempty_text(self.provider, "ProviderProfile.provider")
diff --git a/dspy/_vendor/lm15/providers/_managed.py b/dspy/_vendor/lm15/providers/_managed.py
new file mode 100644
index 000000000..4001556a5
--- /dev/null
+++ b/dspy/_vendor/lm15/providers/_managed.py
@@ -0,0 +1,78 @@
+"""Managed provider operation preparation; execution adapters never share auth state.
+
+Decorated drivers acquire one snapshot before encoding any requests. Nested
+drivers run on the prepared adapter, retaining that snapshot across every wire
+call. Pure mapping, planning, and job-handle constructors are not operations.
+"""
+from __future__ import annotations
+
+import asyncio
+import inspect
+from functools import wraps
+from typing import Any, Callable, TypeVar, cast
+
+from ..errors import AuthOperationError, UnsupportedFeatureError
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def _prepare(lm):
+ prepare = getattr(lm, "_managed_prepare", None)
+ return prepare() if prepare is not None else lm
+
+
+def operation(method: _F) -> _F:
+ if inspect.iscoroutinefunction(method):
+ @wraps(method)
+ async def call(self, *args, **kwargs):
+ lm = await asyncio.to_thread(_prepare, self) if getattr(self, "_managed_prepare", None) else self
+ return await method(lm, *args, **kwargs)
+ elif inspect.isgeneratorfunction(method):
+ @wraps(method)
+ def call(self, *args, **kwargs):
+ yield from method(_prepare(self), *args, **kwargs)
+ else:
+ @wraps(method)
+ def call(self, *args, **kwargs):
+ return method(_prepare(self), *args, **kwargs)
+ return cast(_F, call)
+
+
+def async_stream(method: _F) -> _F:
+ @wraps(method)
+ async def call(self, *args, **kwargs):
+ lm = await asyncio.to_thread(_prepare, self) if getattr(self, "_managed_prepare", None) else self
+ events = method(lm, *args, **kwargs)
+ try:
+ async for event in events:
+ yield event
+ finally:
+ close = getattr(events, "aclose", None)
+ if close is not None:
+ await close()
+ return cast(_F, call)
+
+
+def require_prepared(lm):
+ if getattr(lm, "_managed_prepare", None) is not None:
+ raise AuthOperationError(
+ "managed requests must be built through an operation driver",
+ reason="indeterminate", stage="dispatch", commit_state="not_committed",
+ )
+
+
+def admit(lm, request):
+ require_prepared(lm)
+ expected = getattr(lm, "_managed_admit", None)
+ if expected is not None and request._admit is not expected:
+ raise AuthOperationError(
+ "managed request has no matching authentication snapshot",
+ reason="connection_changed", stage="dispatch", commit_state="not_committed",
+ )
+ if request._admit is not None:
+ request._admit()
+
+
+def require_unmanaged_live(lm):
+ if getattr(lm, "_managed_prepare", None) is not None or getattr(lm, "_managed_admit", None) is not None:
+ raise UnsupportedFeatureError("managed authentication is not supported on websocket transports")
diff --git a/dspy/_vendor/lm15/providers/anthropic.py b/dspy/_vendor/lm15/providers/anthropic.py
index 1e3d6afd9..6035501a1 100644
--- a/dspy/_vendor/lm15/providers/anthropic.py
+++ b/dspy/_vendor/lm15/providers/anthropic.py
@@ -19,6 +19,8 @@ from ..errors import (
TimeoutError,
UnsupportedFeatureError,
UnsupportedModelError,
+ is_pinned_auth_failure,
+ is_pinned_model_not_found,
canonical_error_code,
map_http_error,
)
@@ -72,7 +74,7 @@ from .base import (
batch_entry_request,
default_transport,
)
-from .common import EFFORT_THINKING_BUDGETS, MEDIA_KINDS, anthropic_source, check_tool_result_media, data_part_text, iso_utc, model_infos_from_entries, multipart_form_body, parts_to_text, path_id, unnamed_tool_call_error
+from .common import check_message_media, EFFORT_THINKING_BUDGETS, MEDIA_KINDS, anthropic_source, check_tool_result_media, data_part_text, iso_utc, model_infos_from_entries, multipart_form_body, parts_to_text, path_id, tool_description, unnamed_tool_call_error
# Canonical builtin tool name → Anthropic tool format
_ANTHROPIC_BUILTIN_MAP: dict[str, str] = {
@@ -162,27 +164,37 @@ def _reasoning_thinking_budget(request: Request) -> int | None:
return EFFORT_THINKING_BUDGETS[reasoning.effort]
-# Output ceilings by model class, for the `max_tokens` the Messages API
-# requires and the caller did not set (MAP-13 `defaulted`, decision
-# 2026-09-14 §4.8). Until then the default was 1024, which cut ordinary
-# answers off with nothing said. The 3.x classes have documented lower
-# ceilings and a value above them is a 400; everything else (4.x and later,
-# and any name this table does not know) gets 16384 — loud and actionable
-# if a model's ceiling is lower ("max_tokens: 16384 > N"), never a silent
-# truncation. A table that rots; `Config.max_tokens` overrides.
-_DEFAULT_MAX_TOKENS_BY_CLASS: tuple[tuple[str, int], ...] = (
+# The `max_tokens` the Messages API requires and the caller did not set
+# (MAP-13 `defaulted`; MAP-7 rule 6, amended 2026-09-30): the model's own
+# output ceiling, the value OpenAI and Gemini apply when their field is
+# omitted. From Anthropic's Models API (`max_tokens`, receipts 2026-09-01
+# and 2026-09-30) and its models overview: 128000 for the 4.6 generation and
+# every later Claude (5.x, Fable, Mythos, and any Claude name this table has
+# not met — a newer model is loud, "max_tokens: 128000 > N", never a silent
+# truncation); 64000 for the 4.5 generation; the retired 3.x values stay.
+# Before 2026-09-30 every 4.x and later model got 16384, which a reply with
+# reasoning on routinely exhausted. A model name that is not Claude's (a
+# DeepSeek, Kimi or Muse model on an Anthropic-dialect server) keeps 16384:
+# those servers publish their own, lower ceilings. On the adaptive class
+# this is the ceiling for thinking and answer together; the note records it.
+# There is no rate-limit cost: Anthropic counts output tokens as produced,
+# not max_tokens (scrapes/anthropic/pages/rate-limits.md).
+_CLAUDE_OUTPUT_CEILINGS: tuple[tuple[str, int], ...] = (
("claude-3-haiku", 4096), ("claude-3-opus", 4096), ("claude-3-sonnet", 4096),
("claude-3-5-", 8192), ("claude-3.5-", 8192),
+ ("claude-haiku-4-5", 64000), ("claude-sonnet-4-5", 64000), ("claude-opus-4-5", 64000),
+ ("claude", 128000),
)
_DEFAULT_MAX_TOKENS = 16384
-def _default_max_tokens(model: str) -> int:
+def _claude_output_ceiling(model: str) -> int | None:
+ """The output ceiling of a Claude model, by name; None for any other."""
lowered = model.lower()
- for marker, ceiling in _DEFAULT_MAX_TOKENS_BY_CLASS:
+ for marker, ceiling in _CLAUDE_OUTPUT_CEILINGS:
if marker in lowered:
return ceiling
- return _DEFAULT_MAX_TOKENS
+ return None
def _max_tokens_for_anthropic(request: Request, thinking_budget: int | None, *, provider: str = "anthropic") -> int:
@@ -190,12 +202,26 @@ def _max_tokens_for_anthropic(request: Request, thinking_budget: int | None, *,
budget plus the visible cap. Adaptive class (thinking_budget None):
Config.max_tokens is the total ceiling — provider semantics, stated in
spec/types.md. The Messages API requires the field: when the caller
- set none, the class default is used and recorded (MAP-13)."""
+ set none, a Claude model gets its output ceiling as the WIRE value (on
+ the manual class the visible part is what the budget leaves), any other
+ model 16384 visible; the default is recorded (MAP-13)."""
visible = request.config.max_tokens
if visible is None:
- visible = _default_max_tokens(request.model)
+ ceiling = _claude_output_ceiling(request.model)
+ if ceiling is None:
+ visible = _DEFAULT_MAX_TOKENS
+ elif thinking_budget is None:
+ visible = ceiling
+ elif thinking_budget < ceiling:
+ visible = ceiling - thinking_budget
+ else:
+ # The caller's budget alone reaches the ceiling: the server's
+ # 400 names the limit (never a silent shrink of their budget).
+ visible = _DEFAULT_MAX_TOKENS
adapt("config.max_tokens", "defaulted",
- "the Messages API requires max_tokens and none was set; the class default was used",
+ "the Messages API requires max_tokens and none was set; the model's output ceiling was used"
+ if ceiling is not None else
+ "the Messages API requires max_tokens and none was set; 16384 was used (this server's ceiling is its own)",
applied=visible, provider=provider)
if thinking_budget is None:
return visible
@@ -359,7 +385,9 @@ class AnthropicLM(BaseProviderLM):
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):
+ elif (provider_code == "not_found_error" and self._is_model_error(message)) or is_pinned_model_not_found(
+ provider_code, message
+ ): # MAP-15
cls = UnsupportedModelError
return ErrorDetail(
code=canonical_error_code(cls),
@@ -378,7 +406,15 @@ class AnthropicLM(BaseProviderLM):
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.access is not None and self.access.backend == "claude-code":
+ from ..access import claude_code_version_guidance
+ msg = claude_code_version_guidance(msg)
+
+ if is_pinned_auth_failure(err_type, msg): # MAP-18
+ return self._provider_error(
+ AuthError, msg, status=status, provider_code=err_type, request_id=request_id or None
+ )
if self._is_context_length_message(msg):
return self._provider_error(
ContextLengthError,
@@ -392,7 +428,7 @@ class AnthropicLM(BaseProviderLM):
# 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)
- ):
+ ) or is_pinned_model_not_found(err_type, msg): # MAP-15
return self._provider_error(
UnsupportedModelError,
msg,
@@ -565,6 +601,7 @@ class AnthropicLM(BaseProviderLM):
return payload
def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ check_message_media(request, dialect="anthropic", provider=self.provider)
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
@@ -591,13 +628,26 @@ class AnthropicLM(BaseProviderLM):
# 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 cache_cfg is not None and cache_cfg.key is not None:
+ # MAP-13: a best-effort routing hint by definition; no home on
+ # this wire, whether or not the server takes marks.
+ adapt("config.cache.key", "dropped",
+ "the Messages API has no cache affinity key (OpenAI's prompt_cache_key); "
+ "marks on blocks are its mechanism",
+ asked=cache_cfg.key, provider=self.provider)
+ if cache_cfg is not None and cache_cfg.retention == "long" and compat.cache_control != "anthropic":
+ # MAP-13: the TTL rides a cache mark, and this server takes none.
+ adapt("config.cache.retention", "dropped",
+ "this server caches implicitly and has no cache-control TTL",
+ asked="long", provider=self.provider)
+ if not use_cache and cache_cfg is not None and cache_cfg.resource is not None:
+ # MAP-6 rule 7 on a server without marks (e.g. meta-anthropic): the
+ # same refusal; dropping it would lose the prefix it holds.
+ raise UnsupportedFeatureError(
+ f"{self.provider}: cache.resource is not supported — this server has no stored-cache tier and no cache marks; sending without it would drop the prompt prefix the resource holds",
+ provider=self.provider, feature="config.cache.resource",
+ )
if use_cache and cache_cfg is not None:
- if cache_cfg.key is not None:
- # MAP-13: a best-effort routing hint by definition; no home here.
- adapt("config.cache.key", "dropped",
- "the Messages API has no cache affinity key (OpenAI's prompt_cache_key); "
- "marks on blocks are its mechanism and were placed",
- asked=cache_cfg.key, provider=self.provider)
if cache_cfg.resource is not None:
# MAP-13 rule 4(b): the program references a stored object
# that does not exist on this provider.
@@ -662,7 +712,9 @@ class AnthropicLM(BaseProviderLM):
"(protocols--messages.md)"
if always_adaptive else
f"{request.model} takes thinking.type 'adaptive' with output_config.effort; "
- "budget_tokens is rejected by the API (live 2026-09-02)"),
+ "budget_tokens is rejected by the API (live 2026-09-02). Thinking is bounded only "
+ "by max_tokens, which covers thinking and answer together: lower the effort or "
+ "raise max_tokens"),
asked=reasoning.thinking_budget, provider=self.provider)
reasoning = replace(reasoning, thinking_budget=None)
# MAP-7: the word goes verbatim on the always-adaptive server;
@@ -731,7 +783,7 @@ class AnthropicLM(BaseProviderLM):
if allowed_subset is not None and tool.name not in allowed_subset:
continue
if isinstance(tool, FunctionTool):
- tools_wire.append({"name": tool.name, "description": tool.description, "input_schema": tool.parameters})
+ tools_wire.append({"name": tool.name, **tool_description(tool.description), "input_schema": tool.parameters})
elif isinstance(tool, BuiltinTool):
tools_wire.append(_builtin_to_anthropic(tool))
if allowed_subset is not None:
diff --git a/dspy/_vendor/lm15/providers/async_base.py b/dspy/_vendor/lm15/providers/async_base.py
index 05441387b..5105675ef 100644
--- a/dspy/_vendor/lm15/providers/async_base.py
+++ b/dspy/_vendor/lm15/providers/async_base.py
@@ -29,6 +29,7 @@ from ..errors import (
UnsupportedFeatureError,
)
from ..features import EndpointSupport, ProviderManifest
+from ._managed import admit, async_stream, operation, require_unmanaged_live
from ..sse import aparse_sse
from ..transports import (
AsyncTransportResponse,
@@ -52,13 +53,12 @@ from .base import (
BaseProviderLM, Credential, HttpResponse, _attach_error_metadata, _client_side_stop,
_parse_reply, _reply_error_metadata, _reply_object, _stream_error_metadata,
)
-from .claude_code import DEFAULT_CLAUDE_CODE_VERSION, ClaudeCodeLM
+from .claude_code import 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,
)
@@ -158,6 +158,7 @@ class AsyncBaseProviderLM:
"""What a call WOULD adapt (MAP-13), no network, no credential; pure, so sync."""
return self._inner.plan(request, policy=self.adaptations)
+ @operation
async def complete(self, request: Request) -> Response:
req, adaptations = await self._build(self._inner._build, request, stream=False, policy=self.adaptations)
if _client_side_stop(adaptations):
@@ -175,6 +176,7 @@ class AsyncBaseProviderLM:
_attach_error_metadata(error, resp.headers)
raise
+ @async_stream
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
@@ -198,6 +200,10 @@ class AsyncBaseProviderLM:
async def _stream_raw(self, request: Request, req: "TransportRequest | None" = None) -> AsyncIterator[StreamEvent]:
if req is None:
req = await self._build(self._inner.build_request, request, stream=True)
+ if getattr(self, "_managed_admit", None) is not None:
+ await asyncio.to_thread(admit, self, req)
+ else:
+ admit(self, req)
try:
async with self.transport.stream(req) as resp:
if resp.status >= 400:
@@ -219,6 +225,10 @@ class AsyncBaseProviderLM:
raise LM15TransportError(str(exc)) from exc
async def _send(self, request: TransportRequest) -> HttpResponse:
+ if getattr(self, "_managed_admit", None) is not None:
+ await asyncio.to_thread(admit, self, request)
+ else:
+ admit(self, request)
try:
async with self.transport.stream(request) as resp:
body = await resp.read()
@@ -236,6 +246,7 @@ class AsyncBaseProviderLM:
def normalize_error(self, status: int, body: str) -> ProviderError:
return self._inner.normalize_error(status, body)
+ @operation
async def list_models(self):
"""Async mirror of BaseProviderLM.list_models (canonical ModelInfo)."""
resp = await self._send(await self._build(self._inner._models_request))
@@ -245,6 +256,7 @@ class AsyncBaseProviderLM:
# ── Batch: async drivers over the sync adapter's pure hooks ──────
+ @operation
async def batch_submit(self, request: "BatchRequest"):
self._inner._batch_preflight(request)
upload_body = None
@@ -265,12 +277,14 @@ class AsyncBaseProviderLM:
raise self._inner._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._batch_job_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._batch_job_from_body(reply.text()))
+ @operation
async def batch_results(self, batch_id: str):
from ..types import BATCH_TERMINAL_STATUSES
@@ -297,12 +311,14 @@ class AsyncBaseProviderLM:
texts.append(self._inner._batch_reply_text(status_body, fetched))
return _parse_reply(resp, lambda reply: self._inner._batch_entries(status_body, tuple(texts)), json_body=False)
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._batch_job_from_body(reply.text()))
+ @operation
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:
@@ -332,6 +348,7 @@ class AsyncBaseProviderLM:
# ── Cache resources: async drivers over the sync adapter's pure hooks ──
+ @operation
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))
@@ -339,23 +356,27 @@ class AsyncBaseProviderLM:
raise self._inner._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._cache_info_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._cache_info_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._cache_page_from_list_body(reply.text()))
+ @operation
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._http_error(resp)
+ @operation
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")
@@ -376,35 +397,41 @@ class AsyncBaseProviderLM:
# ── Files: async drivers over the sync adapter's pure hooks ──────
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._file_info_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._file_info_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._file_page_from_list_body(reply.text()))
+ @operation
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._http_error(resp)
+ @operation
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._http_error(resp)
return resp.body
+ @operation
async def file_wait_ready(self, file_id: str, poll_every: float = 2.0, timeout: float | None = None):
import asyncio
import time as _time
@@ -443,18 +470,21 @@ class AsyncBaseProviderLM:
# ── Video generation: async drivers over the sync adapter's pure hooks ──
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._video_job_from_body(reply.text()))
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._video_job_from_body(reply.text(), video_id))
+ @operation
async def video_result(self, video_id: str):
from ..types import VIDEO_TERMINAL_STATUSES
@@ -480,6 +510,7 @@ class AsyncBaseProviderLM:
raise self._inner._http_error(fetched)
return _parse_reply(fetched or resp, lambda reply: self._inner._video_part(status_body, fetched), json_body=False)
+ @operation
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:
@@ -503,12 +534,14 @@ class AsyncBaseProviderLM:
# ── Media generation: async drivers over the sync adapter's pure hooks ──
+ @operation
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._http_error(resp)
return _parse_reply(resp, lambda reply: self._inner._image_generation_from_response(request, reply))
+ @operation
async def speech_generate(self, request: SpeechGenerationRequest):
resp = await self._send(await self._build(self._inner._speech_generate_request, request))
if resp.status >= 400:
@@ -522,19 +555,10 @@ async def _aiter_lines(resp: AsyncTransportResponse) -> AsyncIterator[bytes]:
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)
+ from ..transports._types import LineSplitter
+
+ async for line in LineSplitter.aiterate(resp):
+ yield line
# ─── Mirror classes ──────────────────────────────────────────────────
@@ -556,6 +580,7 @@ class AsyncOpenAILM(AsyncBaseProviderLM):
adaptations: AdaptationPolicy = field(default="note", kw_only=True)
async def live(self, config: LiveConfig):
+ require_unmanaged_live(self)
self._inner._require("live")
# Native async websocket (websockets.asyncio) — not a thread
# wrapper: a blocked sync recv in a worker thread cannot be
@@ -676,6 +701,7 @@ class AsyncGeminiLM(AsyncBaseProviderLM):
self._mirror_binding()
async def live(self, config: LiveConfig):
+ require_unmanaged_live(self)
self._inner._require("live")
# Native async twin of GeminiLM.live: same pure setup frame,
# encoder, and setup-status classifier; only the socket awaits.
@@ -742,6 +768,7 @@ class AsyncOpenAIChatLM(AsyncBaseProviderLM):
"""Pure; the sync sibling's reader under this adapter's provider name."""
return self._inner.response_from_openai_chat(body, model=model, choice=choice)
+ @operation
async def complete(self, request: Request) -> Response:
"""Mirror of OpenAIChatLM.complete: the judgment trie driver (MAP-14
§4) over the inner adapter's pure hooks, else the ordinary path."""
@@ -853,7 +880,8 @@ class AsyncClaudeCodeLM(AsyncBaseProviderLM):
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
+ claude_code_version: str | None = None
+ settings: "Mapping[str, str] | None" = None
adaptations: AdaptationPolicy = field(default="note", kw_only=True)
# Not constructor params on the sync sibling either (it is not a dataclass).
@@ -871,7 +899,9 @@ class AsyncClaudeCodeLM(AsyncBaseProviderLM):
base_url=self.base_url,
api_version=self.api_version,
claude_code_version=self.claude_code_version,
+ settings=self.settings,
)
+ self.claude_code_version = self._inner.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
@@ -920,7 +950,8 @@ class AsyncOpenAICodexLM(AsyncBaseProviderLM):
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
+ client_version: str | None = None
+ settings: "Mapping[str, str] | None" = None
adaptations: AdaptationPolicy = field(default="note", kw_only=True)
# Not constructor params on the sync sibling either (it is not a dataclass).
@@ -939,10 +970,13 @@ class AsyncOpenAICodexLM(AsyncBaseProviderLM):
base_url=self.base_url,
originator=self.originator,
client_version=self.client_version,
+ settings=self.settings,
)
+ self.client_version = self._inner.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
+ @operation
async def complete(self, request: Request) -> Response:
# Mirror of OpenAICodexLM.complete: the Codex subscription backend is
# streaming-first; materialize the (coalesced) stream.
diff --git a/dspy/_vendor/lm15/providers/base.py b/dspy/_vendor/lm15/providers/base.py
index 9f599e4bd..0a3626006 100644
--- a/dspy/_vendor/lm15/providers/base.py
+++ b/dspy/_vendor/lm15/providers/base.py
@@ -23,6 +23,7 @@ from ..errors import (
from ..adaptation import Adaptation, AdaptationPolicy, check_policy, collecting, is_planning
from ..credentials import AwsCredentials, CredentialLike, CredentialValue, coerce_credential
from ..features import EndpointSupport, ProviderManifest
+from ._managed import admit, operation, require_prepared
from ..models import ModelInfo
from ..protocols import LiveSession
from ..sse import SSEEvent, parse_sse
@@ -408,6 +409,15 @@ class BaseProviderLM:
return has_stored_credential(cls.manifest)
+ @classmethod
+ def stored_credential_state(cls) -> str:
+ """Offline: ``usable`` (fresh, or renewable), ``unusable`` (expired
+ with no way to renew), ``logged_out`` (signed out under a managed
+ Auth: a suppression marker blocks ambient keys, R3), or ``absent``."""
+ from ..access import stored_credential_state
+
+ return stored_credential_state(cls.manifest)
+
def _bind_access(
self,
access: ProviderManifest | None,
@@ -436,21 +446,29 @@ class BaseProviderLM:
chain. It cannot be combined with ``api_key``: two answers to "who
am I" is a configuration error, not a precedence question.
"""
- from ..access import load_credential
+ from ..access import load_credential, resolve_backend_settings, with_backend_settings
from ..cloud.hosts import render_base_url, resolve_settings
policy = access if access is not None else type(self).manifest
+ if policy.host is None:
+ # A door without a host: ``settings`` are its backend settings
+ # (AUTH-10, amended 2026-09-30), explicit values and the table's
+ # defaults only — the router fills env fallbacks. A name the
+ # door does not declare raises instead of being dropped.
+ policy = with_backend_settings(policy, resolve_backend_settings(policy, settings))
+ settings = None
self.access = policy
self.provider = policy.provider
endpoint = self.base_url if (policy.host is not None and default_base_url is not None
and self.base_url != default_base_url) else None
if credential is not None:
- if not policy.cloud_chain:
- raise NotConfiguredError(
- f"{policy.provider}: credential={credential!r} names a cloud identity, and this door is not a "
- "cloud door; pass api_key= instead",
- provider=policy.provider,
- )
+ from ..errors import named_credential_refusal
+ from ..features import NAMED_CREDENTIALS
+
+ if not policy.cloud_chain or credential not in NAMED_CREDENTIALS:
+ # AUTH-1 (amended 2026-10-10): never repeat a value that is not
+ # one of the names — it is usually a key in the wrong argument.
+ raise named_credential_refusal(policy.provider, credential, cloud_door=policy.cloud_chain)
if self.api_key is not None and self.api_key != "":
raise NotConfiguredError(
f"{policy.provider}: both api_key= and credential={credential!r} were given; a door has one "
@@ -549,6 +567,8 @@ class BaseProviderLM:
# plan() builds and discards: no credential provider is invoked, no
# header is signed — the record of adaptations does not depend on it.
planning = is_planning()
+ if not planning:
+ require_prepared(self)
credential = resolve_credential_value(self.api_key) if self.api_key is not None and not planning else None
hdrs = dict(headers.items()) if isinstance(headers, dict) else dict(headers or [])
if credential is not None and not isinstance(credential, AwsCredentials):
@@ -590,6 +610,7 @@ class BaseProviderLM:
credential=credential,
now=self._now(),
)
+ req._admit = getattr(self, "_managed_admit", None) if not planning else None
return req
def _require(self, surface: str) -> None:
@@ -645,6 +666,7 @@ class BaseProviderLM:
response = replace(response, adaptations=visible)
return response
+ @operation
def complete(self, request: Request) -> Response:
req, adaptations = self._build(request, stream=False)
if _client_side_stop(adaptations):
@@ -668,6 +690,7 @@ class BaseProviderLM:
_attach_error_metadata(error, resp.headers)
raise
+ @operation
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
@@ -684,6 +707,7 @@ class BaseProviderLM:
if req is None:
req = self.build_request(request, stream=True)
self._ensure_transport_open()
+ admit(self, req)
try:
with self.transport.stream(req) as resp:
if resp.status >= 400:
@@ -707,6 +731,7 @@ class BaseProviderLM:
def _send(self, request: TransportRequest) -> HttpResponse:
self._ensure_transport_open()
+ admit(self, request)
try:
with self.transport.stream(request) as resp:
body = resp.read()
@@ -771,6 +796,14 @@ class BaseProviderLM:
hint = self.access.login_hint
if hint and (self.access.credential_policy == "oauth" or self._credential_source == "stored"):
error = with_credential_hint(error, hint)
+ elif isinstance(error, AuthError) and self.access.cloud_chain:
+ # A cloud door refusing an identity is an IAM or token question,
+ # not a mistyped key: say which role, or which kind of credential.
+ from ..cloud.chains import wire_auth_hint
+
+ wire_hint = wire_auth_hint(self.access, error.status, self._sent_credential_kind())
+ if wire_hint:
+ error = with_credential_hint(error, wire_hint)
if isinstance(error, AuthError):
from ..errors import with_credential_origin
@@ -782,6 +815,24 @@ class BaseProviderLM:
error = with_credential_origin(error, origin)
return error
+ def _sent_credential_kind(self) -> str | None:
+ """"key", "token", or None when a callable decides per request."""
+ from ..access import looks_like_access_token
+ from ..credentials import ApiKey, BearerToken
+
+ cred = self.api_key
+ if hasattr(cred, "source") and hasattr(cred, "named"): # a cloud chain provider: tokens
+ return "token"
+ if cred is None or callable(cred):
+ return None
+ try:
+ value = coerce_credential(cred)
+ except Exception: # noqa: BLE001 - guidance must never mask the real error
+ return None
+ if isinstance(value, BearerToken) or (isinstance(value, ApiKey) and looks_like_access_token(value.value)):
+ return "token"
+ return "key" if isinstance(value, ApiKey) else None
+
def close(self) -> None:
close = getattr(self.transport, "close", None)
if callable(close):
@@ -833,6 +884,7 @@ class BaseProviderLM:
def _speech_generation_from_response(self, request: SpeechGenerationRequest, resp: HttpResponse) -> SpeechGenerationResponse:
raise self._generation_unsupported("speech")
+ @operation
def image_generate(self, request: ImageGenerationRequest) -> ImageGenerationResponse:
"""Generate (or, with ``request.images``, edit) images.
@@ -847,6 +899,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._image_generation_from_response(request, reply))
+ @operation
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 —
@@ -892,6 +945,7 @@ class BaseProviderLM:
def _video_jobs_from_list_body(self, body: str) -> "tuple[VideoJobInfo, ...]":
raise self._video_unsupported()
+ @operation
def video_submit(self, request: VideoGenerationRequest) -> VideoJobInfo:
"""Submit a video job; returns the ticket snapshot."""
self._require("video")
@@ -900,6 +954,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._video_job_from_body(reply.text()))
+ @operation
def video_status(self, video_id: str) -> VideoJobInfo:
self._require("video")
resp = self._send(self._video_status_request(video_id))
@@ -907,6 +962,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._video_job_from_body(reply.text(), video_id))
+ @operation
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
@@ -935,6 +991,7 @@ class BaseProviderLM:
raise self._http_error(fetched)
return _parse_reply(fetched or resp, lambda reply: self._video_part(status_body, fetched), json_body=False)
+ @operation
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
@@ -983,6 +1040,7 @@ class BaseProviderLM:
def _models_from_body(self, body: str) -> "tuple[ModelInfo, ...]":
raise UnsupportedFeatureError(f"{self.provider}: model listing not supported", provider=self.provider)
+ @operation
def list_models(self) -> "tuple[ModelInfo, ...]":
"""Fetch the models this credential can use, as canonical ModelInfo."""
self._require("models")
@@ -1045,6 +1103,7 @@ class BaseProviderLM:
def _batch_jobs_from_list_body(self, body: str) -> "tuple[BatchJobInfo, ...]":
raise self._batch_unsupported()
+ @operation
def batch_submit(self, request: BatchRequest) -> BatchJobInfo:
"""Submit to the provider's batch queue; returns the ticket snapshot."""
self._require("batches")
@@ -1072,6 +1131,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._batch_job_from_body(reply.text()))
+ @operation
def batch_status(self, batch_id: str) -> BatchJobInfo:
self._require("batches")
resp = self._send(self._batch_status_request(batch_id))
@@ -1079,6 +1139,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._batch_job_from_body(reply.text()))
+ @operation
def batch_results(self, batch_id: str) -> "tuple[BatchEntry, ...]":
"""Entries in submission order; raises ValueError while the job runs."""
self._require("batches")
@@ -1123,6 +1184,7 @@ class BaseProviderLM:
raise
return text
+ @operation
def batch_cancel(self, batch_id: str) -> BatchJobInfo:
"""Request cancellation — a request, not a guarantee."""
self._require("batches")
@@ -1131,6 +1193,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._batch_job_from_body(reply.text()))
+ @operation
def batch_list(self, limit: int = 20) -> "tuple[BatchJobInfo, ...]":
"""Enumerate this credential's batch jobs, newest first.
@@ -1206,6 +1269,7 @@ class BaseProviderLM:
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")
+ @operation
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")
@@ -1215,6 +1279,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._cache_info_from_body(reply.text()))
+ @operation
def cache_get(self, cache_id: str) -> CacheInfo:
self._require("caches")
resp = self._send(self._cache_get_request(cache_id))
@@ -1222,6 +1287,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._cache_info_from_body(reply.text()))
+ @operation
def cache_list(self, limit: int = 20, cursor: str | None = None) -> CachePage:
self._require("caches")
resp = self._send(self._cache_list_request(limit, cursor))
@@ -1229,6 +1295,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._cache_page_from_list_body(reply.text()))
+ @operation
def cache_delete(self, cache_id: str) -> None:
"""Returning without an exception IS the confirmation (the files precedent)."""
self._require("caches")
@@ -1236,6 +1303,7 @@ class BaseProviderLM:
if resp.status >= 400:
raise self._http_error(resp)
+ @operation
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:
@@ -1293,6 +1361,7 @@ class BaseProviderLM:
def _file_download_request(self, file_id: str) -> TransportRequest:
raise self._files_unsupported()
+ @operation
def file_upload(self, request: FileUploadRequest) -> FileInfo:
"""Store a file with the provider; returns its canonical snapshot.
@@ -1306,6 +1375,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._file_info_from_body(reply.text()))
+ @operation
def file_get(self, file_id: str) -> FileInfo:
self._require("files")
resp = self._send(self._file_get_request(file_id))
@@ -1313,6 +1383,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._file_info_from_body(reply.text()))
+ @operation
def file_list(self, limit: int = 20, cursor: str | None = None) -> FilePage:
"""One page of this credential's stored files.
@@ -1326,6 +1397,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return _parse_reply(resp, lambda reply: self._file_page_from_list_body(reply.text()))
+ @operation
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
@@ -1335,6 +1407,7 @@ class BaseProviderLM:
if resp.status >= 400:
raise self._http_error(resp)
+ @operation
def file_download(self, file_id: str) -> bytes:
"""Download a file's content, when THIS file supports download.
@@ -1348,6 +1421,7 @@ class BaseProviderLM:
raise self._http_error(resp)
return resp.body
+ @operation
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
@@ -1423,19 +1497,8 @@ class UnsupportedLiveSession:
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)
+ """Split arbitrary byte chunks into newline-terminated lines for SSE
+ (linear in the bytes, however long a line is: INV-056)."""
+ from ..transports._types import LineSplitter
+
+ return LineSplitter.iterate(chunks)
diff --git a/dspy/_vendor/lm15/providers/claude_code.py b/dspy/_vendor/lm15/providers/claude_code.py
index 23b55b3cf..b0d2e09ac 100644
--- a/dspy/_vendor/lm15/providers/claude_code.py
+++ b/dspy/_vendor/lm15/providers/claude_code.py
@@ -13,7 +13,7 @@ not this class.
from __future__ import annotations
import os
-from typing import ClassVar
+from typing import ClassVar, Mapping
from ..access import CLAUDE_CODE, DEFAULT_CLAUDE_CODE_SYSTEM_PROMPT, DEFAULT_CLAUDE_CODE_VERSION # noqa: F401
from ..features import ProviderManifest
@@ -23,7 +23,14 @@ from .base import Credential, SyncTransport, default_transport
class ClaudeCodeLM(AnthropicLM):
- """Anthropic Messages adapter authenticated with local Claude Code OAuth."""
+ """Anthropic Messages adapter authenticated with local Claude Code OAuth.
+
+ ``settings={"client_version": "2.1.290"}`` (or ``claude_code_version=``,
+ the same setting under its older name) changes the Claude Code release
+ the door claims; see ``lm15.access.DEFAULT_CLAUDE_CODE_VERSION``. A
+ router also reads ``LM15_CLAUDE_CODE_VERSION``; an adapter built by hand
+ reads no environment.
+ """
manifest: ClassVar[ProviderManifest] = CLAUDE_CODE
@@ -35,22 +42,22 @@ class ClaudeCodeLM(AnthropicLM):
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,
+ claude_code_version: str | None = None,
+ settings: "Mapping[str, str] | None" = None,
adaptations: "AdaptationPolicy" = "note",
) -> 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}"})
+ settings = merge_client_version(settings, claude_code_version, "claude_code_version")
super().__init__(
api_key=api_key,
transport=transport or default_transport(),
base_url=base_url,
api_version=api_version,
- access=policy,
+ access=CLAUDE_CODE,
credentials_path=credentials_path,
+ settings=settings,
adaptations=adaptations,
)
+ self.claude_code_version = (self.access or CLAUDE_CODE).backend_options["client_version"]
@classmethod
def from_claude_code(
@@ -59,7 +66,7 @@ class ClaudeCodeLM(AnthropicLM):
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,
+ claude_code_version: str | None = None,
) -> "ClaudeCodeLM":
return cls(
credentials_path=credentials_path,
@@ -67,3 +74,15 @@ class ClaudeCodeLM(AnthropicLM):
base_url=base_url,
claude_code_version=claude_code_version,
)
+
+
+def merge_client_version(settings: "Mapping[str, str] | None", version: str | None, keyword: str) -> "dict[str, str] | None":
+ """``settings`` with the ``client_version`` a named keyword gave; two
+ different answers are a configuration error, not a precedence question."""
+ if version is None:
+ return None if settings is None else dict(settings)
+ merged = dict(settings or {})
+ if merged.get("client_version", version) != version:
+ raise ValueError(f"{keyword}={version!r} and settings client_version={merged['client_version']!r} disagree; pass one")
+ merged["client_version"] = version
+ return merged
diff --git a/dspy/_vendor/lm15/providers/common.py b/dspy/_vendor/lm15/providers/common.py
index a0285ada1..887682761 100644
--- a/dspy/_vendor/lm15/providers/common.py
+++ b/dspy/_vendor/lm15/providers/common.py
@@ -3,10 +3,13 @@ from __future__ import annotations
import base64
import json
import urllib.parse
-from typing import Any
+from typing import TYPE_CHECKING, Any, Callable
from ..models import ModelInfo, ModelOrigin
from ..transports import TransportRequest
+
+if TYPE_CHECKING:
+ from ..errors import ProviderError
from ..types import (
AudioPart,
BinaryPart,
@@ -23,11 +26,28 @@ from ..types import (
ToolResultPart,
TopLogprob,
VideoPart,
+ Request,
)
JsonPayload = dict[str, Any] | list[Any]
+def tool_description(description: str | None) -> dict[str, str]:
+ """MAP-17: a function tool's description field for any wire.
+
+ ``{"description": text}`` when the tool has one, ``{}`` when it does not.
+ An absent description is left off the wire, never sent as ``null``:
+ every tool wire documents the field as an optional *string*, and
+ Anthropic and Groq refuse ``null`` (400, receipts
+ lm15-contract/receipts/2026-10-02-tool-description/). ``""`` is the
+ same value as ``None`` in canonical JSON (omit-empty, spec/types.md), so
+ it is left off too: two requests that serialize identically must build
+ the same wire. Splat it between the name and the schema to keep the
+ documented key order: ``{"name": ..., **tool_description(d), ...}``.
+ """
+ return {"description": description} if description else {}
+
+
# 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
@@ -154,6 +174,38 @@ def check_tool_result_media(provider: str, part: ToolResultPart, policy: str, *,
)
+# MAP-10 for message parts, the cells where a dialect has no slot at all.
+# Found 2026-09-24 (lm15-contract changes/2026-09-24-message-media.md): the
+# builders below turned such a part into an empty text block or dropped it,
+# silently. lm15-rs refused; this is the same preflight, before any wire.
+_NO_MESSAGE_SLOT = {
+ # The Messages API has image and document blocks only, in either role.
+ "anthropic": lambda role, kind: kind in ("audio", "video", "binary"),
+ # Assistant content is output text (and refusals) on both OpenAI wires.
+ "openai": lambda role, kind: role == "assistant",
+ "openai_chat": lambda role, kind: role == "assistant",
+}
+
+
+def check_message_media(request: Request, *, dialect: str, provider: str) -> None:
+ """Raise before any wire when a message holds a media part this dialect
+ has no content slot for in that role (MAP-10: natively or raises).
+ ``feature`` is the part's path, as MAP-13.4b addresses refusals."""
+ from ..errors import UnsupportedFeatureError
+
+ gap = _NO_MESSAGE_SLOT.get(dialect)
+ if gap is None:
+ return
+ for i, message in enumerate(request.messages):
+ for j, part in enumerate(message.parts):
+ if part.type in MEDIA_KINDS and gap(message.role, part.type):
+ raise UnsupportedFeatureError(
+ f"{provider}: messages[{i}].parts[{j}]: the program depends on this "
+ f"{message.role} {part.type} part; no native {dialect} content slot carries it (MAP-10)",
+ provider=provider, feature=f"messages[{i}].parts[{j}]",
+ )
+
+
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
@@ -246,7 +298,7 @@ def model_infos_from_entries(
*,
provider: str,
api_family: str,
- id_of: "callable",
+ id_of: Callable[[dict[str, Any]], object],
) -> tuple[ModelInfo, ...]:
"""Map a provider's list-models entries to canonical ModelInfo.
@@ -527,11 +579,4 @@ def multipart_related_body(
# 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,
-}
+from ..types import EFFORT_THINKING_BUDGETS as EFFORT_THINKING_BUDGETS # noqa: E402 (one table, in types)
diff --git a/dspy/_vendor/lm15/providers/gemini.py b/dspy/_vendor/lm15/providers/gemini.py
index f15e9a6f8..066dad729 100644
--- a/dspy/_vendor/lm15/providers/gemini.py
+++ b/dspy/_vendor/lm15/providers/gemini.py
@@ -23,11 +23,14 @@ from ..errors import (
UnsupportedFeatureError,
UnsupportedModelError,
canonical_error_code,
+ google_error_reasons,
+ is_pinned_auth_failure,
map_http_error,
)
from ..access import GEMINI_API
from ..features import ProviderManifest
from ..judgments import gemini_schema, note_unmeasurable_probabilities, replace_text_with_data, request_judgments
+from ._managed import operation, require_unmanaged_live
from ..live import WebSocketLiveSession, require_websocket_sync_connect
from ..sse import SSEEvent
from ..transports import TransportRequest
@@ -107,7 +110,7 @@ from .base import (
default_transport,
resolve_credential,
)
-from .common import EFFORT_THINKING_BUDGETS, MEDIA_KINDS, build_url, data_part_text, iso_utc, media_base64, model_infos_from_entries, multipart_related_body, parts_to_text, path_id, unnamed_tool_call_error
+from .common import EFFORT_THINKING_BUDGETS, MEDIA_KINDS, build_url, data_part_text, iso_utc, media_base64, model_infos_from_entries, multipart_related_body, parts_to_text, path_id, tool_description, unnamed_tool_call_error
# Canonical builtin tool name → Gemini tool key
_GEMINI_BUILTIN_MAP: dict[str, str] = {
@@ -190,22 +193,62 @@ def _gemini_token_logprobs(logprobs_result: Any) -> tuple[TokenLogprob, ...]:
return tuple(out)
-def _gemini_schema_field(schema: dict[str, Any]) -> str:
- """Pick Gemini's schema field for an lm15 JSON schema.
+# Gemini's Schema object (generate-content#v1beta.Schema): the keys its
+# OpenAPI fields (``responseSchema``, ``parameters``) parse.
+_GEMINI_SCHEMA_FIELDS = frozenset({
+ "type", "format", "title", "description", "nullable", "enum", "maxItems", "minItems",
+ "properties", "required", "minProperties", "maxProperties", "minLength", "maxLength",
+ "pattern", "example", "anyOf", "propertyOrdering", "default", "items", "minimum", "maximum",
+})
- ``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 gemini_openapi_schema(schema: Any) -> bool:
+ """MAP-16: can Gemini's OpenAPI field carry ``schema``?
-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
+ No, when a schema node — the root, a value of ``properties``, ``items``,
+ an element of ``anyOf`` (or ``anyOf`` itself when it is one object) —
+ is a boolean, has a key that is not a Schema field, has a list
+ ``type``, or has an ``enum`` list with an element that is not a string:
+ the OpenAPI field answers 400 there and the JSON Schema field accepts
+ it (live 2026-09-26). Anything else stays on the OpenAPI field, where
+ lm15 has always sent it; ``example`` and ``default`` are values, never
+ walked.
+ """
+ stack = [schema]
+ while stack:
+ node = stack.pop()
+ if isinstance(node, bool):
+ return False
+ if not isinstance(node, dict):
+ continue
+ for key, value in node.items():
+ if key not in _GEMINI_SCHEMA_FIELDS:
+ return False
+ if key == "type" and isinstance(value, list):
+ return False
+ if key == "enum" and isinstance(value, list) and any(not isinstance(v, str) for v in value):
+ return False
+ if key == "properties" and isinstance(value, dict):
+ stack.extend(value.values())
+ elif key == "items":
+ stack.append(value)
+ elif key == "anyOf":
+ stack.extend(value if isinstance(value, list) else [value])
+ return True
+
+
+def _gemini_schema_field(schema: Any) -> str:
+ """MAP-16: ``responseSchema`` when the schema fits Gemini's OpenAPI
+ Schema object, else ``responseJsonSchema`` (full JSON Schema)."""
+ return "responseSchema" if gemini_openapi_schema(schema) else "responseJsonSchema"
+
+
+def _gemini_function_declaration(tool: FunctionTool) -> dict[str, Any]:
+ """MAP-16: ``parameters`` when the tool's schema fits Gemini's OpenAPI
+ Schema object, else ``parametersJsonSchema``. The schema is verbatim
+ either way (INV-002); only the field that carries it changes."""
+ field = "parameters" if gemini_openapi_schema(tool.parameters) else "parametersJsonSchema"
+ return {"name": tool.name, **tool_description(tool.description), field: tool.parameters}
def _gemini_number(value: float) -> float | int:
@@ -225,10 +268,10 @@ def _gemini_number(value: float) -> float | int:
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);
+ `responseJsonSchema` accepts JSON Schema; `responseSchema` is Gemini's
+ OpenAPI Schema object — `_gemini_schema_field` picks by MAP-16 (pinned
+ by gemini.response_schema, gemini.response_json_schema and the
+ 2026-09-26 receipts). `strict` is satisfied (always constrained);
`name` is a label with no slot.
"""
if format_config["type"] == "json_object":
@@ -521,6 +564,8 @@ class GeminiLM(BaseProviderLM):
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 is_pinned_auth_failure(err_status, msg, google_error_reasons(err)): # MAP-18
+ return self._provider_error(AuthError, msg, status=status, provider_code=err_status)
if self._is_context_length_message(msg):
return self._provider_error(
ContextLengthError,
@@ -813,7 +858,7 @@ class GeminiLM(BaseProviderLM):
if request.tools and resource is None:
function_declarations = [
- {"name": t.name, "description": t.description, "parameters": t.parameters}
+ _gemini_function_declaration(t)
for t in request.tools
if isinstance(t, FunctionTool)
]
@@ -1088,6 +1133,7 @@ class GeminiLM(BaseProviderLM):
# ─── Streaming via Gemini Live for live models ──────────────────
+ @operation
def stream(self, request: Request) -> Iterator[StreamEvent]:
wire = self._wire_request(request)
if self._should_use_live_completion(wire):
@@ -1123,6 +1169,7 @@ class GeminiLM(BaseProviderLM):
return data, 16000
def _stream_via_live_completion(self, request: Request) -> Iterator[StreamEvent]:
+ require_unmanaged_live(self)
ws = self._live_connect(self._live_url())
saw_tool_call = False
audio_native = self._is_audio_native_live_model(request.model)
@@ -1275,6 +1322,7 @@ class GeminiLM(BaseProviderLM):
# ─── Live sessions ──────────────────────────────────────────────
def live(self, config: LiveConfig):
+ require_unmanaged_live(self)
self._require("live")
ws = self._live_connect(self._live_url())
for frame in self._live_setup_frames(config):
@@ -1347,7 +1395,7 @@ class GeminiLM(BaseProviderLM):
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}
+ _gemini_function_declaration(t)
for t in config.tools
if isinstance(t, FunctionTool)
]
@@ -1619,7 +1667,7 @@ class GeminiLM(BaseProviderLM):
body["systemInstruction"] = {"parts": [{"text": text}]}
if prefix.tools:
declarations = [
- {"name": t.name, "description": t.description, "parameters": t.parameters}
+ _gemini_function_declaration(t)
for t in prefix.tools if isinstance(t, FunctionTool)
]
tools_wire: list[dict[str, Any]] = []
diff --git a/dspy/_vendor/lm15/providers/openai.py b/dspy/_vendor/lm15/providers/openai.py
index 4674c5f48..0865d5f3f 100644
--- a/dspy/_vendor/lm15/providers/openai.py
+++ b/dspy/_vendor/lm15/providers/openai.py
@@ -23,6 +23,8 @@ from ..errors import (
TimeoutError,
UnsupportedFeatureError,
UnsupportedModelError,
+ is_pinned_auth_failure,
+ is_pinned_model_not_found,
canonical_error_code,
map_http_error,
)
@@ -31,12 +33,14 @@ from ..auth import extract_chatgpt_account_id
from ..compat import OPENAI_RESPONSES_PRESET_BASE_URLS, OpenAIResponsesCompat, preset_base_url
from ..features import ProviderManifest
from ..judgments import note_unmeasurable_probabilities, replace_text_with_data, request_judgments
+from ._managed import operation, require_unmanaged_live
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 (
+ JsonObject,
continuation_data,
VideoGenerationRequest,
VideoJobInfo,
@@ -109,6 +113,7 @@ from .base import (
resolve_credential_value,
)
from .common import (
+ check_message_media,
tool_result_error_text,
tool_result_output_openai,
iso_utc,
@@ -119,6 +124,7 @@ from .common import (
parse_json_object,
part_to_openai_input,
path_id,
+ tool_description,
unnamed_tool_call_error,
parts_to_text,
)
@@ -255,7 +261,30 @@ def _cache_common_payload(request: Request, payload: dict, cache_control: str, p
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"):
+ if cache_cfg is None:
+ return
+ if cache_control not in ("openai", "openai_implicit"):
+ # MAP-6 rule 7: a stored-cache resource on a provider without that
+ # tier RAISES. Dropping it would silently send the request without
+ # the prompt prefix the resource holds (MAP-13: refuse when a guess
+ # could hurt). Found 2026-09-24 by lm15-rs, which already refused.
+ if cache_cfg.resource is not None:
+ raise UnsupportedFeatureError(
+ f"{provider}: cache.resource is not supported — this provider has no stored-cache "
+ "tier; sending without it would drop the prompt prefix the resource holds",
+ provider=provider, feature="config.cache.resource",
+ )
+ # MAP-13: the key and the lifetime have no home on a server without
+ # OpenAI's cache fields; dropped and recorded (implicit caching, where
+ # the server has it, still applies).
+ if cache_cfg.key is not None:
+ adapt("config.cache.key", "dropped",
+ "this server has no cache affinity field; implicit caching still applies",
+ asked=cache_cfg.key, provider=provider)
+ if cache_cfg.retention == "long":
+ adapt("config.cache.retention", "dropped",
+ "this server has no in-request cache lifetime knob; implicit caching still applies",
+ asked="long", provider=provider)
return
if cache_control == "openai_implicit":
if cache_cfg.mode != "off":
@@ -630,6 +659,8 @@ class OpenAILM(BaseProviderLM):
def _error_detail(self, provider_code: str, message: str) -> ErrorDetail:
cls = self._stream_error_code_map.get(provider_code, ProviderError)
+ if is_pinned_model_not_found(provider_code, message): # MAP-15
+ cls = UnsupportedModelError
return ErrorDetail(
code=canonical_error_code(cls),
message=message or provider_code or "provider error",
@@ -655,6 +686,8 @@ class OpenAILM(BaseProviderLM):
provider_code = code or err_type or None
+ if is_pinned_auth_failure(provider_code, msg): # MAP-18
+ return self._provider_error(AuthError, msg, status=status, provider_code=provider_code)
if code == "context_length_exceeded":
return self._provider_error(
ContextLengthError,
@@ -664,7 +697,7 @@ class OpenAILM(BaseProviderLM):
)
if code in self._model_error_codes or (
status == 404 and self._is_model_error(msg, code, err_type)
- ):
+ ) or is_pinned_model_not_found(provider_code, msg): # MAP-15
return self._provider_error(
UnsupportedModelError,
msg,
@@ -868,6 +901,7 @@ class OpenAILM(BaseProviderLM):
return "auto"
def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ check_message_media(request, dialect="openai", provider=self.provider)
compat = self._compat(request)
breakpoint_index = _cache_breakpoint_index(request, compat.cache_control) # once: it may record
payload: dict[str, Any] = {
@@ -929,10 +963,10 @@ class OpenAILM(BaseProviderLM):
tools_wire: list[dict[str, Any]] = []
for tool in request.tools:
if isinstance(tool, FunctionTool):
- tool_payload = {
+ tool_payload: dict[str, Any] = {
"type": "function",
"name": tool.name,
- "description": tool.description,
+ **tool_description(tool.description),
"parameters": tool.parameters,
}
if compat.strict_tools == "include":
@@ -1044,7 +1078,21 @@ class OpenAILM(BaseProviderLM):
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.
+ # and expects instructions to be present. An explicit cap or
+ # store=True is refused, never stripped: dropping a cap means
+ # unbounded spend (MAP-13 rule 4; Rust and R refuse the same).
+ if request.config.max_tokens is not None:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.max_tokens: this backend has no output cap; "
+ "dropping it risks unbounded paid generation",
+ provider=self.provider, feature="config.max_tokens",
+ )
+ if request.config.store is True:
+ raise UnsupportedFeatureError(
+ f"{self.provider}: config.store: this backend cannot store a retrievable "
+ "response; the program may depend on retrieval",
+ provider=self.provider, feature="config.store",
+ )
if self.access.system_prefix:
payload.setdefault("instructions", self.access.system_prefix)
payload["store"] = False
@@ -1333,6 +1381,7 @@ class OpenAILM(BaseProviderLM):
# ─── Streaming over OpenAI Realtime for live models ──────────────
+ @operation
def complete(self, request: Request) -> Response:
if self._codex:
# Streaming-first backend: materialize the stream so callers get
@@ -1340,6 +1389,7 @@ class OpenAILM(BaseProviderLM):
return materialize_response(self.stream(request), request)
return BaseProviderLM.complete(self, request)
+ @operation
def stream(self, request: Request) -> Iterator[StreamEvent]:
wire = self._wire_request(request)
if not self._codex and self._should_use_live_completion(wire):
@@ -1359,6 +1409,7 @@ class OpenAILM(BaseProviderLM):
return "realtime" in model_name or "-live" in model_name
def _stream_via_live_completion(self, request: Request) -> Iterator[StreamEvent]:
+ require_unmanaged_live(self)
ws = self._live_connect(self._live_url(request.model), self._live_headers())
saw_tool_call = False
usage = Usage()
@@ -1489,6 +1540,7 @@ class OpenAILM(BaseProviderLM):
# ─── Live sessions ──────────────────────────────────────────────
def live(self, config: LiveConfig):
+ require_unmanaged_live(self)
self._require("live")
ws = self._live_connect(self._live_url(config.model), self._live_headers())
for frame in self._live_setup_frames(config):
@@ -1570,7 +1622,7 @@ class OpenAILM(BaseProviderLM):
session["audio"] = audio
if config.tools:
session["tools"] = [
- {"type": "function", "name": t.name, "description": t.description, "parameters": t.parameters}
+ {"type": "function", "name": t.name, **tool_description(t.description), "parameters": t.parameters}
for t in config.tools
if isinstance(t, FunctionTool)
]
diff --git a/dspy/_vendor/lm15/providers/openai_chat.py b/dspy/_vendor/lm15/providers/openai_chat.py
index f5a6eab2d..4c8227a1a 100644
--- a/dspy/_vendor/lm15/providers/openai_chat.py
+++ b/dspy/_vendor/lm15/providers/openai_chat.py
@@ -17,7 +17,7 @@ import math
import mimetypes
import os
from dataclasses import dataclass, field, replace
-from typing import Any, Callable, ClassVar, Iterator, Mapping
+from typing import Any, Callable, ClassVar, Iterator, Mapping, cast
from ..compat import (
OPENAI_CHAT_PRESET_BASE_URLS,
@@ -30,10 +30,12 @@ from ..adaptation import Adaptation, AdaptationPolicy, adapt, check_policy, coll
from ..errors import ProviderError, ServerError, UnsupportedFeatureError
from ..access import OPENAI_CHAT_API
from ..features import ProviderManifest
+from ._managed import operation
from ..judgments import Judgment, judgments_in_schema, non_judgment_properties, normalize_logprobs, note_unmeasurable_probabilities, replace_text_with_data, request_judgments
from ..sse import SSEEvent
from ..transports import TransportRequest
from ..types import (
+ ReasoningEffort,
DataPart,
BuiltinTool,
CacheConfig,
@@ -66,6 +68,7 @@ from ..types import (
)
from .base import BaseProviderLM, Credential, HttpResponse, SyncTransport, default_transport, _attach_error_metadata
from .common import (
+ check_message_media,
MEDIA_KINDS,
check_tool_result_media,
media_data_uri,
@@ -73,6 +76,7 @@ from .common import (
model_infos_from_entries,
openai_token_logprobs,
parse_json_object,
+ tool_description,
unnamed_tool_call_error,
parts_to_text,
data_part_text,
@@ -246,7 +250,13 @@ _INGEST_CONFIG_KEYS: frozenset[str] = frozenset({
_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"}
+# MAP-12 rule 4: OpenAI's server takes wav and mp3, Gemini's any audio type,
+# and DSPy writes the MIME subtype (mpeg for .mp3). Each format reads as its
+# true media type; a builder with no audio slot raises at send (MAP-10).
+_INGEST_AUDIO_MEDIA_TYPES: dict[str, str] = {
+ "wav": "audio/wav", "mp3": "audio/mpeg", "mpeg": "audio/mpeg", "ogg": "audio/ogg", "opus": "audio/opus",
+ "flac": "audio/flac", "aac": "audio/aac", "aiff": "audio/aiff", "webm": "audio/webm",
+}
def _ingest_unsupported(provider: str, what: str, why: str) -> UnsupportedFeatureError:
@@ -1091,7 +1101,14 @@ def _usage_from_chat(usage_data: dict[str, Any]) -> Usage:
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"),
+ # Nested (OpenAI) first; some servers report the count flat on usage
+ # instead (Together's non-reasoning models: `usage.cached_tokens`,
+ # openai-compatibility.md, live 2026-09-26). Reading one place only
+ # turns a reported 0 into "not reported".
+ cache_read_tokens=(
+ prompt_details["cached_tokens"] if prompt_details.get("cached_tokens") is not None
+ else usage_data.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"),
@@ -1176,8 +1193,18 @@ class OpenAIChatLM(BaseProviderLM):
)
def _models_from_body(self, body: str):
+ # Two catalog shapes are in the wild: OpenAI's envelope
+ # {"object": "list", "data": [...]} and a bare JSON array (Together,
+ # api.together.ai/v1/models, live 2026-09-26: 272 entries, no
+ # envelope). Anything else is a malformed reply, never an empty
+ # catalog: reading it as zero models would lose every entry silently.
data = json.loads(body)
- entries = data.get("data") if isinstance(data, dict) else None
+ if isinstance(data, list):
+ entries = data
+ elif isinstance(data, dict) and isinstance(data.get("data"), list):
+ entries = data["data"]
+ else:
+ raise ValueError("a model catalog is {\"data\": [...]} or a JSON array of entries")
return model_infos_from_entries(
entries,
provider=self.provider,
@@ -1343,6 +1370,7 @@ class OpenAIChatLM(BaseProviderLM):
return resolve_openai_chat_compat(partial.for_model(model))
def _payload(self, request: Request, stream: bool) -> dict[str, Any]:
+ check_message_media(request, dialect="openai_chat", provider=self.provider)
compat = self._compat_for(request.model)
# Streaming uses generated JSON, never the non-streamable trie driver.
# Check before building messages or invoking credentials, including on
@@ -1391,7 +1419,7 @@ class OpenAIChatLM(BaseProviderLM):
if isinstance(tool, FunctionTool):
function_payload: dict[str, Any] = {
"name": tool.name,
- "description": tool.description,
+ **tool_description(tool.description),
"parameters": tool.parameters,
}
if compat.strict_tools == "include":
@@ -1463,6 +1491,16 @@ class OpenAIChatLM(BaseProviderLM):
"the model reasons at its own default; pass the server's own knob through extensions",
asked={"effort": reasoning.effort}, provider=self.provider)
reasoning = None
+ if reasoning is not None and reasoning.is_off and compat.reasoning_off == "lowest":
+ # The model cannot stop reasoning and this server accepts the
+ # off word and reasons anyway (compat reasoning_off): send the
+ # lowest level and say so (MAP-13 §4.2, xAI's rule).
+ lowest = cast(ReasoningEffort, compat.reasoning_efforts[0] if compat.reasoning_efforts else "low")
+ adapt("config.reasoning.effort", "substituted",
+ "this model cannot stop reasoning and the server accepts 'none' and reasons anyway "
+ "(a paid no-op); the lowest level was sent",
+ asked="off", applied=lowest, provider=self.provider)
+ reasoning = replace(reasoning, effort=lowest)
if reasoning is not None and not reasoning.is_off:
# MAP-7: verbatim effort; no budget on this wire; summary
# levels are Responses-only; "auto" maps to the dialect's
@@ -1885,6 +1923,7 @@ class OpenAIChatLM(BaseProviderLM):
return self._judgment_adaptations(wire_request, policy=policy)
return BaseProviderLM.plan(self, request, policy=policy)
+ @operation
def complete(self, request: Request) -> Response:
wire_request = self._wire_request(request)
if not self._judgments_via_token_scoring(wire_request):
diff --git a/dspy/_vendor/lm15/providers/openai_codex.py b/dspy/_vendor/lm15/providers/openai_codex.py
index eac387222..9e179cdcf 100644
--- a/dspy/_vendor/lm15/providers/openai_codex.py
+++ b/dspy/_vendor/lm15/providers/openai_codex.py
@@ -14,7 +14,7 @@ needs the policy table and the dialect, not this class.
from __future__ import annotations
import os
-from typing import ClassVar
+from typing import ClassVar, Mapping
from ..access import ( # noqa: F401
DEFAULT_CODEX_BASE_URL,
@@ -43,18 +43,17 @@ class OpenAICodexLM(OpenAILM):
transport: SyncTransport | None = None,
base_url: str = DEFAULT_CODEX_BASE_URL,
originator: str = DEFAULT_CODEX_ORIGINATOR,
- client_version: str = DEFAULT_CODEX_CLIENT_VERSION,
+ client_version: str | None = None,
+ settings: "Mapping[str, str] | None" = None,
adaptations: "AdaptationPolicy" = "note",
) -> None:
+ from .claude_code import merge_client_version
+
self.originator = originator
- self.client_version = client_version
+ settings = merge_client_version(settings, 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(),
@@ -63,8 +62,10 @@ class OpenAICodexLM(OpenAILM):
access=policy,
credentials_path=auth_path,
account_id=account_id,
+ settings=settings,
adaptations=adaptations,
)
+ self.client_version = (self.access or OPENAI_CODEX).backend_options["client_version"]
@classmethod
def from_codex_cli(
diff --git a/dspy/_vendor/lm15/providers/typesafe.py b/dspy/_vendor/lm15/providers/typesafe.py
index 0206501c9..785cb6e1d 100644
--- a/dspy/_vendor/lm15/providers/typesafe.py
+++ b/dspy/_vendor/lm15/providers/typesafe.py
@@ -5,8 +5,12 @@ the messages become Jev's ``state`` (D6), the judgment properties of the
``json_schema`` become its ``questions`` (MAP-14 §2), and the answers come
back as one ``DataPart`` with the distribution per judgment and
``method="provider_classification"`` (§3). Jev generates no text: a
-request without judgments, with tools, or with media is refused before
-the wire (D8). Wire facts: receipts/2026-09-17-judgments/ (jev-*.json).
+request without judgments or with tools is refused before the wire (D8).
+Images reach Jev as top-level ``assets`` named by a reference string
+written where the image belongs in the state
+(changes/2026-10-14-jev-images.md); audio, video and documents are
+refused (MAP-10). Wire facts: receipts/2026-09-17-judgments/,
+receipts/2026-10-14-typesafe/.
"""
from __future__ import annotations
@@ -32,9 +36,9 @@ from ..errors import (
from ..features import ProviderManifest
from ..judgments import MAX_CHOICE_KEYS, MAX_ORDERED_LEVELS, Judgment, non_judgment_properties, request_judgments
from ..transports import TransportRequest
-from ..types import DataPart, Message, Request, Response, StreamEvent, TextPart, Usage
+from ..types import DataPart, ImagePart, Message, Part, Request, Response, StreamEvent, TextPart, Usage
from .base import BaseProviderLM, Credential, HttpResponse, SyncTransport, default_transport, _attach_error_metadata
-from .common import model_infos_from_entries
+from .common import media_base64, model_infos_from_entries
from ..sse import SSEEvent
_DEFAULT_BASE_URL = "https://api.typesafe.ai"
@@ -45,6 +49,21 @@ _DROPPED_KNOBS: tuple[str, ...] = (
"presence_penalty", "reasoning", "logprobs", "store", "user_id", "service_tier", "cache",
)
+# changes/2026-10-14-jev-images.md. The asset formats systemone reads
+# (docs.typesafe.ai/images "Asset fields"): PNG and JPEG, nothing else.
+_IMAGE_FORMATS: dict[str, str] = {"image/png": "png", "image/jpeg": "jpg", "image/jpg": "jpg"}
+# Images are off unless each request that carries one sends this header
+# (live 400 without it, 2026-10-14: "Images are experimental. Send the header
+# TypeSafe-Danger-Zone-Images: true to use them.").
+_IMAGES_HEADER = "TypeSafe-Danger-Zone-Images"
+
+
+def _image_reference(n: int) -> str:
+ """The n-th image's reference (1-based, in part order). The angle
+ brackets close it, so `<lm15-image-1>` never matches inside
+ `<lm15-image-10>` (systemone replaces references as plain text)."""
+ return f"<lm15-image-{n}>"
+
@dataclass
class TypeSafeLM(BaseProviderLM):
@@ -72,18 +91,43 @@ class TypeSafeLM(BaseProviderLM):
def _refuse(self, feature: str, why: str) -> UnsupportedFeatureError:
return UnsupportedFeatureError(f"{self.provider}: {why}", provider=self.provider, feature=feature)
- def _state(self, request: Request) -> Any:
+ def _check_image(self, part: ImagePart, where: str) -> None:
+ """An image reaches systemone as inline PNG or JPEG bytes, or not at
+ all (MAP-10 rule 1); lm15 never fetches or converts media."""
+ if part.url is not None or part.file_id is not None:
+ how = "a URL" if part.url is not None else "a file id"
+ raise self._refuse(
+ where,
+ f"systemone takes image bytes, not {how}; fetch the image and pass "
+ "image(data=...) or image(path=...) (changes/2026-10-14-jev-images.md)",
+ )
+ if part.media_type.lower() not in _IMAGE_FORMATS:
+ raise self._refuse(
+ where,
+ f"systemone reads PNG or JPEG images, got {part.media_type!r}; convert the image "
+ "first (lm15 never converts media)",
+ )
+
+ def _state(self, request: Request) -> tuple[Any, dict[str, Any]]:
"""changes/2026-09-19-jev-state.md D1/D2: the state is the one user
part, verbatim — a text's string or a data part's value. Jev has
no system prompt and no conversation; anything else is refused
with the native place named, never merged into a shape of ours.
- A media part is refused first, as the specific fault it is (MAP-10)."""
+ A media part is refused first, as the specific fault it is (MAP-10).
+
+ changes/2026-10-14-jev-images.md: an image part is its reference
+ string, its bytes an asset; a message holding an image and other
+ parts is the array of its parts in order. Returns (state, assets)."""
for m_index, message in enumerate(request.messages):
for p_index, part in enumerate(message.parts):
- if not isinstance(part, (TextPart, DataPart)):
+ where = f"messages[{m_index}].parts[{p_index}]"
+ if isinstance(part, ImagePart):
+ self._check_image(part, where)
+ elif not isinstance(part, (TextPart, DataPart)):
raise self._refuse(
- f"messages[{m_index}].parts[{p_index}]",
- f"a {part.type} part has no slot on the systemone wire (MAP-10); Jev reads text or data",
+ where,
+ f"a {part.type} part has no slot on the systemone wire (MAP-10); "
+ "Jev reads text, data, or PNG/JPEG images",
)
if request.system is not None:
raise self._refuse(
@@ -102,14 +146,31 @@ class TypeSafeLM(BaseProviderLM):
message = request.messages[0]
if message.role != "user":
raise self._refuse("messages[0].role", f"Jev's state is a user message, got role {message.role!r}")
- if len(message.parts) != 1:
+ has_image = any(isinstance(part, ImagePart) for part in message.parts)
+ if len(message.parts) != 1 and not has_image:
raise self._refuse(
"messages[0].parts",
f"Jev's state is one text or data part, got {len(message.parts)} parts; put several pieces "
"in one data part as named keys",
)
- only = message.parts[0]
- return only.text if isinstance(only, TextPart) else only.value # type: ignore[union-attr]
+ assets: dict[str, Any] = {}
+
+ def element(part: Part) -> Any:
+ if isinstance(part, TextPart):
+ return part.text
+ if isinstance(part, DataPart):
+ return part.value
+ reference = _image_reference(len(assets) + 1)
+ assets[reference] = {
+ "type": "image",
+ "format": _IMAGE_FORMATS[part.media_type.lower()], # type: ignore[union-attr]
+ "data_base64": media_base64(part), # type: ignore[arg-type]
+ }
+ return reference
+
+ if len(message.parts) == 1:
+ return element(message.parts[0]), assets
+ return [element(part) for part in message.parts], assets
def _questions(self, request: Request) -> dict[str, Any]:
fmt = request.config.response_format
@@ -168,7 +229,11 @@ class TypeSafeLM(BaseProviderLM):
adapt(f"config.{name}", "dropped", "no such control on the systemone wire (Jev returns decisions, not samples)",
asked=value if isinstance(value, (int, float, str, bool)) else str(value), provider=self.provider)
questions = self._questions(request)
- payload: dict[str, Any] = {"model": request.model, "state": self._state(request), "questions": questions}
+ state, assets = self._state(request)
+ payload: dict[str, Any] = {"model": request.model, "state": state}
+ if assets:
+ payload["assets"] = assets
+ payload["questions"] = questions
if cfg.extensions:
for key, value in cfg.extensions.items():
if key == "n" and isinstance(value, (int, float)) and value > 1:
@@ -180,13 +245,19 @@ class TypeSafeLM(BaseProviderLM):
request = self._wire_request(request)
if stream:
raise self._refuse("stream", "systemone answers in one piece; there is no stream to wrap")
+ payload = self._payload(request)
+ headers = {"Content-Type": "application/json"}
+ if "assets" in payload:
+ # The caller put an image in the request: that is the opt-in the
+ # header exists for (changes/2026-10-14-jev-images.md D3).
+ headers[_IMAGES_HEADER] = "true"
return self._emit(
method="POST",
url=f"{self.base_url.rstrip('/')}/v1/systemone",
endpoint="systemone",
model=request.model,
- headers={"Content-Type": "application/json"},
- payload=self._payload(request),
+ headers=headers,
+ payload=payload,
)
# ─── Response parsing (pure) ────────────────────────────────────
diff --git a/dspy/_vendor/lm15/providers/xai.py b/dspy/_vendor/lm15/providers/xai.py
index 404c868a8..01883d6ff 100644
--- a/dspy/_vendor/lm15/providers/xai.py
+++ b/dspy/_vendor/lm15/providers/xai.py
@@ -39,7 +39,7 @@ import os
from typing import Any, ClassVar
from ..access import DEFAULT_XAI_BASE_URL, XAI
-from ..adaptation import adapt
+from ..adaptation import AdaptationPolicy, adapt
from ..errors import ProviderError, UnsupportedFeatureError
from ..features import ProviderManifest
from ..transports import TransportRequest
diff --git a/dspy/_vendor/lm15/registry.py b/dspy/_vendor/lm15/registry.py
index d17ee5ca8..8bd11c60a 100644
--- a/dspy/_vendor/lm15/registry.py
+++ b/dspy/_vendor/lm15/registry.py
@@ -472,6 +472,27 @@ _DEFINITIONS: tuple[ProviderDefinition, ...] = (
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)",
),
+ _chat_bound(
+ _access.DEEPINFRA,
+ console_url="https://deepinfra.com/dash/api_keys",
+ note="DeepInfra open-model inference (Chat Completions dialect; models are vendor/name ids)",
+ ),
+ _chat_bound(
+ _access.TOGETHER,
+ console_url="https://api.together.ai/settings/projects/~current/api-keys",
+ note="Together AI open-model inference (Chat Completions dialect; gpt-oss refuses a forced tool choice client-side — "
+ "Together answers it with HTTP 500)",
+ ),
+ _chat_bound(
+ _access.FIREWORKS,
+ console_url="https://app.fireworks.ai/settings/users/api-keys",
+ note="Fireworks AI open-model inference (Chat Completions dialect; models are accounts/fireworks/models/<name> ids)",
+ ),
+ _chat_bound(
+ _access.PARASAIL,
+ console_url="https://www.saas.parasail.io/keys",
+ note="Parasail open-model inference (Chat Completions dialect; serverless models)",
+ ),
_responses_bound(
_access.META,
compat="meta",
diff --git a/dspy/_vendor/lm15/router.py b/dspy/_vendor/lm15/router.py
index 28775a789..865952557 100644
--- a/dspy/_vendor/lm15/router.py
+++ b/dspy/_vendor/lm15/router.py
@@ -80,11 +80,12 @@ from typing import AsyncIterator, Iterator, Literal, Mapping, overload
from .result import AsyncResponseStream, ResponseStream
-from .errors import AmbiguousModelError, NotConfiguredError, UnknownModelError
+from .errors import AmbiguousModelError, AuthOperationError, NotConfiguredError, UnknownModelError
from .models import ModelInfo, ModelRegistry
from .providers import Credential
from .registry import PROVIDERS, Compat, ProviderDefinition, canonical_provider as _canonical_provider
from .adaptation import AdaptationPolicy, check_policy
+from .features import AccessPolicy
from .transports import Timeouts
from .types import Request, Response, StreamEvent
@@ -196,9 +197,18 @@ def _table(adapters: Mapping[str, type], config: RouterConfig) -> Mapping[str, t
"""``adapters`` as a router uses it: unchanged when nothing is declared
(the module views keep their identity), else wrapped with the config's
declared providers."""
- if not config.providers:
+ declared = config.providers
+ if config.auth is not None:
+ # A managed router also routes the connection-only doors (kimi-code,
+ # github-copilot): declared providers, marked as such, added only
+ # here because only a managed Auth can hold their credential.
+ from .login.declared import DECLARED_PROVIDERS
+
+ taken = {d.id for d in declared}
+ declared = declared + tuple(d for d in DECLARED_PROVIDERS if d.id not in taken)
+ if not declared:
return adapters
- return _Table(adapters, config.providers, is_async=adapters is ASYNC_ADAPTERS)
+ return _Table(adapters, declared, is_async=adapters is ASYNC_ADAPTERS)
def _definitions(adapters: Mapping[str, type]) -> Mapping[str, ProviderDefinition]:
@@ -513,19 +523,34 @@ class RouterConfig:
# wire). Applied to every LM the router builds.
adaptations: AdaptationPolicy = field(default="note", kw_only=True)
providers: tuple[ProviderDefinition, ...] = field(default=(), kw_only=True)
+ # Managed authentication (spec/auth.md AUTH-15 mode B, ratified
+ # 2026-09-22): a ``lm15.login.Auth`` whose saved connections supply the
+ # credential when no explicit ``api_keys``/``credentials`` entry does.
+ # With it attached, environment keys, foreign CLI files and the
+ # machine's cloud identity are never consulted: a missing, expired,
+ # rejected or signed-out connection is a typed ``AuthOperationError``,
+ # never a silent switch to a metered key. Keyless local servers still
+ # work without a connection.
+ auth: object | None = field(default=None, kw_only=True, repr=False)
def __post_init__(self) -> None:
check_policy(self.adaptations)
_check_declared(self.providers)
+ if self.auth is not None:
+ from .login.manager import Auth
+
+ if not isinstance(self.auth, Auth):
+ raise TypeError(f"RouterConfig(auth=...) takes a lm15.login.Auth, got {type(self.auth).__name__}")
if self.credentials is not None:
from .features import NAMED_CREDENTIALS
for key, name in self.credentials.items():
if name not in NAMED_CREDENTIALS:
raise NotConfiguredError(
- f"RouterConfig(credentials={{{key!r}: {name!r}}}): not a named credential; one of "
+ f"RouterConfig(credentials={{{key!r}: ...}}): the value is not a named credential (one of "
+ ", ".join(repr(n) for n in NAMED_CREDENTIALS)
- + ". A credential VALUE (a key, a token, a callable) goes in api_keys=."
+ + "), so it is not shown (it may be a key; AUTH-5). A credential VALUE (a key, a token, a "
+ "callable) goes in api_keys=."
)
if self.timeouts is not None and not isinstance(self.timeouts, Timeouts):
raise TypeError(
@@ -902,6 +927,32 @@ def _env_key_for(provider: str, config: RouterConfig, adapters: Mapping[str, typ
return env_keys[0]
+def _settings_entry(config: RouterConfig, provider: str) -> Mapping[str, str] | None:
+ """The ``settings`` entry for ``provider``, under any spelling of its name."""
+ for key, value in (config.settings or {}).items():
+ if _canonical_provider(key) == provider:
+ return value
+ return None
+
+
+def _backend_settings(config: RouterConfig, provider: str, cls: type,
+ definition: "ProviderDefinition | None", *, sources: dict[str, str] | None = None) -> dict[str, str] | None:
+ """A door without a host: its backend settings (AUTH-10, amended
+ 2026-09-30) from the config's entry, then the environment, then the
+ table's default — ``client_version`` on the subscription doors. None
+ when the door declares none and the config gives none; a settings entry
+ for a door that reads none raises (NotConfiguredError), because nothing
+ would read it."""
+ from .access import resolve_backend_settings
+
+ policy: AccessPolicy = definition.access if definition is not None else getattr(cls, "manifest")
+ given = _settings_entry(config, provider)
+ if not given and not policy.backend_settings:
+ return None
+ env = config.env if config.env is not None else os.environ
+ return resolve_backend_settings(policy, given, env, sources=sources)
+
+
def _build_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[str, type], transport: object | None = None):
cls = _adapter_for(resolution.provider, adapters)
definition = _bound(resolution.provider, adapters)
@@ -916,7 +967,13 @@ def _build_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[st
base_url = _hosted_endpoint(config, resolution.provider, definition) if hosted else _base_url_entry(config, resolution.provider)
if base_url is not None:
extra["base_url"] = base_url
+ if not hosted:
+ door = _backend_settings(config, resolution.provider, cls, definition)
+ if door:
+ extra["settings"] = door
policy = _credential_policy(resolution.provider, adapters)
+ if config.auth is not None:
+ return _build_managed_lm(resolution, config, adapters, cls, definition, extra, hosted, base_url)
if policy == "oauth":
return cls(**extra) # self-resolving local OAuth constructor
api_key, _ = _api_keys_entry(config, resolution.provider, adapters)
@@ -962,10 +1019,32 @@ def _build_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[st
if origin is not None:
_set_origin(lm, origin)
return lm
- 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 and policy == "oauth-unless-explicit":
+ # A usable stored subscription login outranks ambient env keys: it
+ # spends no money per token (AUTH-1, oauth-unless-explicit). An
+ # unusable or signed-out one BLOCKS them (R3, ratified 2026-09-22):
+ # a failed subscription is never silently replaced by a metered key.
+ probe = getattr(cls, "stored_credential_state", None)
+ if callable(probe):
+ state = probe()
+ else: # an adapter written against the older boolean probe
+ state = "usable" if cls.has_stored_credential() else "absent"
+ if state == "usable":
+ return cls(**extra) # self-resolving local OAuth constructor
+ if state in ("unusable", "logged_out"):
+ env_keys = _declared_env_keys(resolution.provider, adapters)
+ env = config.env if config.env is not None else os.environ
+ present = [key for key in env_keys if env.get(key)]
+ what = "was signed out" if state == "logged_out" else "is expired and cannot be renewed"
+ raise MissingCredentialError(
+ f"the {resolution.provider!r} subscription login {what}. "
+ + (f"${present[0]} is set but is used only when passed explicitly: " if present else "")
+ + f"sign in again ({cls.manifest.login_hint}), or pass the key deliberately with "
+ f"RouterConfig(api_keys={{{resolution.provider!r}: \"...\"}}).",
+ provider=resolution.provider,
+ env_keys=env_keys,
+ credential_hint=cls.manifest.login_hint,
+ )
origin: str | None = None
if api_key is None:
env = config.env if config.env is not None else os.environ
@@ -1003,6 +1082,111 @@ def _build_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[st
return lm
+def _build_managed_lm(resolution: Resolution, config: RouterConfig, adapters: Mapping[str, type], cls: type,
+ definition: "ProviderDefinition | None", extra: dict, hosted: bool, base_url: str | None,
+ *, snapshot=None):
+ """AUTH-15 mode B. Order: explicit ``api_keys`` entry; explicit named
+ cloud identity; the scope's saved connection (renewed per request);
+ a keyless local server's placeholder. Never an environment key, a
+ foreign CLI file or the machine's cloud chain."""
+ from .login.manager import Auth, _RequestSnapshot
+
+ auth: Auth = config.auth # type: ignore[assignment]
+ provider = resolution.provider
+ original_definition, original_extra, original_url = definition, dict(extra), base_url
+ saved = None
+ connection = None
+ api_key, explicit = _api_keys_entry(config, provider, adapters)
+ named = _credentials_entry(config, provider)
+ origin: str | None = None
+ account_id: str | None = None
+ if not explicit and named is None:
+ try:
+ saved = snapshot if snapshot is not None else auth.request_auth(provider)
+ except AuthOperationError as exc:
+ if exc.reason == "login_required" and definition is not None and definition.placeholder_key is not None \
+ and not auth.status(provider).logged_out:
+ api_key = definition.placeholder_key
+ origin = "the local server's placeholder key"
+ elif exc.reason == "login_required" and definition is not None and definition.hosted:
+ raise AuthOperationError(
+ f"{provider}: no saved connection in this scope; the machine's cloud identity is not used "
+ "under a managed Auth — save a named identity (Auth.configure(method='cloud')) or pass "
+ "RouterConfig(credentials=...) explicitly",
+ reason="login_required", stage="resolution", recovery="select_connection", provider=provider,
+ ) from exc
+ else:
+ raise
+ else:
+ if not isinstance(saved, _RequestSnapshot):
+ raise AuthOperationError("managed authentication requires a connection snapshot",
+ reason="indeterminate", stage="resolution")
+ connection = saved.connection
+ if saved.named is not None:
+ named = saved.named # a saved cloud recipe names the identity; the chain rung runs
+ else:
+ api_key = saved.credential
+ account_id = saved.account_id
+ if saved.base_url is not None and base_url is None:
+ base_url = saved.base_url
+ extra["base_url"] = base_url
+ if saved.headers and definition is not None and not definition.hosted:
+ from dataclasses import replace as _replace
+
+ merged = tuple(definition.access.headers) + tuple(
+ (k, v) for k, v in saved.headers.items() if k.lower() not in {h[0].lower() for h in definition.access.headers}
+ )
+ definition = _replace(definition, access=_replace(definition.access, headers=merged))
+ origin = (f"managed connection {connection.id} ({connection.label})" if connection is not None
+ else "managed connection")
+ if hosted:
+ from .cloud.chains import ChainContext, credential_provider, profile_settings
+ from .cloud.hosts import resolve_settings
+
+ env = config.env if config.env is not None else os.environ
+ given = dict(connection.settings) if connection is not None else {}
+ given.update(_settings_entry(config, provider) or {})
+ ctx = ChainContext.online(env)
+ settings = resolve_settings(definition.access.host, given, env, provider=provider,
+ profile=profile_settings(definition.access, ctx), endpoint=base_url)
+ ctx.settings = settings
+ if api_key is None and named is not None:
+ api_key = credential_provider(definition.access, ctx, named=named)
+ if api_key is None:
+ raise AuthOperationError(
+ f"{provider}: no credential for this cloud door under a managed Auth",
+ reason="login_required", stage="resolution", recovery="select_connection", provider=provider,
+ )
+ if definition.compat is not None:
+ extra["compat"] = definition.compat
+ lm = cls(api_key=api_key, access=definition.access, settings=settings, **extra)
+ elif definition is not None and definition.bound:
+ lm = cls(api_key=api_key, compat=definition.compat, access=definition.access, **extra)
+ else:
+ if account_id is not None:
+ extra["account_id"] = account_id
+ lm = cls(api_key=api_key, **extra)
+ if origin is not None:
+ _set_origin(lm, origin)
+ if saved is not None:
+ inner = getattr(lm, "_inner", lm)
+ if snapshot is None:
+ def prepare():
+ execution_extra = dict(original_extra, transport=lm.transport, adaptations=lm.adaptations)
+ return _build_managed_lm(
+ resolution, config, adapters, cls, original_definition, execution_extra, hosted,
+ original_url, snapshot=auth.request_auth(provider),
+ )
+ lm._managed_prepare = prepare
+ inner._managed_prepare = prepare
+ else:
+ def admission():
+ auth._admit(saved)
+ lm._managed_admit = admission
+ inner._managed_admit = admission
+ return lm
+
+
PLANNING_KEY = "lm15-planning"
@@ -1030,6 +1214,10 @@ def _build_planning_lm(resolution: Resolution, config: RouterConfig, adapters: M
# The Codex backend derives an account id from its token at
# construction; a placeholder token has none, so name one.
extra["account_id"] = PLANNING_KEY
+ if definition is None or not definition.hosted:
+ door = _backend_settings(config, resolution.provider, cls, definition)
+ if door:
+ extra["settings"] = door
if definition is None:
return cls(**extra)
if definition.hosted:
@@ -1076,6 +1264,10 @@ LITELLM_PROVIDER_PREFIXES: Mapping[str, str] = MappingProxyType({
"hosted_vllm": "vllm",
"moonshot": "moonshotai",
"azure": "azure-chat",
+ "deepinfra": "deepinfra",
+ "together_ai": "together",
+ "fireworks_ai": "fireworks",
+ "parasail": "parasail",
})
# The same prefixes in canonical spelling, for the collision check a
diff --git a/dspy/_vendor/lm15/serde.py b/dspy/_vendor/lm15/serde.py
index b0dd33473..0975d5bb3 100644
--- a/dspy/_vendor/lm15/serde.py
+++ b/dspy/_vendor/lm15/serde.py
@@ -8,6 +8,7 @@ in memory. No name translation (no "arguments" vs "input" split).
from __future__ import annotations
+from pathlib import PurePath, PureWindowsPath
from typing import Any
from .adaptation import adaptation_from_dict, adaptation_to_dict
@@ -192,7 +193,7 @@ def part_to_dict(part: Part) -> dict[str, Any]:
if part.file_id is not None:
d["file_id"] = part.file_id
if part.path is not None:
- d["path"] = str(part.path)
+ d["path"] = _wire_path(part.path)
if hasattr(part, "detail") and part.detail is not None:
d["detail"] = part.detail
@@ -925,6 +926,18 @@ def batch_entry_from_dict(d: dict[str, Any]) -> BatchEntry:
# ─── Files ─────────────────────────────────────────────────────────
+def _wire_path(path: PurePath | str) -> str:
+ """A local path on the wire: ``/`` as the separator on every OS (INV-009,
+ clarified 2026-09-24), so the same request serializes identically on
+ Windows, where ``str(Path("/data/x"))`` is ``\\data\\x``; Windows reads
+ ``/`` back (``C:/Users/...``). Only a Windows path's ``\\`` is replaced: on
+ POSIX a backslash is an ordinary character in a name. (Not
+ ``as_posix()``: Python 3.10 turns ``\\data\\x`` into ``\\/data/x``.)"""
+ p = PurePath(path) if isinstance(path, str) else path
+ text = str(p)
+ return text.replace("\\", "/") if isinstance(p, PureWindowsPath) else text
+
+
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
@@ -937,7 +950,7 @@ def file_upload_request_to_dict(r: FileUploadRequest) -> dict[str, Any]:
"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,
+ "path": _wire_path(r.path) if r.path is not None else None,
})
diff --git a/dspy/_vendor/lm15/sse.py b/dspy/_vendor/lm15/sse.py
index 93f99e592..bc0e48a72 100644
--- a/dspy/_vendor/lm15/sse.py
+++ b/dspy/_vendor/lm15/sse.py
@@ -3,6 +3,15 @@ lm15.sse — Server-Sent Events parser.
Parses a byte-line iterator (from a streaming HTTP response) into
typed SSEEvent objects.
+
+No size limit by default (lm15-contract INV-056). A provider sends whole
+objects as single lines: OpenAI Responses repeats the full response,
+system prompt included, in ``response.completed``; Gemini sends a 4K image
+as one 29.7 MB line. A non-streamed reply has no limit either, and a stream
+is accumulated into the whole reply anyway, so a per-line cap refused real
+answers without bounding memory. Callers who want a cap on this parser set
+``max_line_bytes`` / ``max_event_bytes``; going over one raises
+``TransportError``.
"""
from __future__ import annotations
@@ -22,21 +31,25 @@ class SSEEvent:
def parse_sse(
lines: Iterator[bytes],
*,
- max_line_bytes: int = 64 * 1024,
- max_event_bytes: int = 1024 * 1024,
+ max_line_bytes: int | None = None,
+ max_event_bytes: int | None = None,
) -> Iterator[SSEEvent]:
- """Parse SSE byte lines into events."""
+ """Parse SSE byte lines into events.
+
+ ``max_line_bytes`` / ``max_event_bytes`` are opt-in caps (``None``: no
+ cap, INV-056); a line or event over a cap raises ``TransportError``.
+ """
event_name: str | None = None
data_lines: list[str] = []
event_bytes = 0
for raw in lines:
- if len(raw) > max_line_bytes:
+ if max_line_bytes is not None and 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:
+ if max_event_bytes is not None and event_bytes > max_event_bytes:
raise TransportError(f"SSE event exceeds limit ({event_bytes} > {max_event_bytes})")
if line == "":
@@ -63,12 +76,12 @@ def parse_sse(
async def aparse_sse(
lines: AsyncIterator[bytes],
*,
- max_line_bytes: int = 64 * 1024,
- max_event_bytes: int = 1024 * 1024,
+ max_line_bytes: int | None = None,
+ max_event_bytes: int | None = None,
) -> 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
+ Same field grammar and opt-in caps; the only difference is ``async for`` over
the line source.
"""
event_name: str | None = None
@@ -76,12 +89,12 @@ async def aparse_sse(
event_bytes = 0
async for raw in lines:
- if len(raw) > max_line_bytes:
+ if max_line_bytes is not None and 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:
+ if max_event_bytes is not None and event_bytes > max_event_bytes:
raise TransportError(f"SSE event exceeds limit ({event_bytes} > {max_event_bytes})")
if line == "":
diff --git a/dspy/_vendor/lm15/tools.py b/dspy/_vendor/lm15/tools.py
deleted file mode 100644
index 8fee390f2..000000000
--- a/dspy/_vendor/lm15/tools.py
+++ /dev/null
@@ -1,725 +0,0 @@
-"""
-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/_types.py b/dspy/_vendor/lm15/transports/_types.py
index c5ee42428..3f04bb3c1 100644
--- a/dspy/_vendor/lm15/transports/_types.py
+++ b/dspy/_vendor/lm15/transports/_types.py
@@ -8,7 +8,7 @@ HTTP transport.
from __future__ import annotations
from dataclasses import dataclass, field
-from typing import AsyncIterator, Iterator
+from typing import AsyncIterable, AsyncIterator, Awaitable, Callable, Iterable, Iterator
@dataclass(slots=True)
@@ -21,6 +21,66 @@ class TransportRequest:
connect_timeout: float | None = None
read_timeout: float | None = None
write_timeout: float | None = None
+ _admit: Callable[[], None] | None = field(default=None, repr=False, compare=False)
+
+
+class LineSplitter:
+ """Split body chunks into newline-terminated lines in linear time.
+
+ A provider can send one line of tens of megabytes (Gemini streams a 4K
+ image as a single 29.7 MB SSE line, lm15-contract INV-056) in thousands
+ of reads. Searching the whole buffer for ``\\n`` after every read is
+ quadratic in that line's length; this searches only the bytes that have
+ not been searched yet, and copies a line once, when it is complete.
+ Lines keep their ``\\n``; a last line without one is yielded at the end.
+ """
+
+ __slots__ = ("_buf", "_searched")
+
+ def __init__(self) -> None:
+ self._buf = bytearray()
+ self._searched = 0
+
+ def feed(self, chunk: bytes) -> list[bytes]:
+ """Take one chunk; return the lines it completed, in order."""
+ buf = self._buf
+ buf += chunk
+ lines: list[bytes] = []
+ start = 0
+ idx = buf.find(b"\n", self._searched)
+ while idx >= 0:
+ lines.append(bytes(buf[start : idx + 1]))
+ start = idx + 1
+ idx = buf.find(b"\n", start)
+ if start:
+ del buf[:start]
+ self._searched = len(buf)
+ return lines
+
+ def finish(self) -> list[bytes]:
+ """End of body: the unterminated last line, if any."""
+ rest = bytes(self._buf)
+ self._buf.clear()
+ self._searched = 0
+ return [rest] if rest else []
+
+ @classmethod
+ def iterate(cls, chunks: Iterable[bytes]) -> Iterator[bytes]:
+ splitter = cls()
+ for chunk in chunks:
+ if chunk:
+ yield from splitter.feed(chunk)
+ yield from splitter.finish()
+
+ @classmethod
+ async def aiterate(cls, chunks: AsyncIterable[bytes]) -> AsyncIterator[bytes]:
+ splitter = cls()
+ async for chunk in chunks:
+ if chunk:
+ for line in splitter.feed(chunk):
+ yield line
+ for line in splitter.finish():
+ yield line
class TransportResponse:
@@ -44,7 +104,7 @@ class TransportResponse:
headers: list[tuple[str, str]],
http_version: str,
chunks: Iterator[bytes],
- release: "callable",
+ release: Callable[[bool], None],
) -> None:
self.status = status
self.reason = reason
@@ -79,21 +139,11 @@ class TransportResponse:
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)
+ """Yield newline-terminated byte lines from arbitrary body chunks.
+
+ Linear in the bytes received, however long a line is (see
+ :class:`LineSplitter`)."""
+ return LineSplitter.iterate(self)
def close(self) -> None:
self._release_once(body_consumed=self._complete)
@@ -130,7 +180,7 @@ class AsyncTransportResponse:
headers: list[tuple[str, str]],
http_version: str,
chunks: AsyncIterator[bytes],
- release: "callable",
+ release: Callable[[bool], Awaitable[None]],
) -> None:
self.status = status
self.reason = reason
@@ -170,22 +220,12 @@ class AsyncTransportResponse:
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)
+ def aiter_lines(self) -> AsyncIterator[bytes]:
+ """Yield newline-terminated byte lines from arbitrary body chunks.
+
+ Linear in the bytes received, however long a line is (see
+ :class:`LineSplitter`)."""
+ return LineSplitter.aiterate(self)
async def aclose(self) -> None:
await self._release_once(body_consumed=self._complete)
diff --git a/dspy/_vendor/lm15/types.py b/dspy/_vendor/lm15/types.py
index 3163d4a3c..c41e27409 100644
--- a/dspy/_vendor/lm15/types.py
+++ b/dspy/_vendor/lm15/types.py
@@ -45,11 +45,11 @@ import json as _json
import math as _math
import mimetypes as _mimetypes
import re as _re
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
from dataclasses import dataclass, field
from os import PathLike
from pathlib import Path
-from typing import Any, Literal, TypeAlias, TypeVar, get_args
+from typing import TYPE_CHECKING, Any, Literal, TypeAlias, TypeVar, get_args
from .adaptation import Adaptation
@@ -94,6 +94,7 @@ ReasoningSummary = Literal["auto", "concise", "detailed"]
ErrorCode = Literal[
"auth",
+ "auth_operation",
"billing",
"rate_limit",
"invalid_request",
@@ -126,6 +127,7 @@ LiveServerEventType = Literal["audio", "text", "tool_call", "tool_call_delta", "
ROLE_VALUES = frozenset(get_args(Role))
FINISH_REASONS = frozenset(get_args(FinishReason))
REASONING_EFFORTS = frozenset(get_args(ReasoningEffort))
+_REASONING_EFFORT_ORDER: tuple[str, ...] = get_args(ReasoningEffort)
REASONING_SUMMARIES = frozenset(get_args(ReasoningSummary))
BATCH_STATUSES = frozenset(get_args(BatchStatus))
BATCH_OUTCOMES = frozenset(get_args(BatchOutcome))
@@ -636,6 +638,17 @@ class ToolCallPart:
continuation: tuple[ContinuationState, ...] = ()
type: Literal["tool_call"] = field(default="tool_call", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ id: str,
+ name: str,
+ input: dict[str, Any],
+ continuation: ContinuationState | Sequence[ContinuationState] = ...,
+ ) -> None: ...
+ # END generated
+
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)
@@ -654,6 +667,18 @@ class ToolResultPart:
continuation: tuple[ContinuationState, ...] = ()
type: Literal["tool_result"] = field(default="tool_result", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ id: str,
+ content: Sequence[ToolResultContentPart],
+ name: str | None = ...,
+ is_error: bool = ...,
+ continuation: ContinuationState | Sequence[ContinuationState] = ...,
+ ) -> None: ...
+ # END generated
+
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)
@@ -768,6 +793,17 @@ class DataPart:
continuation: tuple[ContinuationState, ...] = ()
type: Literal["data"] = field(default="data", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ value: object,
+ probabilities: Mapping[str, Mapping[str, float]] | None = ...,
+ method: JudgmentMethod | None = ...,
+ continuation: ContinuationState | Sequence[ContinuationState] = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
if not _is_json_value(self.value):
raise TypeError("DataPart.value must be a JSON-compatible value")
@@ -1163,6 +1199,16 @@ class Message:
parts: tuple[Part, ...]
continuation: tuple[ContinuationState, ...] = ()
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ role: Role,
+ parts: Part | Sequence[Part],
+ continuation: ContinuationState | Sequence[ContinuationState] = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
if self.role not in ROLE_VALUES:
raise ValueError(f"unsupported role: {self.role}")
@@ -1204,7 +1250,7 @@ class Message:
@staticmethod
def tool(
- results: "str | ToolResultPart | Sequence[ToolResultPart] | dict[str, ToolResultContent]",
+ results: "str | ToolResultPart | Sequence[ToolResultPart] | Mapping[str, ToolResultContent]",
output: "ToolResultContent | None" = None,
*,
is_error: bool = False,
@@ -1241,7 +1287,7 @@ class Message:
"Message.tool(call_id, output, is_error=True) or "
"lm15.tool_result(call_id, output, is_error=True)."
)
- if isinstance(results, dict):
+ if isinstance(results, Mapping):
parts: list[Part] = []
for call_id, value in results.items():
parts.append(tool_result(call_id, value))
@@ -1683,6 +1729,16 @@ class FunctionTool:
)
type: Literal["function"] = field(default="function", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ name: str,
+ description: str | None = ...,
+ parameters: dict[str, Any] = ...,
+ ) -> None: ...
+ # END generated
+
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")
@@ -1696,6 +1752,11 @@ class BuiltinTool:
config: JsonObject | None = None
type: Literal["builtin"] = field(default="builtin", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(self, name: str, config: dict[str, Any] | None = ...) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_validate_text(self.name, field_name="BuiltinTool.name", allow_empty=False)
_validate_json_field(self, "config")
@@ -1707,6 +1768,29 @@ Tool: TypeAlias = FunctionTool | BuiltinTool
# ─── Configuration ───────────────────────────────────────────────────
+# MAP-7 rule 3: the one grading table between effort levels and thinking
+# budgets. Budget-only wires read it level -> budget; a Reasoning given only
+# a budget reads it the other way (amended 2026-10-10).
+EFFORT_THINKING_BUDGETS: dict[str, int] = {
+ "minimal": 1024,
+ "low": 2048,
+ "medium": 8192,
+ "high": 16384,
+ "xhigh": 24576,
+ "max": 32768,
+}
+
+
+def effort_for_budget(budget: int) -> str:
+ """The highest effort level whose table budget is at or below ``budget``
+ (``minimal`` below 1024) — MAP-7 rule 3 read the other way."""
+ level = "minimal"
+ for name, tokens in EFFORT_THINKING_BUDGETS.items():
+ if tokens <= budget:
+ level = name
+ return level
+
+
@dataclass(frozen=True, slots=True)
class Reasoning:
"""How much hidden thinking the model does before it answers (MAP-7).
@@ -1734,18 +1818,57 @@ class Reasoning:
show the thinking where a knob exists (satisfied silently where the
provider always shows it), ``"concise"``/``"detailed"`` = OpenAI's
detail levels (RAISE elsewhere).
+
+ ``Reasoning(thinking_budget=2000)`` alone is accepted: ``effort`` is
+ filled from the grading table read the other way (here ``"minimal"``;
+ MAP-7 rule 3, amended 2026-10-10).
"""
- effort: ReasoningEffort
+ # Stored: always a word once built (a budget alone fills it, below). The
+ # constructor also takes None; the generated __init__ block says so.
+ effort: ReasoningEffort = None # type: ignore[assignment]
thinking_budget: int | None = None
summary: ReasoningSummary | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ effort: ReasoningEffort | None = ...,
+ thinking_budget: int | None = ...,
+ summary: ReasoningSummary | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
+ if self.effort is None:
+ if self.thinking_budget is None:
+ raise TypeError(
+ "Reasoning needs effort= (one of " + ", ".join(repr(e) for e in _REASONING_EFFORT_ORDER)
+ + ") or thinking_budget=; leave Config.reasoning unset to let the model decide"
+ )
+ _coerce_int_field(self, "thinking_budget")
+ if self.thinking_budget == 0 and not isinstance(self.thinking_budget, bool):
+ raise ValueError(
+ "thinking_budget must be > 0; to turn thinking off, use Reasoning(effort='off') with no budget"
+ )
+ _validate_positive(self.thinking_budget, field_name="thinking_budget")
+ object.__setattr__(self, "effort", effort_for_budget(self.thinking_budget))
if self.effort not in REASONING_EFFORTS:
- raise ValueError(f"unsupported reasoning effort: {self.effort}")
+ hint = ""
+ if self.effort == "none":
+ hint = " (lm15 spells \"none\" as effort='off')"
+ elif self.effort is not None:
+ hint = " (one of " + ", ".join(repr(e) for e in _REASONING_EFFORT_ORDER) + ")"
+ raise ValueError(f"unsupported reasoning effort: {self.effort}{hint}")
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")
+ if self.thinking_budget == 0 and not isinstance(self.thinking_budget, bool):
+ # Gemini spells "thinking off" as thinkingBudget: 0; lm15 spells it effort="off".
+ raise ValueError(
+ "thinking_budget must be > 0; to turn thinking off, use Reasoning(effort='off') with no 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(
@@ -1834,6 +1957,16 @@ class ToolChoice:
allowed: tuple[str, ...] = ()
parallel: bool | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ mode: ToolChoiceMode = ...,
+ allowed: str | Sequence[str] = ...,
+ parallel: bool | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
if self.mode not in TOOL_CHOICE_MODES:
raise ValueError(f"unsupported tool choice mode: {self.mode}")
@@ -1919,6 +2052,31 @@ class Config:
probabilities: ProbabilityPolicy | None = None
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ max_tokens: int | None = ...,
+ temperature: float | None = ...,
+ top_p: float | None = ...,
+ top_k: int | None = ...,
+ stop: str | Sequence[str] = ...,
+ response_format: dict[str, Any] | None = ...,
+ tool_choice: ToolChoice | None = ...,
+ reasoning: Reasoning | None = ...,
+ cache: CacheConfig | None = ...,
+ seed: int | None = ...,
+ frequency_penalty: float | None = ...,
+ presence_penalty: float | None = ...,
+ service_tier: str | None = ...,
+ user_id: str | None = ...,
+ store: bool | None = ...,
+ logprobs: int | None = ...,
+ probabilities: ProbabilityPolicy | None = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
stop = (self.stop,) if isinstance(self.stop, str) else tuple(self.stop or ())
object.__setattr__(self, "stop", stop)
@@ -2009,6 +2167,30 @@ def _validate_response_format_shape(value: JsonObject | None) -> None:
# ─── Request ─────────────────────────────────────────────────────────
+def _tools_tuple(tools: Any) -> tuple[Any, ...]:
+ """One tool, or a function passed where a tool belongs, becomes a one-tuple so the check below names it."""
+ if isinstance(tools, (FunctionTool, BuiltinTool)) or callable(tools):
+ return (tools,)
+ return tuple(tools)
+
+
+def _require_tools(owner: str, tools: tuple[Any, ...]) -> None:
+ """Tools are data: a request never holds a function. A function gets the fix named."""
+ for item in tools:
+ if isinstance(item, (FunctionTool, BuiltinTool)):
+ continue
+ if callable(item):
+ name = getattr(item, "__name__", None)
+ name = name if isinstance(name, str) and name.isidentifier() else None
+ what = f"the function {name!r}" if name else f"a callable {type(item).__name__} object"
+ raise TypeError(
+ f"{owner}.tools must contain Tool objects, not {what}: describe it as "
+ 'FunctionTool(name=..., description=..., parameters={...JSON Schema...}) '
+ "and keep the function to run when the model calls it."
+ )
+ raise TypeError(f"{owner}.tools must contain Tool objects, not {type(item).__name__}")
+
+
@dataclass(frozen=True, slots=True)
class _ModelRequest:
"""Base for endpoint requests/configs that require a model."""
@@ -2033,12 +2215,23 @@ class Request(_ModelRequest):
tools: tuple[Tool, ...] = ()
config: Config = field(default_factory=Config)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str,
+ messages: Message | Sequence[Message],
+ system: SystemContent | None = ...,
+ tools: Tool | Sequence[Tool] = ...,
+ config: Config = ...,
+ ) -> None: ...
+ # END generated
+
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, "tools", _tools_tuple(self.tools))
object.__setattr__(self, "system", _normalize_system(self.system))
if not self.messages:
raise ValueError("at least one message is required")
@@ -2047,8 +2240,7 @@ class Request(_ModelRequest):
'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")
+ _require_tools("Request", self.tools)
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")
@@ -2112,6 +2304,18 @@ class TokenLogprob:
token_id: int | None = None
top: tuple[TopLogprob, ...] = ()
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ token: str,
+ logprob: float,
+ bytes: tuple[int, ...] | None = ...,
+ token_id: int | None = ...,
+ top: TopLogprob | Sequence[TopLogprob] = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_validate_text(self.token, field_name="token")
_coerce_float_field(self, "logprob")
@@ -2319,6 +2523,15 @@ class Response:
text_parts = [p.text for p in self.message.parts if isinstance(p, TextPart)]
if text_parts:
return "\n".join(text_parts)
+ # A structured answer that came back as a DataPart (MAP-14: a schema
+ # with a judgment property) reads as its compact JSON, so .text,
+ # .parse_json() and .json work whichever form the wire gave it
+ # (types.md §Response convenience, amended 2026-10-10).
+ data_parts = [p for p in self.message.parts if isinstance(p, DataPart)]
+ if len(data_parts) == 1 and all(
+ isinstance(p, (DataPart, CitationPart, ThinkingPart)) for p in self.message.parts
+ ):
+ return _json.dumps(data_parts[0].value, separators=(",", ":"), ensure_ascii=False)
return None
@property
@@ -2418,6 +2631,18 @@ class FileUploadRequest:
extensions: Extensions | None = None
path: Path | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ filename: str,
+ bytes_data: bytes | None = ...,
+ media_type: str = ...,
+ extensions: Extensions | None = ...,
+ path: Path | None = ...,
+ ) -> None: ...
+ # END generated
+
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):
@@ -2515,6 +2740,15 @@ class FilePage:
items: tuple[FileInfo, ...] = ()
next_cursor: str | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ items: Sequence[FileInfo] = ...,
+ next_cursor: str | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
object.__setattr__(self, "items", tuple(self.items))
if not all(isinstance(item, FileInfo) for item in self.items):
@@ -2568,6 +2802,15 @@ class CachePage:
items: tuple[CacheInfo, ...] = ()
next_cursor: str | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ items: Sequence[CacheInfo] = ...,
+ next_cursor: str | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
object.__setattr__(self, "items", tuple(self.items))
if not all(isinstance(item, CacheInfo) for item in self.items):
@@ -2695,6 +2938,17 @@ class BatchRequest:
label: str | None = None
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str | None = ...,
+ requests: Sequence[Request] = ...,
+ label: str | None = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
object.__setattr__(self, "requests", tuple(self.requests))
if not self.requests:
@@ -2803,6 +3057,18 @@ class ImageGenerationRequest(_PromptRequest):
images: tuple[ImagePart, ...] = ()
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str,
+ prompt: str,
+ size: str | None = ...,
+ images: Sequence[ImagePart] = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_PromptRequest.__post_init__(self)
_validate_optional_text(self.size, field_name="size", allow_empty=False)
@@ -2824,6 +3090,19 @@ class ImageGenerationResponse:
usage: Usage = field(default_factory=Usage)
provider_data: ProviderData | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ images: Sequence[ImagePart],
+ text: str | None = ...,
+ id: str | None = ...,
+ model: str | None = ...,
+ usage: Usage = ...,
+ provider_data: dict[str, Any] | None = ...,
+ ) -> None: ...
+ # END generated
+
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)
@@ -2855,6 +3134,18 @@ class SpeechGenerationRequest(_PromptRequest):
format: str | None = None
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str,
+ prompt: str,
+ voice: str | None = ...,
+ format: str | None = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_PromptRequest.__post_init__(self)
_validate_optional_text(self.voice, field_name="voice", allow_empty=False)
@@ -2898,6 +3189,18 @@ class VideoGenerationRequest(_PromptRequest):
images: tuple[ImagePart, ...] = ()
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str,
+ prompt: str,
+ seconds: int | None = ...,
+ images: Sequence[ImagePart] = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_PromptRequest.__post_init__(self)
if self.seconds is not None and (
@@ -2994,12 +3297,25 @@ class LiveConfig(_ModelRequest):
output_format: AudioFormat | None = None
extensions: Extensions | None = None
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ model: str,
+ system: SystemContent | None = ...,
+ tools: Tool | Sequence[Tool] = ...,
+ voice: str | None = ...,
+ input_format: AudioFormat | None = ...,
+ output_format: AudioFormat | None = ...,
+ extensions: Extensions | None = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_ModelRequest.__post_init__(self)
- object.__setattr__(self, "tools", tuple(self.tools))
+ object.__setattr__(self, "tools", _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")
+ _require_tools("LiveConfig", self.tools)
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")
@@ -3017,6 +3333,15 @@ class LiveClientTurnEvent:
turn_complete: bool = True
type: Literal["turn"] = field(default="turn", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(
+ self,
+ parts: PromptPart | Sequence[PromptPart],
+ turn_complete: bool = ...,
+ ) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
parts = (self.parts,) if _is_part(self.parts) else tuple(self.parts)
object.__setattr__(self, "parts", parts)
@@ -3073,6 +3398,11 @@ class LiveClientToolResultEvent:
content: tuple[ToolResultContentPart, ...]
type: Literal["tool_result"] = field(default="tool_result", init=False)
+ # BEGIN generated by tools/gen_init_signatures.py: do not edit
+ if TYPE_CHECKING:
+ def __init__(self, id: str, content: Sequence[ToolResultContentPart]) -> None: ...
+ # END generated
+
def __post_init__(self) -> None:
_validate_text(self.id, field_name="LiveClientToolResultEvent.id", allow_empty=False)
object.__setattr__(self, "content", tuple(self.content))
diff --git a/dspy/_vendor/lm15/vet.py b/dspy/_vendor/lm15/vet.py
index 74333320c..75491d39f 100644
--- a/dspy/_vendor/lm15/vet.py
+++ b/dspy/_vendor/lm15/vet.py
@@ -34,6 +34,7 @@ JsonObject = dict[str, Any]
LANGUAGE = "python"
from ._version import __version__ as IMPL_VERSION
+from ._vet_managed import op_managed_run
# Parse-only ops (parse_response, replay_stream, normalize_error) construct an
# adapter but never build auth headers; the key value is irrelevant and must
@@ -96,7 +97,10 @@ def adapter_for_provider(provider: str, api_key: Any, base_url: str | None = Non
if definition.compat is not None:
# The Gemini dialect takes no compat (the router does the same).
kwargs["compat"] = definition.compat
- if definition.hosted:
+ if definition.hosted or settings:
+ # A cloud door's host settings, or a door's backend settings
+ # (client_version on the subscription doors; AUTH-10 amended
+ # 2026-09-30). The shim passes exactly these and reads no environment.
kwargs["settings"] = settings
if clock is not None:
kwargs["clock"] = clock
@@ -345,6 +349,25 @@ def op_resolve_model(msg: JsonObject) -> JsonObject:
return {"provider": resolution.provider, "model": resolution.model, "source": resolution.source}
+def op_resolve_openai_chat_model(msg: JsonObject) -> JsonObject:
+ """PROTOCOL.md resolve_openai_chat_model: the router's
+ ``resolve_openai_chat`` (the OpenAI SDK and litellm spellings, read by
+ ``openai_chat_model_string``) over harness-supplied inputs only."""
+ from .router import LMRouter, RouterConfig
+
+ env = {str(k): str(v) for k, v in (msg.get("env") or {}).items()}
+ resolution = LMRouter(RouterConfig(env=env)).resolve_openai_chat(str(msg["model"]))
+ return {"provider": resolution.provider, "model": resolution.model, "source": resolution.source}
+
+
+def op_provider_tables(msg: JsonObject) -> JsonObject:
+ """PROTOCOL.md provider_tables (reference only): the registry, access
+ policies, compat presets and router tables, as data."""
+ from ._vet_tables import provider_tables
+
+ return provider_tables()
+
+
def op_build_models_request(msg: JsonObject) -> JsonObject:
lm = _adapter(msg)
return normalize_transport_request(lm._models_request())
@@ -588,6 +611,19 @@ def op_replay_live(msg: JsonObject) -> JsonObject:
}
+def _explained_settings(report: Any) -> JsonObject:
+ values = {name: value for name, value in report.settings if name != "error"}
+ out: JsonObject = {}
+ for name, origin in report.setting_sources:
+ if origin == "missing":
+ out[name] = {"value": None, "from": None}
+ elif origin.startswith("unprobed:"):
+ out[name] = {"value": None, "from": origin.split(":", 1)[1], "state": "unprobed"}
+ else:
+ out[name] = {"value": values.get(name), "from": origin}
+ return out
+
+
def op_explain_auth(msg: JsonObject) -> JsonObject:
"""AUTH-7 resolution chain over harness-supplied inputs only.
@@ -625,6 +661,9 @@ def op_explain_auth(msg: JsonObject) -> JsonObject:
return {
"configured": report.configured,
"steps": [{"kind": step.kind, "state": step.state} for step in report.steps],
+ # PROTOCOL.md explain_auth ``settings`` (additive, 2026-09-26): each
+ # host setting's value and origin; an unprobed one has value null.
+ "settings": _explained_settings(report),
"report_text": "\n".join((report.describe(), repr(report), str(report))),
}
@@ -792,6 +831,8 @@ HANDLERS: dict[str, Callable[[JsonObject], JsonObject]] = {
"surface_dump": op_surface_dump,
"explain_auth": op_explain_auth,
"resolve_model": op_resolve_model,
+ "resolve_openai_chat_model": op_resolve_openai_chat_model,
+ "provider_tables": op_provider_tables,
"token_exchange_build": op_token_exchange_build,
"token_exchange_parse": op_token_exchange_parse,
"sigv4_sign": op_sigv4_sign,
@@ -808,6 +849,7 @@ HANDLERS: dict[str, Callable[[JsonObject], JsonObject]] = {
"batch_op_parse": op_batch_op_parse,
"cache_op_build": op_cache_op_build,
"cache_op_parse": op_cache_op_parse,
+ "managed_run": op_managed_run,
}
diff --git a/dspy/clients/engines/stream_guard.py b/dspy/clients/engines/stream_guard.py
index 9045d05a8..0d0601fc0 100644
--- a/dspy/clients/engines/stream_guard.py
+++ b/dspy/clients/engines/stream_guard.py
@@ -3,15 +3,19 @@
from dspy._vendor.lm15.errors import error_class_for_code
from dspy._vendor.lm15.types import STREAM_EVENT_CLASSES
from dspy.clients.engines.lifecycle import aclosing_stream, closing_stream
-from dspy.lm15 import StreamAssemblyError
+from dspy.lm15 import AuthOperationError, StreamAssemblyError
def error_from_event(event, *, provider=None):
http = event.error.http_response
- return error_class_for_code(event.error.code)(
+ error_class = error_class_for_code(event.error.code)
+ # ErrorDetail carries no managed-auth lifecycle state. Do not invent a
+ # specific login failure or claim that an operation did not commit.
+ kwargs = {"reason": "indeterminate", "stage": "dispatch", "commit_state": "unknown"} if error_class is AuthOperationError else {}
+ return error_class(
event.error.message, provider=provider, provider_code=event.error.provider_code,
request_id=http.get("request_id"), retry_after=http.get("retry_after"),
- rate_limit_headers=http.get("rate_limit_headers"),
+ rate_limit_headers=http.get("rate_limit_headers"), **kwargs,
)
diff --git a/dspy/clients/errors.py b/dspy/clients/errors.py
index 92ab8703e..897e39dcf 100644
--- a/dspy/clients/errors.py
+++ b/dspy/clients/errors.py
@@ -46,7 +46,6 @@ ERROR_MAPPING = (
(lm15.CapabilityError, LMUnsupportedFeatureError),
(lm15.NotConfiguredError, LMNotConfiguredError),
(lm15.ConfigurationError, LMConfigurationError),
- (lm15.ToolDerivationError, LMConfigurationError),
(lm15.TransportError, LMTransportError),
(lm15.ProviderError, LMProviderError),
)
diff --git a/dspy/clients/model_metadata/__init__.py b/dspy/clients/model_metadata/__init__.py
index f1ca818dc..cb2980c8e 100644
--- a/dspy/clients/model_metadata/__init__.py
+++ b/dspy/clients/model_metadata/__init__.py
@@ -102,6 +102,7 @@ def _provider_names(provider):
"moonshotai-responses": ("moonshot", "moonshotai"),
"moonshotai-anthropic": ("moonshot", "moonshotai"),
"vllm": ("hosted_vllm", "vllm"),
+ "fireworks": ("fireworks_ai",), "together": ("together_ai",),
}.get(provider, (provider,))
diff --git a/tests/clients/test_engine_errors.py b/tests/clients/test_engine_errors.py
index e395cfbfd..f16e00371 100644
--- a/tests/clients/test_engine_errors.py
+++ b/tests/clients/test_engine_errors.py
@@ -21,6 +21,7 @@ from dspy.utils.callback import BaseCallback
EXPECTED = {
lm15.LM15Error: dspy.LMUnexpectedError,
+ lm15.AuthOperationError: dspy.LMUnexpectedError,
lm15.TransportError: dspy.LMTransportError,
lm15.LockTimeoutError: dspy.LMLockTimeoutError,
lm15.StreamAssemblyError: dspy.LMStreamAssemblyError,
@@ -40,7 +41,6 @@ EXPECTED = {
lm15.UnsupportedModelError: dspy.LMUnsupportedModelError,
lm15.TimeoutError: dspy.LMTimeoutError,
lm15.ServerError: dspy.LMServerError,
- lm15.ToolDerivationError: dspy.LMConfigurationError,
CredentialLockTimeout: dspy.LMLockTimeoutError,
DeviceCodeExpiredError: dspy.LMAuthError,
MissingCredentialError: dspy.LMNotConfiguredError,
@@ -96,8 +96,9 @@ def test_all_exported_canonical_error_classes_have_an_explicit_policy():
@pytest.mark.parametrize("streaming", [False, True])
@pytest.mark.parametrize("source,target", EXPECTED.items(), ids=[cls.__name__ for cls in EXPECTED])
async def test_public_projection_preserves_metadata_and_cause(source, target, asynchronous, streaming):
+ kwargs = {"reason": "login_required"} if source is lm15.AuthOperationError else {}
original = source("original failure", provider="fake", provider_code="code", status=429,
- request_id="request-1", retry_after=7.0)
+ request_id="request-1", retry_after=7.0, **kwargs)
engine = Engine(original)
errors = []
@@ -302,6 +303,11 @@ def test_every_canonical_error_event_uses_the_same_projection(code):
canonical = error_from_event(event, provider="fake")
assert canonical.code == code
assert type(wrap_error(canonical, model="custom")) is EXPECTED[error_class_for_code(code)]
+ if code == "auth_operation":
+ assert isinstance(canonical, lm15.AuthOperationError)
+ assert canonical.reason == "indeterminate"
+ assert canonical.stage == "dispatch"
+ assert canonical.commit_state == "unknown"
@pytest.mark.asyncio
diff --git a/tests/clients/test_lm15_rc3_integration.py b/tests/clients/test_lm15_rc3_integration.py
index ba2a347ce..9ba2aa10a 100644
--- a/tests/clients/test_lm15_rc3_integration.py
+++ b/tests/clients/test_lm15_rc3_integration.py
@@ -217,6 +217,51 @@ async def test_judgment_response_preserves_json_prediction_and_typed_value(async
assert CallResult.load(CallResult.native(response).dump()).responses[0] == response
[email protected]("asynchronous", [False, True])
+async def test_typesafe_image_judgments_preserve_media_and_cached_answers(asynchronous, monkeypatch, tmp_path):
+ import json
+
+ import dspy.clients.execution as execution
+ from dspy._vendor.lm15.testing import FakeTransport
+ from tests.clients.test_lm_engine_execution import DualResponse
+
+ path = tmp_path / "first.png"
+ path.write_bytes(b"\x89PNG\r\n\x1a\n")
+ transport = FakeTransport([DualResponse(200, json.dumps({
+ "model": "jev-1.13.0", "answers": {"same": {"type": "noul", "noul": 0.2}},
+ "usage": {"input_tokens": 42, "output_tokens": 3},
+ }).encode())])
+ monkeypatch.setattr(execution, "RouterConfig", lambda **kwargs: lm15.RouterConfig(
+ **{**kwargs, "transport": transport},
+ ))
+ lm = dspy.LM("typesafe:jev-latest", engine="lm15", api_key="fake", num_retries=0)
+ request = lm15.Request(model=lm.model, messages=(lm15.Message.user([
+ "Compare these pictures.", lm15.ImagePart(path=path), lm15.data({"label": "second"}),
+ lm15.ImagePart(data="/9j/4AAQ", media_type="image/jpeg"),
+ ]),), config=lm15.Config(response_format=lm15.judgments(same=lm15.yes_no("Are they the same?"))))
+ try:
+ response = await invoke(lm, asynchronous, request)
+ cached = await invoke(lm, asynchronous, request)
+ assert len(transport.requests) == 1
+ sent, = transport.requests
+ wire = json.loads(sent.body)
+ assert wire["state"] == ["Compare these pictures.", "<lm15-image-1>", {"label": "second"}, "<lm15-image-2>"]
+ assert wire["assets"] == {
+ "<lm15-image-1>": {"type": "image", "format": "png", "data_base64": "iVBORw0KGgo="},
+ "<lm15-image-2>": {"type": "image", "format": "jpg", "data_base64": "/9j/4AAQ"},
+ }
+ assert dict(sent.headers)["TypeSafe-Danger-Zone-Images"] == "true"
+ for result in (response, cached):
+ assert isinstance(result.message.parts[0], lm15.DataPart)
+ assert result.data == {"same": False}
+ assert result.probabilities == {"same": {"true": 0.2, "false": 0.8}}
+ assert result.method == "provider_classification"
+ assert lm.history[-1]["usage"] == {}
+ finally:
+ await lm.aclose()
+
+
@pytest.mark.asyncio
@pytest.mark.parametrize("asynchronous", [False, True])
@pytest.mark.parametrize("streaming", [False, True])
diff --git a/tests/clients/test_native_metadata.py b/tests/clients/test_native_metadata.py
index 17a106a2e..01135cbbf 100644
--- a/tests/clients/test_native_metadata.py
+++ b/tests/clients/test_native_metadata.py
@@ -164,3 +164,20 @@ def test_family_rule_provider_limits_only_known_entries(monkeypatch):
unknown = metadata.model_info("proxy", "gpt-unlisted")
assert unknown["supports_reasoning"] is True
assert "input_cost_per_token" not in unknown
+
+
[email protected]("provider,namespace", [("fireworks", "fireworks_ai"), ("together", "together_ai")])
+def test_native_inference_hosts_use_their_metadata_namespace(monkeypatch, provider, namespace):
+ monkeypatch.setattr(metadata, "_data", {
+ f"{namespace}/vendor/model": {
+ "litellm_provider": namespace, "supports_function_calling": True,
+ "input_cost_per_token": 2e-6, "output_cost_per_token": 7e-6,
+ },
+ "vendor/model": {"litellm_provider": "openai", "input_cost_per_token": 99},
+ })
+ lm = dspy.LM(f"{namespace}/vendor/model", engine="lm15", api_key="test")
+ assert lm.supports_function_calling
+ cost, details = estimate_cost(answer("vendor/model", input_tokens=3, output_tokens=5),
+ provider=provider, requested_model="vendor/model")
+ assert cost == pytest.approx(41e-6)
+ assert details["provider"] == provider
diff --git a/tests/clients/test_registered_providers.py b/tests/clients/test_registered_providers.py
index 44d5ff58e..90e29e7b1 100644
--- a/tests/clients/test_registered_providers.py
+++ b/tests/clients/test_registered_providers.py
@@ -66,11 +66,11 @@ def server():
worker.join()
-def _definition(base_url, provider="fireworks", aliases=("fireworks-ai",), headers=(), auth_scheme=("bearer",), **compat):
+def _definition(base_url, provider="private-fireworks", aliases=("private-fireworks-ai",), headers=(), auth_scheme=("bearer",), **compat):
compat.setdefault("max_tokens_field", "max_tokens")
return ProviderDefinition.chat(
AccessPolicy(provider=provider, supports=EndpointSupport(complete=True, stream=True, models=True),
- auth_modes=("bearer",), auth_scheme=auth_scheme, env_keys=("FIREWORKS_API_KEY",),
+ auth_modes=("bearer",), auth_scheme=auth_scheme, env_keys=("PRIVATE_FIREWORKS_API_KEY",),
base_url=base_url, headers=tuple(headers)),
compat=OpenAIChatCompat(**compat),
aliases=aliases, note="Fireworks (test)",
@@ -81,7 +81,7 @@ def _definition(base_url, provider="fireworks", aliases=("fireworks-ai",), heade
def clean_registry(monkeypatch):
import dspy.clients.model_metadata as metadata
- for name in ("FIREWORKS_API_KEY", "FIREWORKS_API_BASE", "FIREWORKS_BASE_URL", "OPENAI_API_KEY"):
+ for name in ("PRIVATE_FIREWORKS_API_KEY", "PRIVATE_FIREWORKS_API_BASE", "PRIVATE_FIREWORKS_BASE_URL", "OPENAI_API_KEY"):
monkeypatch.delenv(name, raising=False)
# Capabilities and prices come from the bundled metadata snapshot, not
# from whatever the live LiteLLM map says today (or whichever a sibling
@@ -134,15 +134,15 @@ def test_register_is_idempotent_and_replace_is_explicit():
register_provider(definition, metadata_namespaces=("fireworks_ai",)) # statements are part of it
replaced = register_provider(_definition("https://other.test/v1"), replace=True)
assert registered_providers() == (replaced,)
- unregister_provider("fireworks")
+ unregister_provider("private-fireworks")
assert registered_providers() == ()
- unregister_provider("fireworks") # unknown: ignored
+ unregister_provider("private-fireworks") # unknown: ignored
def test_arguments_are_type_checked():
definition = _definition("https://x.test/v1")
with pytest.raises(TypeError, match="ProviderDefinition"):
- register_provider("fireworks")
+ register_provider("private-fireworks")
with pytest.raises(TypeError, match="ModelSupport"):
register_provider(definition, supports={"function_calling": True})
with pytest.raises(TypeError, match="models= maps"):
@@ -154,12 +154,12 @@ def test_arguments_are_type_checked():
def test_spellings_lm15_or_litellm_already_use_are_refused():
- for taken in ("groq", "ollama-chat"):
+ for taken in ("groq", "ollama-chat", "fireworks"):
with pytest.raises(Exception, match="already names"):
register_provider(_definition("https://x.test/v1", provider="new-door", aliases=(taken,)))
register_provider(_definition("https://x.test/v1"))
- with pytest.raises(ValueError, match=r"spells \['fireworks-ai'\] like the registered provider 'fireworks'"):
- register_provider(_definition("https://x.test/v1", provider="other", aliases=("fireworks-ai",)))
+ with pytest.raises(ValueError, match=r"spells \['private-fireworks-ai'\] like the registered provider 'private-fireworks'"):
+ register_provider(_definition("https://x.test/v1", provider="other", aliases=("private-fireworks-ai",)))
# ─── one binding per LM ───────────────────────────────────────────────
@@ -167,9 +167,9 @@ def test_spellings_lm15_or_litellm_already_use_are_refused():
def test_an_lm_binds_the_registrations_present_at_construction(server):
base, _ = server
- before = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False)
+ before = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False)
register_provider(_definition(base))
- after = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ after = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
assert not select_backend(before).native # bound nothing; stays as it was
assert select_backend(after).native
assert after("hi") == ["Paris"]
@@ -180,7 +180,7 @@ def test_an_lm_binds_the_registrations_present_at_construction(server):
def test_replacing_a_registration_never_splits_an_lm(server):
base, _ = server
register_provider(_definition(base, max_tokens_field="max_tokens"))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
call = prepare(lm, "hi", None, {"max_tokens": 7})
sync_engine, _, _ = _select_engine(lm, call, False)
register_provider(_definition("http://127.0.0.1:9/v1", max_tokens_field="max_completion_tokens"), replace=True)
@@ -196,7 +196,7 @@ def test_replacing_a_registration_never_splits_an_lm(server):
assert asyncio.run(async_engine()) == base
assert lm("hi") == ["Paris"] # still the address it was built with
- fresh = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ fresh = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
assert select_backend(fresh).resolution.compat.max_tokens_field == "max_completion_tokens"
lm.close()
@@ -204,13 +204,13 @@ def test_replacing_a_registration_never_splits_an_lm(server):
# ─── routing through dspy.LM ──────────────────────────────────────────
[email protected]("prefix", ["fireworks", "fireworks_ai", "fireworks-ai"])
[email protected]("prefix", ["private-fireworks", "private_fireworks_ai", "private-fireworks-ai"])
def test_registered_provider_routes_natively_with_the_lm_key(server, prefix):
base, seen = server
register_provider(_definition(base))
lm = dspy.LM(f"{prefix}/{MODEL}", api_key="lm-key", cache=False, num_retries=0)
selection = select_backend(lm)
- assert selection.native and selection.resolution.provider == "fireworks" and selection.resolution.declared
+ assert selection.native and selection.resolution.provider == "private-fireworks" and selection.resolution.declared
assert lm("capital of France?") == ["Paris"]
assert seen[-1]["auth"] == "Bearer lm-key"
assert seen[-1]["path"] == "/v1/chat/completions"
@@ -221,19 +221,19 @@ def test_registered_provider_routes_natively_with_the_lm_key(server, prefix):
def test_env_key_and_client_settings_are_honored(server, monkeypatch):
base, seen = server
register_provider(_definition(base))
- monkeypatch.setenv("FIREWORKS_API_KEY", "env-key")
- lm = dspy.LM(f"fireworks/{MODEL}", cache=False, num_retries=0, max_tokens=9, timeout=5)
+ monkeypatch.setenv("PRIVATE_FIREWORKS_API_KEY", "env-key")
+ lm = dspy.LM(f"private-fireworks/{MODEL}", cache=False, num_retries=0, max_tokens=9, timeout=5)
assert select_backend(lm).native
assert lm("hi") == ["Paris"]
assert seen[-1]["auth"] == "Bearer env-key"
assert seen[-1]["body"]["max_tokens"] == 9 # the declared compat's spelling
lm.close()
- moved = dspy.LM(f"fireworks/{MODEL}", api_base="http://127.0.0.1:9/v1", cache=False, num_retries=0)
+ moved = dspy.LM(f"private-fireworks/{MODEL}", api_base="http://127.0.0.1:9/v1", cache=False, num_retries=0)
with pytest.raises(dspy.LMError):
moved("hi") # api_base moves the call; a closed port fails, never a silent success elsewhere
- monkeypatch.delenv("FIREWORKS_API_KEY")
- with pytest.raises(dspy.LMError, match="FIREWORKS_API_KEY"):
- dspy.LM(f"fireworks/{MODEL}", cache=False, num_retries=0)("hi")
+ monkeypatch.delenv("PRIVATE_FIREWORKS_API_KEY")
+ with pytest.raises(dspy.LMError, match="PRIVATE_FIREWORKS_API_KEY"):
+ dspy.LM(f"private-fireworks/{MODEL}", cache=False, num_retries=0)("hi")
def test_a_declaration_beats_the_ambient_gateway_variable(server, monkeypatch):
@@ -241,8 +241,8 @@ def test_a_declaration_beats_the_ambient_gateway_variable(server, monkeypatch):
# providers (legacy gateways). A declaration states its address itself.
base, seen = server
register_provider(_definition(base))
- monkeypatch.setenv("FIREWORKS_API_BASE", "http://127.0.0.1:9/v1")
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ monkeypatch.setenv("PRIVATE_FIREWORKS_API_BASE", "http://127.0.0.1:9/v1")
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
assert select_backend(lm).native
assert lm("hi") == ["Paris"] and seen[-1]["path"] == "/v1/chat/completions"
lm.close()
@@ -252,25 +252,25 @@ def test_a_declaration_beats_the_ambient_gateway_variable(server, monkeypatch):
async def test_async_path(server):
base, seen = server
register_provider(_definition(base))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="lm-key", cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="lm-key", cache=False, num_retries=0)
assert await lm.acall("hi") == ["Paris"]
assert seen[-1]["auth"] == "Bearer lm-key"
await lm.aclose()
def test_unregistered_prefix_is_not_native():
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False)
assert not select_backend(lm).native
# ─── the fallback keeps the declared connection ───────────────────────
[email protected]("prefix", ["fireworks", "fireworks_ai"])
[email protected]("prefix", ["private-fireworks", "private_fireworks_ai"])
def test_fallback_reaches_the_declared_address_with_the_declared_credential(litellm_stub, prefix, monkeypatch):
# extra_headers is a client setting only LiteLLM carries. The route it
# takes is LiteLLM's generic OpenAI-compatible door at the DECLARED
- # address, not LiteLLM's own idea of "fireworks_ai".
+ # address, not LiteLLM's own idea of the private provider.
register_provider(_definition("https://private-gateway.test/v1", headers=(("X-Gateway", "tenant-1"),)))
lm = dspy.LM(f"{prefix}/{MODEL}", api_key="private-key", extra_headers={"X-Test": "1"}, cache=False, num_retries=0)
selection = select_backend(lm)
@@ -287,18 +287,18 @@ def test_fallback_reaches_the_declared_address_with_the_declared_credential(lite
def test_fallback_reads_the_declared_key_variable_and_never_an_ambient_openai_key(litellm_stub, monkeypatch):
register_provider(_definition("https://private-gateway.test/v1"))
monkeypatch.setenv("OPENAI_API_KEY", "sk-openai-must-not-leak")
- lm = dspy.LM(f"fireworks/{MODEL}", extra_headers={"X-Test": "1"}, cache=False, num_retries=0)
- with pytest.raises(dspy.LMError, match="FIREWORKS_API_KEY") as info:
+ lm = dspy.LM(f"private-fireworks/{MODEL}", extra_headers={"X-Test": "1"}, cache=False, num_retries=0)
+ with pytest.raises(dspy.LMError, match="PRIVATE_FIREWORKS_API_KEY") as info:
lm("hi")
assert not litellm_stub and "sk-openai" not in str(info.value)
- monkeypatch.setenv("FIREWORKS_API_KEY", "env-key")
+ monkeypatch.setenv("PRIVATE_FIREWORKS_API_KEY", "env-key")
assert "Paris" in lm("hi")[0]
assert litellm_stub[-1]["api_key"] == "env-key"
def test_fallback_under_engine_litellm_takes_the_same_route(litellm_stub):
register_provider(_definition("https://private-gateway.test/v1"))
- lm = dspy.LM(f"fireworks_ai/{MODEL}", engine="litellm", api_key="k", cache=False, num_retries=0)
+ lm = dspy.LM(f"private_fireworks_ai/{MODEL}", engine="litellm", api_key="k", cache=False, num_retries=0)
assert "Paris" in lm("hi")[0]
assert litellm_stub[-1]["model"] == f"openai/{MODEL}"
assert litellm_stub[-1]["api_base"] == "https://private-gateway.test/v1"
@@ -307,7 +307,7 @@ def test_fallback_under_engine_litellm_takes_the_same_route(litellm_stub):
@pytest.mark.asyncio
async def test_async_fallback_keeps_the_connection_too(litellm_stub):
register_provider(_definition("https://private-gateway.test/v1"))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
assert "Paris" in (await lm.acall("hi"))[0]
assert litellm_stub[-1]["api_base"] == "https://private-gateway.test/v1"
@@ -318,7 +318,7 @@ def test_capabilities_on_the_fallback_route_come_from_the_declaration(litellm_st
# does not know. The whole program runs.
register_provider(_definition("https://private-gateway.test/v1"),
supports=ModelSupport(function_calling=True, response_schema=True))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
assert not select_backend(lm).native
assert lm.supports_function_calling and lm.supports_response_schema and "tools" in lm.supported_params
with dspy.context(lm=lm, adapter=dspy.ChatAdapter(use_json_adapter_fallback=False)):
@@ -363,7 +363,7 @@ def test_fallback_resolves_a_callable_credential_per_call(litellm_stub):
# LiteLLM the string (greptile on dspy#10442).
register_provider(_definition("https://private-gateway.test/v1"))
tokens = iter(["token-1", "token-2"])
- lm = dspy.LM(f"fireworks/{MODEL}", api_key=lambda: next(tokens), extra_headers={"X": "1"}, cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key=lambda: next(tokens), extra_headers={"X": "1"}, cache=False, num_retries=0)
lm("hi")
lm("hi again")
assert [call["api_key"] for call in litellm_stub[-2:]] == ["token-1", "token-2"]
@@ -375,14 +375,14 @@ async def test_fallback_is_still_the_declared_provider_for_pricing(litellm_stub)
# declaration's namespaces on every path, never from LiteLLM's reading
# of the generic door's model string (greptile on dspy#10442).
register_provider(_definition("https://private-gateway.test/v1"), metadata_namespaces=("fireworks_ai",))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", extra_headers={"X": "1"}, cache=False, num_retries=0)
lm("hi") # legacy body path
lm(dspy.lm15.Request(model=lm.model, messages=(dspy.lm15.Message.user("hi"),))) # canonical path
await lm.acall("hi") # async legacy path
costs = [entry["cost"] for entry in lm.history[-3:]]
assert all(cost is not None and cost > 0 for cost in costs) and len(set(costs)) == 1
for entry in lm.history[-3:]:
- assert entry["cost_details"]["provider"] == "fireworks"
+ assert entry["cost_details"]["provider"] == "private-fireworks"
assert entry["cost_details"]["metadata"]["namespaces"] == ["fireworks_ai"]
# A colliding name on a gateway with no namespace is unknown, not OpenAI's price.
register_provider(_definition("https://private-gateway.test/v1", provider="gw", aliases=()))
@@ -400,7 +400,7 @@ def test_a_declared_refusal_is_final_under_auto(litellm_stub, server):
# is not a refusal and never leaves the native route.)
base, seen = server
register_provider(_definition(base, thinking_format="none", json_schema="reject"))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
with pytest.raises(dspy.LMUnsupportedFeatureError):
lm("hi", reasoning_effort="low")
assert not litellm_stub
@@ -413,7 +413,7 @@ def test_engine_lm15_refuses_client_settings_it_cannot_carry(server):
base, _ = server
register_provider(_definition(base))
with pytest.raises(Exception, match="require the LiteLLM"):
- select_backend(dspy.LM(f"fireworks/{MODEL}", engine="lm15", api_key="k", extra_headers={"X": "1"}))
+ select_backend(dspy.LM(f"private-fireworks/{MODEL}", engine="lm15", api_key="k", extra_headers={"X": "1"}))
# ─── aliases grant a spelling, nothing else ───────────────────────────
@@ -421,8 +421,8 @@ def test_engine_lm15_refuses_client_settings_it_cannot_carry(server):
def test_an_alias_grants_no_metadata(server):
base, _ = server
- register_provider(_definition(base)) # alias fireworks-ai, no namespaces
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ register_provider(_definition(base)) # alias private-fireworks-ai, no namespaces
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
assert not (lm.supports_function_calling or lm.supports_reasoning or lm.supports_response_schema)
lm("hi")
assert lm.history[-1]["cost"] is None
@@ -433,13 +433,13 @@ def test_an_alias_grants_no_metadata(server):
def test_metadata_namespaces_are_an_explicit_opt_in(server):
base, _ = server
register_provider(_definition(base), metadata_namespaces=("fireworks_ai",))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False, num_retries=0)
assert lm.supports_function_calling and lm.supports_reasoning and lm.supports_response_schema
assert {"reasoning_effort", "max_tokens", "response_format", "tools"} <= lm.supported_params
lm("hi")
entry = lm.history[-1]
assert entry["cost"] is not None and entry["cost_details"]["kind"] == "estimate"
- assert entry["cost_details"]["provider"] == "fireworks"
+ assert entry["cost_details"]["provider"] == "private-fireworks"
assert entry["cost_details"]["metadata"]["namespaces"] == ["fireworks_ai"]
lm.close()
@@ -450,14 +450,14 @@ def test_stated_support_fills_what_no_snapshot_says(server):
_definition(base), supports=ModelSupport(function_calling=True),
models={"private-v1": ModelSupport(response_schema=True, function_calling=False)},
)
- default = dspy.LM("fireworks/private-v2", api_key="k")
+ default = dspy.LM("private-fireworks/private-v2", api_key="k")
assert default.supports_function_calling and not default.supports_response_schema and not default.supports_reasoning
assert "tools" in default.supported_params
- specific = dspy.LM("fireworks/private-v1", api_key="k")
+ specific = dspy.LM("private-fireworks/private-v1", api_key="k")
assert not specific.supports_function_calling and specific.supports_response_schema
assert "response_format" in specific.supported_params and "tools" not in specific.supported_params
# A statement never prices anything.
- specific = dspy.LM("fireworks/private-v1", api_key="k", cache=False, num_retries=0)
+ specific = dspy.LM("private-fireworks/private-v1", api_key="k", cache=False, num_retries=0)
specific("hi")
assert specific.history[-1]["cost"] is None
specific.close()
@@ -469,15 +469,15 @@ def test_a_snapshot_entry_is_more_specific_than_a_statement(server):
# says the provider does not. The per-model fact wins.
register_provider(_definition(base), metadata_namespaces=("fireworks_ai",),
supports=ModelSupport(function_calling=False))
- assert dspy.LM(f"fireworks/{MODEL}", api_key="k").supports_function_calling
- assert not dspy.LM("fireworks/private-v9", api_key="k").supports_function_calling
+ assert dspy.LM(f"private-fireworks/{MODEL}", api_key="k").supports_function_calling
+ assert not dspy.LM("private-fireworks/private-v9", api_key="k").supports_function_calling
def test_compat_object_shapes_capabilities(server):
base, _ = server
register_provider(_definition(base, json_schema="reject", thinking_format="none"),
supports=ModelSupport(function_calling=True, reasoning=True, response_schema=True))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k")
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k")
assert lm.supports_function_calling
assert not lm.supports_response_schema and not lm.supports_reasoning # the wire cannot carry them
assert "reasoning_effort" not in lm.supported_params
@@ -489,11 +489,11 @@ def test_compat_object_shapes_capabilities(server):
def test_state_is_the_model_string(server):
base, _ = server
register_provider(_definition(base))
- state = dspy.LM(f"fireworks/{MODEL}", api_key="k").dump_state()
+ state = dspy.LM(f"private-fireworks/{MODEL}", api_key="k").dump_state()
json.dumps(state)
assert "engine" not in state and "api_key" not in state and "_providers" not in state
loaded = dspy.LM.load_state(state)
- assert loaded.model == f"fireworks/{MODEL}" and select_backend(loaded).native # bound at load time
+ assert loaded.model == f"private-fireworks/{MODEL}" and select_backend(loaded).native # bound at load time
def test_pickled_lm_keeps_its_binding(server):
@@ -501,7 +501,7 @@ def test_pickled_lm_keeps_its_binding(server):
base, _ = server
register_provider(_definition(base))
- lm = dspy.LM(f"fireworks/{MODEL}", api_key="k", cache=False)
- unregister_provider("fireworks")
+ lm = dspy.LM(f"private-fireworks/{MODEL}", api_key="k", cache=False)
+ unregister_provider("private-fireworks")
restored = pickle.loads(pickle.dumps(lm))
assert select_backend(restored).native and restored._providers == lm._providers
diff --git a/tests/test_vendored_lm15.py b/tests/test_vendored_lm15.py
index 95eb7ad44..ae84bb639 100644
--- a/tests/test_vendored_lm15.py
+++ b/tests/test_vendored_lm15.py
@@ -22,6 +22,10 @@ def test_public_exports_are_the_vendored_objects():
assert lm15.__all__[: len(vendored.__all__)] == vendored.__all__
for name in vendored.__all__:
assert getattr(lm15, name) is getattr(vendored, name)
+ # Login descriptors must not collide with the provider implementation package.
+ assert lm15.login_providers.meta.id == "meta"
+ assert lm15.login_providers.xai.id == "xai"
+ assert lm15.providers.XaiLM is lm15.XaiLM
assert set(lm15.__all__) - set(vendored.__all__) == {
"AnthropicCompat", "ModelSupport", "OpenAIChatCompat", "OpenAIResponsesCompat", "ProviderDefinition",
"RegisteredProvider", "register_provider", "registered_providers", "unregister_provider",