agentshim 0.17.0__tar.gz → 0.18.0__tar.gz

{agentshim-0.17.0 → agentshim-0.18.0}/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.18.0 (2026-10-16)
+
+### Added
+
+- `context_window(provider, model)` and `model_spec(provider, model)`: a model's context
+  window in tokens from a static, versioned table (`ModelSpec`, `ModelTable`,
+  `default_models()`), each entry citing the vendor page it was read from. Covers the
+  Claude 5 family (`claude-fable-5-1`, `claude-opus-5-5`, `claude-sonnet-5-5`,
+  `claude-haiku-5-5`, all 1M) and current OpenAI models. An unknown model, or a
+  bracketed variant, returns `None`; the lookup never matches by prefix.
+- `ProviderProfile.models`: the model ids a provider's CLI is known to run, the default
+  first, and `ProviderProfile.default_model`. Claude, Codex and opencode declare theirs.
+
 ## 0.17.0 (2026-10-15)
 
 ### Added

{agentshim-0.17.0 → agentshim-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentshim
-Version: 0.17.0
+Version: 0.18.0
 Summary: Provider-agnostic coding-agent CLI shims
 License-Expression: MIT
 License-File: LICENSE

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/__init__.py

@@ -57,6 +57,8 @@ from .core import (
     McpServer,
     McpTransport,
     ModelPricing,
+    ModelSpec,
+    ModelTable,
     NativeMode,
     NativePermissions,
     NoopInstallation,
@@ -124,13 +126,16 @@ from .core import (
     UsageReport,
     compact_json,
     compose_event_handlers,
+    context_window,
     cost_usd,
+    default_models,
     default_pricing,
     dialect_problems,
     host_auth_plan,
     install_config_file,
     interactive_env,
     materialize,
+    model_spec,
     normalize,
     normalized_usage,
     parse_json_object,
@@ -171,7 +176,7 @@ from .providers.opencode import OpencodeProvider
 from .runtime import Agent
 from .session import Session, Turn, TurnTicket, map_mcp_servers
 
-__version__ = "0.17.0"
+__version__ = "0.18.0"
 
 __all__ = [
     "Agent",
@@ -244,6 +249,8 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "ModelSpec",
+    "ModelTable",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -327,7 +334,9 @@ __all__ = [
     "compact_json",
     "compose_event_handlers",
     "confine",
+    "context_window",
     "cost_usd",
+    "default_models",
     "default_pricing",
     "dialect_problems",
     "get_provider",
@@ -336,6 +345,7 @@ __all__ = [
     "interactive_env",
     "map_mcp_servers",
     "materialize",
+    "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/core/__init__.py

@@ -95,6 +95,7 @@ from .mcp import (
     StdioMcpServer,
     install_config_file,
 )
+from .models import ModelSpec, ModelTable, context_window, default_models, model_spec
 from .permissions import ApprovalPolicy, NativeMode, NativePermissions
 from .pricing import ModelPricing, PricingTable, cost_usd, default_pricing, price_for
 from .profile import (
@@ -175,6 +176,8 @@ __all__ = [
     "McpServer",
     "McpTransport",
     "ModelPricing",
+    "ModelSpec",
+    "ModelTable",
     "NativeMode",
     "NativePermissions",
     "NoRunningTurnError",
@@ -242,13 +245,16 @@ __all__ = [
     "UsageReport",
     "compact_json",
     "compose_event_handlers",
+    "context_window",
     "cost_usd",
+    "default_models",
     "default_pricing",
     "dialect_problems",
     "host_auth_plan",
     "install_config_file",
     "interactive_env",
     "materialize",
+    "model_spec",
     "normalize",
     "normalized_usage",
     "parse_json_object",

agentshim-0.18.0/agentshim/core/models.py

@@ -0,0 +1,247 @@
+"""Static, versioned per-model facts: each model's context window and where it was read.
+
+The table is data: one :class:`ModelSpec` per ``(vendor, model)``, each with
+the official page its numbers were read from and the date they were checked,
+and a table-level ``version`` and ``last_updated``. It is keyed by vendor, the
+same way as the pricing table, because a context window belongs to the model,
+whichever CLI runs it.
+
+A lookup of a model the table does not know returns ``None``: an unknown
+window is never guessed from a similar name, a prefix or a model family. A
+bracketed variant (``claude-opus-5-5[1m]``) also returns ``None``, because a
+variant may change the window. Callers pin or extend assumptions by passing
+their own :class:`ModelTable` (see :meth:`ModelTable.with_entries`).
+
+Which models a provider CLI is known to run, and which of them is its
+default, is per-provider data on ``ProviderProfile.models``.
+
+Updating the table is described in ``docs/models.md``.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING, cast
+
+from agentshim.core.pricing import PROVIDER_VENDORS
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+_DATE_SUFFIX = re.compile(r"-\d{8}$")
+
+OPENAI_MODELS_URL = "https://developers.openai.com/api/docs/models"
+ANTHROPIC_CONTEXT_WINDOWS_URL = (
+    "https://platform.claude.com/docs/en/build-with-claude/context-windows"
+)
+
+
+@dataclass(frozen=True)
+class ModelSpec:
+    """One model's context window, with where and when it was read.
+
+    Attributes:
+        vendor: Who serves the model (``"openai"``, ``"anthropic"``).
+        model: The model id as the vendor names it.
+        context_window: The model's context window in tokens (input and
+            output together), at the vendor's default for that id.
+        source: URL of the official page the number was read from.
+        checked: Date the number was last checked against ``source``.
+    """
+
+    vendor: str
+    model: str
+    context_window: int
+    source: str
+    checked: dt.date
+
+    def __post_init__(self) -> None:
+        """Reject a missing name, source or date, and a window that is not a positive int."""
+        for name in ("vendor", "model"):
+            value: object = getattr(self, name)
+            if not isinstance(value, str) or not value.strip():
+                msg = f"{name} must be a non-empty string"
+                raise ValueError(msg)
+        source = cast("object", self.source)
+        if not isinstance(source, str) or not source.startswith("https://"):
+            msg = f"{self.vendor}/{self.model}: source must be an https:// URL"
+            raise ValueError(msg)
+        checked = cast("object", self.checked)
+        if not isinstance(checked, dt.date) or isinstance(checked, dt.datetime):
+            msg = f"{self.vendor}/{self.model}: checked must be a datetime.date"
+            raise TypeError(msg)
+        window = cast("object", self.context_window)
+        if isinstance(window, bool) or not isinstance(window, int) or window <= 0:
+            msg = f"{self.vendor}/{self.model}: context_window must be a positive int"
+            raise ValueError(msg)
+
+    @property
+    def key(self) -> tuple[str, str]:
+        """The ``(vendor, model)`` this entry describes."""
+        return (self.vendor, self.model)
+
+
+@dataclass(frozen=True)
+class ModelTable:
+    """A versioned set of :class:`ModelSpec` entries.
+
+    Attributes:
+        version: Names this set of facts; change it whenever a fact changes.
+        last_updated: Date the table as a whole was last updated. No entry
+            may have been checked later.
+        entries: One entry per ``(vendor, model)``.
+    """
+
+    version: str
+    last_updated: dt.date
+    entries: tuple[ModelSpec, ...] = field(default=())
+
+    def __post_init__(self) -> None:
+        """Reject a missing version, duplicate keys, and entries checked after ``last_updated``."""
+        version = cast("object", self.version)
+        if not isinstance(version, str) or not version.strip():
+            msg = "version must be a non-empty string"
+            raise ValueError(msg)
+        object.__setattr__(self, "entries", tuple(self.entries))
+        seen: set[tuple[str, str]] = set()
+        for entry in self.entries:
+            if not isinstance(cast("object", entry), ModelSpec):
+                msg = f"entries must be ModelSpec, got {entry!r}"
+                raise TypeError(msg)
+            if entry.key in seen:
+                msg = f"duplicate model entry for {entry.vendor}/{entry.model}"
+                raise ValueError(msg)
+            seen.add(entry.key)
+            if entry.checked > self.last_updated:
+                msg = (
+                    f"{entry.vendor}/{entry.model} was checked {entry.checked}, "
+                    f"after the table's last_updated {self.last_updated}"
+                )
+                raise ValueError(msg)
+
+    def get(self, vendor: str, model: str) -> ModelSpec | None:
+        """The entry for exactly ``(vendor, model)``, or ``None``."""
+        for entry in self.entries:
+            if entry.key == (vendor, model):
+                return entry
+        return None
+
+    def with_entries(
+        self,
+        entries: Iterable[ModelSpec],
+        *,
+        version: str,
+        last_updated: dt.date | None = None,
+    ) -> ModelTable:
+        """A new table with *entries* added, replacing any with the same key."""
+        added = tuple(entries)
+        by_key = {entry.key: entry for entry in self.entries}
+        by_key.update({entry.key: entry for entry in added})
+        latest = max([self.last_updated, *(entry.checked for entry in added)])
+        return replace(
+            self,
+            version=version,
+            last_updated=last_updated or latest,
+            entries=tuple(by_key.values()),
+        )
+
+
+def model_spec(
+    provider: str, model: str | None, table: ModelTable | None = None
+) -> ModelSpec | None:
+    """The facts about *model* run through *provider*, or ``None`` when they are not known.
+
+    Accepts a provider name (``codex``, ``claude``) or a vendor name, and a
+    model with a ``vendor/`` prefix (opencode's ``provider/model``). Drops a
+    trailing date snapshot (``claude-haiku-4-5-20251001``). Returns ``None``
+    for a bracketed variant (``claude-opus-5-5[1m]``), for a provider that
+    runs no known vendor's models, and for any model the table lacks; it
+    never matches by prefix or family.
+    """
+    if not model:
+        return None
+    name = model.strip().lower()
+    if "[" in name:
+        return None
+    vendor = PROVIDER_VENDORS.get(provider.strip().lower())
+    if "/" in name:
+        prefix, _, rest = name.partition("/")
+        vendor = PROVIDER_VENDORS.get(prefix)
+        name = rest
+    if vendor is None or not name:
+        return None
+    return (table or DEFAULT_MODELS).get(vendor, _DATE_SUFFIX.sub("", name))
+
+
+def context_window(provider: str, model: str | None, table: ModelTable | None = None) -> int | None:
+    """*model*'s context window in tokens when run through *provider*, or ``None`` when not known."""
+    spec = model_spec(provider, model, table)
+    return None if spec is None else spec.context_window
+
+
+def default_models() -> ModelTable:
+    """The table agentshim ships (:data:`DEFAULT_MODELS`)."""
+    return DEFAULT_MODELS
+
+
+_CHECKED = dt.date(2026, 10, 16)
+
+
+def _openai(model: str, context_window: int) -> ModelSpec:
+    # Each model's page under OPENAI_MODELS_URL ("<n> context window").
+    return ModelSpec(
+        vendor="openai",
+        model=model,
+        context_window=context_window,
+        source=f"{OPENAI_MODELS_URL}/{model}",
+        checked=_CHECKED,
+    )
+
+
+def _anthropic(model: str, context_window: int) -> ModelSpec:
+    # "Context window sizes by model": the 1M models list 1M as the default
+    # with no beta header; "other Claude models ... have a 200k-token" window.
+    return ModelSpec(
+        vendor="anthropic",
+        model=model,
+        context_window=context_window,
+        source=ANTHROPIC_CONTEXT_WINDOWS_URL,
+        checked=_CHECKED,
+    )
+
+
+_ONE_MILLION = 1_000_000
+_OPENAI_1_05M = 1_050_000
+
+#: The table agentshim ships. Update it as described in ``docs/models.md``.
+#: A model whose window could not be read from its vendor's page is left out.
+DEFAULT_MODELS = ModelTable(
+    version="2026-10-16",
+    last_updated=_CHECKED,
+    entries=(
+        # OpenAI (Codex): each model page reads "1,050,000 context window".
+        _openai("gpt-6-astra", _OPENAI_1_05M),
+        _openai("gpt-6.1-sol", _OPENAI_1_05M),
+        _openai("gpt-6-sol", _OPENAI_1_05M),
+        _openai("gpt-6-luna", _OPENAI_1_05M),
+        _openai("gpt-5.6-sol", _OPENAI_1_05M),
+        _openai("gpt-5.6-terra", _OPENAI_1_05M),
+        _openai("gpt-5.6-luna", _OPENAI_1_05M),
+        _openai("gpt-5.5", _OPENAI_1_05M),
+        # Anthropic (Claude).
+        _anthropic("claude-fable-5-1", _ONE_MILLION),
+        _anthropic("claude-fable-5", _ONE_MILLION),
+        _anthropic("claude-opus-5-5", _ONE_MILLION),
+        _anthropic("claude-opus-5", _ONE_MILLION),
+        _anthropic("claude-opus-4-8", _ONE_MILLION),
+        _anthropic("claude-opus-4-7", _ONE_MILLION),
+        _anthropic("claude-opus-4-6", _ONE_MILLION),
+        _anthropic("claude-sonnet-5-5", _ONE_MILLION),
+        _anthropic("claude-sonnet-5", _ONE_MILLION),
+        _anthropic("claude-sonnet-4-6", _ONE_MILLION),
+        _anthropic("claude-haiku-5-5", _ONE_MILLION),
+        _anthropic("claude-haiku-4-5", 200_000),
+    ),
+)

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/core/profile.py

@@ -237,3 +237,13 @@ class ProviderProfile:
     #: The settings files the CLI reads at start that can change how it logs
     #: in, or ``None`` if it has none (0.17.0+).
     settings: SettingsSpec | None = None
+    #: The model ids agentshim knows this CLI runs, as its ``--model`` flag
+    #: takes them, the provider's default first (0.18.0+). Empty means
+    #: agentshim knows of none: a caller may still pass any model, at its own
+    #: risk. A model's facts (its context window) are in ``model_spec``.
+    models: tuple[str, ...] = ()
+
+    @property
+    def default_model(self) -> str | None:
+        """The model to run when a caller must name one and has none: ``models[0]``, or ``None``."""
+        return self.models[0] if self.models else None

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/providers/claude/provider.py

@@ -69,6 +69,18 @@ STRICT_MCP_FLAG = "--strict-mcp-config"
 
 PROFILE = ProviderProfile(
     name="claude",
+    # Model ids Claude Code's ``--model`` takes and agentshim has run, the
+    # default first. Context windows are in ``agentshim.core.models``.
+    models=(
+        "claude-opus-5",
+        "claude-opus-5-5",
+        "claude-fable-5-1",
+        "claude-fable-5",
+        "claude-sonnet-5-5",
+        "claude-sonnet-5",
+        "claude-haiku-5-5",
+        "claude-haiku-4-5",
+    ),
     display_name="Claude Code",
     binary="claude",
     supports_resume=True,

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/providers/codex/provider.py

@@ -73,6 +73,17 @@ _HTTP_HEADERS_UNSUPPORTED = (
 
 PROFILE = ProviderProfile(
     name="codex",
+    # Model ids Codex's ``--model`` takes and agentshim has run, the default
+    # first. Context windows are in ``agentshim.core.models``.
+    models=(
+        "gpt-5.6-sol",
+        "gpt-5.6-luna",
+        "gpt-5.6-terra",
+        "gpt-5.5",
+        "gpt-6-astra",
+        "gpt-6-sol",
+        "gpt-6-luna",
+    ),
     display_name="Codex",
     binary="codex",
     supports_resume=True,

{agentshim-0.17.0 → agentshim-0.18.0}/agentshim/providers/opencode/provider.py

@@ -47,6 +47,9 @@ _NO_WORKSPACE = "opencode installs MCP servers into <cwd>/opencode.json; the tur
 
 PROFILE = ProviderProfile(
     name="opencode",
+    # ``provider/model`` ids opencode's ``--model`` takes and agentshim has
+    # run, the default first.
+    models=("google-vertex/gemini-3-pro-preview",),
     display_name="opencode",
     binary="opencode",
     supports_resume=True,

{agentshim-0.17.0 → agentshim-0.18.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentshim"
-version = "0.17.0"
+version = "0.18.0"
 description = "Provider-agnostic coding-agent CLI shims"
 readme = "README.md"
 license = "MIT"