opencode-models 0.1.0__py3-none-any.whl

opencode_models/data.py

@@ -0,0 +1,82 @@
+"""Load opencode.ai/data per-model JSON files into normalized records.
+
+The scraper (see fetch.py) stores one JSON file per model exactly as served
+by ``https://opencode.ai/data/<lab>/<model>.json`` under ``data/opencode/``
+— the verbatim upstream layer that only ``fetch`` writes. Curated overlays
+live beside it in ``data/overrides/`` and are merged by overrides.py, never
+here. This module turns the upstream files into :class:`Model` records;
+parsing is tolerant — a model without pricing, without benchmarks, or a
+file that is not valid JSON at all must not take down a whole render.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Model:
+    """One model's identity, pricing and benchmark scores."""
+
+    model_id: str
+    name: str
+    lab: str
+    price_input: float | None
+    price_output: float | None
+    price_cached_input: float | None
+    scores: dict[str, float] = field(default_factory=dict)
+    sources: dict[str, str | None] = field(default_factory=dict)
+
+    @property
+    def slug(self) -> str:
+        """Filename-safe unique key (``deepseek/deepseek-v4-pro`` → dashes)."""
+        return self.model_id.replace("/", "-")
+
+
+def benchmark_key(b: dict) -> str:
+    """Benchmark name qualified by version when present.
+
+    Two models' "Terminal-Bench" scores are only comparable when the
+    benchmark version is the same — Fable 5's 88 on Terminal-Bench 2.1 and
+    Fable 5.1's 55.8 on 4.0 look like a regression until you see the
+    version. Entries without a version field keep the bare name.
+    """
+    name = b["name"]
+    version = b.get("version")
+    return f"{name} {version}" if version else name
+
+
+def load_model(path: Path) -> Model:
+    """Parse one scraped ``<lab>__<model>.json`` file."""
+    doc = json.loads(path.read_text())
+    m = doc["model"]
+    price = m.get("priceUsdPer1M") or {}
+    scores: dict[str, float] = {}
+    sources: dict[str, str | None] = {}
+    for b in m.get("benchmarks") or []:
+        if isinstance(b.get("score"), (int, float)):
+            scores[benchmark_key(b)] = b["score"]
+        sources[benchmark_key(b)] = b.get("source")
+    return Model(
+        model_id=m["id"],
+        name=m.get("name") or m["id"],
+        lab=m.get("lab") or m["id"].split("/")[0],
+        price_input=price.get("input"),
+        price_output=price.get("output"),
+        price_cached_input=price.get("cachedInput"),
+        scores=scores,
+        sources=sources,
+    )
+
+
+def load_models(data_dir: Path) -> list[Model]:
+    """Parse every ``*.json`` file in *data_dir*, skipping unreadable ones."""
+    models: list[Model] = []
+    for path in sorted(Path(data_dir).glob("*.json")):
+        try:
+            models.append(load_model(path))
+        except (json.JSONDecodeError, KeyError, TypeError):
+            continue
+    return models

opencode_models/fetch.py

@@ -0,0 +1,101 @@
+"""Refresh the data directory from opencode.ai.
+
+The site publishes one page per model and serves its structured data at the
+same URL with a ``.json`` suffix; the sitemap at SITEMAP_URL lists every
+page. HTTP access is an injected ``get(url) -> str`` callable so tests can
+exercise the full flow offline (see tests/test_fetch.py).
+"""
+
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from pathlib import Path
+from xml.etree import ElementTree
+
+from . import __version__
+from .availability import offered
+
+SITEMAP_URL = "https://opencode.ai/data/sitemap.xml"
+_BASE = "https://opencode.ai/data/"
+_SITEMAP_NS = "{http://www.sitemaps.org/schemas/sitemap/0.9}"
+
+
+def http_get(url: str) -> str:
+    """Real transport: plain GET with a browser-ish user agent.
+
+    Failed responses are closed before the error propagates: urlopen
+    leaves the error response open, and dropping it unclosed warns at
+    GC time. No caller reads error bodies, so nothing is lost.
+    """
+    req = urllib.request.Request(
+        url, headers={"User-Agent": f"opencode-models/{__version__}"}
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            return resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        exc.close()
+        raise
+
+
+def urls_from_sitemap(xml: str) -> list[str]:
+    """Model-page URLs from sitemap XML, skipping the root and lab indexes."""
+    root = ElementTree.fromstring(xml)
+    urls = []
+    for loc in root.iter(f"{_SITEMAP_NS}loc"):
+        text = (loc.text or "").strip()
+        # Only <scheme>://opencode.ai/data/<lab>/<model> — lab indexes and
+        # other paths have fewer segments or a different host.
+        if text.startswith(_BASE) and text.count("/") == 5:
+            urls.append(text)
+    return urls
+
+
+def _filename_for(url: str) -> str:
+    """``https://opencode.ai/data/<lab>/<model>`` → ``<lab>__<model>.json``."""
+    lab, model = url[len(_BASE) :].rsplit("/", 1)
+    return f"{lab}__{model}.json"
+
+
+def refresh(
+    data_dir: Path, get=http_get, progress=None, only: set[str] | None = None
+) -> list[str]:
+    """Download every model's JSON into *data_dir*/opencode; return names.
+
+    The upstream layer is verbatim: ``fetch`` writes only here, and the
+    curated overlays in ``data/overrides/`` are layered on at load time
+    (see overrides.py). A failed or empty download for one model is
+    skipped, not fatal — the rest of the dataset still refreshes.
+
+    *progress* is an optional ``(done, total, name)`` callback, fired
+    after every model URL is attempted (saved or skipped), so a caller
+    can show the long sequential walk instead of silence.
+
+    *only* restricts downloads to the models the plans offer (slugs or
+    ids — ``-free`` variants reaching their model, as elsewhere). Files
+    already on disk are never deleted: a model the plans dropped keeps
+    its record, so the scales it anchors do not move under the scores.
+    None downloads everything.
+    """
+    out = Path(data_dir) / "opencode"
+    out.mkdir(parents=True, exist_ok=True)
+    saved: list[str] = []
+    urls = urls_from_sitemap(get(SITEMAP_URL))
+    if only is not None:
+        urls = [u for u in urls if offered(u[len(_BASE) :], only)]
+    total = len(urls)
+    for done, url in enumerate(urls, 1):
+        try:
+            body = get(f"{url}.json")
+        except (urllib.error.URLError, OSError):
+            body = ""
+        if body.strip():
+            name = _filename_for(url)
+            (out / name).write_text(body)
+            saved.append(name)
+        else:
+            name = _filename_for(url)
+        if progress is not None:
+            progress(done, total, name)
+    return saved

opencode_models/identity.py

@@ -0,0 +1,100 @@
+"""Which model a catalog id really names.
+
+A designation is not an identity. ``meta/muse-spark-1.3`` and
+``meta/muse-spark-1.3-contributor`` are the same weights on two plans: eleven
+identical benchmark values, none differing, $1.25 in on Zen and $0.10 in on
+Go. The catalog lists them as two models, so the console showed two rows for
+one model - and two different scores, 99 and 98, because the contributor
+record happened to lack a Terminal-Bench 4.0 run its twin carried. A
+data-completeness artefact, not a difference between models.
+
+So the benchmarks merge into one model, the score is computed once, and each
+plan keeps its own priced line - which is exactly how a priced variant like
+``(Off-Peak)`` already works. What changes is that the alias has to be known
+in three places at once: the model's own record, the tier price entries keyed
+by id, and the availability record. Getting two of the three right still
+splits the model, so all three go through :func:`canonical_id`.
+
+The alias map is explicit rather than a suffix rule. ``-contributor`` is a
+Meta programme today and means nothing anywhere else, and a suffix rule would
+quietly merge a model whose name merely ends that way - while a designation
+with no twin in the catalog keeps its own identity rather than vanishing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .data import Model
+
+#: Designation id → the model it is a designation of.
+#:
+#: Added only where the two records carry identical benchmark values, so the
+#: merge cannot invent a difference. A pair that disagrees is a data problem
+#: to look at, not an alias to paper over.
+MODEL_ALIASES: dict[str, str] = {
+    "meta/muse-spark-1.2-contributor": "meta/muse-spark-1.2",
+    "meta/muse-spark-1.3-contributor": "meta/muse-spark-1.3",
+}
+
+
+def canonical_id(model_id: str) -> str:
+    """The model *model_id* names, with any plan designation folded away."""
+    return MODEL_ALIASES.get(model_id, model_id)
+
+
+def plan_ids(model_id: str) -> set[str]:
+    """Every catalog id that is this model, designation or not."""
+    ids = {model_id}
+    ids.update(alias for alias, plain in MODEL_ALIASES.items() if plain == model_id)
+    return ids
+
+
+def merge_aliases(models: list[Model]) -> list[Model]:
+    """Fold designation records into the model they are a designation of.
+
+    Benchmarks union (the plain record wins a disagreement, so a designation
+    can never quietly restate a number), and the cheapest price is kept: the
+    tier price tables replace it wherever they list the model, and where they
+    do not, the price someone can actually pay is the honest one. Order is
+    the catalog's, so the tables do not reshuffle.
+    """
+    known = {m.model_id: m for m in models}
+    merged: list[Model] = []
+    seen: set[str] = set()
+    for model in models:
+        plain = canonical_id(model.model_id)
+        if plain in seen:
+            continue  # already emitted as part of its group
+        twin = known.get(plain)
+        group = (
+            [
+                known[alias]
+                for alias, target in MODEL_ALIASES.items()
+                if target == plain and alias in known
+            ]
+            if twin
+            else []
+        )
+        seen.add(model.model_id)
+        seen.update(m.model_id for m in group)
+        if twin is None or not group:
+            merged.append(model)  # no twin: renaming must not hide it
+            continue
+        scores, sources = dict(twin.scores), dict(twin.sources)
+        for other in group:
+            scores = {**other.scores, **scores}  # plain record wins
+            sources = {**other.sources, **sources}
+        merged.append(
+            replace(
+                twin,
+                price_input=min([twin.price_input] + [m.price_input for m in group]),
+                price_output=min([twin.price_output] + [m.price_output for m in group]),
+                price_cached_input=min(
+                    [twin.price_cached_input] + [m.price_cached_input for m in group]
+                ),
+                scores=scores,
+                sources=sources,
+            )
+        )
+    return merged

opencode_models/labelmap.py

@@ -0,0 +1,84 @@
+"""How each board's model labels map onto catalog ids.
+
+A board and the catalog name the same models differently: Terminal-Bench
+says "Opus 5.5" where the catalog says "Claude Opus 5.5", SWE-bench says
+"Claude 3.5 Sonnet" where the catalog says "Claude Sonnet 3.5 v2". The token
+matcher in :mod:`boards` handles most of that, but two things it cannot do
+on its own:
+
+- **Decide a tie.** "GPT-3.5" fits ``openai/gpt-3.5-turbo`` and
+  ``openai/gpt-5.3-codex`` equally well; the right answer is the first, and
+  no amount of token arithmetic says so.
+- **Stay put.** The catalog gains and loses rows between fetches. A label
+  that resolves today can become ambiguous after an unrelated model lands,
+  and a board score would stop being applied without anyone noticing.
+
+So each service's awkward labels are recorded here, once, by hand. This is
+the *exception list*: labels the matcher places by name or by unique token
+overlap are not listed, because there is nothing to decide. When one appears
+here it is because a human looked at the candidates and made a call.
+
+To add an entry: run ``opencode-models boards``-style analysis (see the
+backfill-scores skill), find the label the matcher cannot place, look at its
+candidates, and write down the one you mean. If the candidates are genuinely
+different models, leave the label out — an absent label is dropped on
+purpose, which is better than a wrong merge.
+"""
+
+from __future__ import annotations
+
+#: Board source host → {label as the board writes it: catalog model id}.
+#: Ids are the canonical ones; a dated snapshot beside them is reached
+#: through :func:`~opencode_models.boards.match_models`, which returns every
+#: row of the matched model.
+LABEL_MAPS: dict[str, dict[str, str]] = {
+    # Terminal-Bench drops the vendor prefix: "Opus 5.5", not "Claude".
+    "www.tbench.ai": {
+        "Fable 5": "anthropic/claude-fable-5",
+        "Fable 5.1": "anthropic/claude-fable-5-1",
+        "Opus 4.8": "anthropic/claude-opus-4-8",
+        "Opus 5": "anthropic/claude-opus-5",
+        "Opus 5.5": "anthropic/claude-opus-5-5",
+        "Sonnet 5": "anthropic/claude-sonnet-5",
+        "Sonnet 5.5": "anthropic/claude-sonnet-5-5",
+    },
+    # SWE-bench orders the version after the family, adds release tags, and
+    # on one label ties with a newer model family entirely.
+    "www.swebench.com": {
+        "Claude 3.5 Sonnet": "anthropic/claude-3-5-sonnet-20241022",
+        "Claude Sonnet 3.5": "anthropic/claude-3-5-sonnet-20241022",
+        "claude-3-5-sonnet-20241022": "anthropic/claude-3-5-sonnet-20241022",
+        "DevStral Small 2507": "mistral/devstral-small-2507",
+        "Devstral (2512)": "mistral/devstral-2512",
+        "Gemini 3 Pro": "google/gemini-3-pro-preview",
+        "Llama 4 Maverick Instruct": "meta/llama-4-maverick-17b-instruct",
+        "Llama 4 Scout Instruct": "meta/llama-4-scout-17b-instruct",
+        # "GPT-3.5" fits gpt-3.5-turbo and gpt-5.3-codex equally by token
+        # count; it means the turbo, which the 0.4% resolve rate confirms.
+        "GPT-3.5": "openai/gpt-3.5-turbo",
+    },
+}
+
+#: Labels a human looked at and left unmapped, with the reason. Kept so the
+#: same question is not re-litigated on every fetch — an unmapped label
+#: drops its score, which is the correct outcome when the board's label
+#: genuinely fits several models.
+UNRESOLVED: dict[str, dict[str, str]] = {
+    "www.swebench.com": {
+        "Gemini 3 Flash": "fits 3-flash-preview, 3.5, 3.6 and 3.7 alike; "
+        "the board does not say which",
+        "Kimi K2": "fits k2-instruct, k2-thinking, k2.5 and k2.6 alike",
+    },
+}
+
+
+def mapped_id(source: str, label: str) -> str | None:
+    """The catalog id *source* uses for *label*, if a human decided one."""
+    host = _host(source)
+    return LABEL_MAPS.get(host, {}).get(label)
+
+
+def _host(source: str) -> str:
+    """The host of a source URL, ignoring scheme and ``www.`` differences."""
+    text = (source or "").split("://", 1)[-1]
+    return text.split("/", 1)[0].lower()

opencode_models/live.py

@@ -0,0 +1,88 @@
+"""Live availability from the Console config API.
+
+``GET /api/v2/config`` answers with the workspace's live model set, per
+provider — the same plans the docs describe, but as the API serves them
+right now rather than as the pricing pages last said. The docs snapshot
+(``tier_prices/``) stays the offline fallback; this layer wins wherever it
+exists, because the API is what the next request is actually checked
+against.
+
+Reading needs a service-account key (``OPENCODE_API_KEY``); the caller
+builds the authed transport, so this module never touches the environment.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+#: The workspace's live model set, with tiered cost arrays and limits.
+LIVE_CONFIG_URL = "https://opencode.ai/console/api/v2/config"
+
+#: Config providers to console tiers. Anything else the API lists is not a
+#: tier this tool ranks, so it is ignored rather than guessed at.
+LIVE_TIERS = {"opencode": "zen", "opencode-go": "go"}
+
+#: Where ``fetch`` snapshots the live set; ``models`` reads it offline.
+SNAPSHOT_DIR = "available"
+
+
+def fetch_live(get) -> dict[str, set[str]]:
+    """Model slugs each tier offers right now, keyed by tier.
+
+    *get* is an authed ``(url) -> str`` callable (the endpoint is
+    person-free but key-gated). Unknown providers are ignored; a provider
+    with no models entry counts as offering nothing, not as unknown.
+    """
+    payload = json.loads(get(LIVE_CONFIG_URL))
+    providers = payload.get("providers") or {}
+    return {
+        tier: set((providers.get(name) or {}).get("models") or {})
+        for name, tier in LIVE_TIERS.items()
+    }
+
+
+def save_live(data_dir: Path, live: dict[str, set[str]]) -> list[str]:
+    """Snapshot the live set to ``available/<tier>.json``; returns files."""
+    saved = []
+    for tier, slugs in live.items():
+        directory = Path(data_dir) / SNAPSHOT_DIR
+        directory.mkdir(parents=True, exist_ok=True)
+        path = directory / f"{tier}.json"
+        path.write_text(
+            json.dumps(
+                {
+                    "meta": {
+                        "source": LIVE_CONFIG_URL,
+                        "fetched_at": datetime.now(timezone.utc).isoformat(
+                            timespec="seconds"
+                        ),
+                    },
+                    "models": sorted(slugs),
+                },
+                indent=1,
+            )
+        )
+        saved.append(path.name)
+    return saved
+
+
+def load_live(data_dir: Path) -> dict[str, set[str] | None]:
+    """The live snapshot, by tier; None where there is none.
+
+    None means "never fetched live", not "the plan offers nothing".
+    """
+    out = {}
+    for tier in sorted(LIVE_TIERS.values()):
+        path = Path(data_dir) / SNAPSHOT_DIR / f"{tier}.json"
+        if not path.exists():
+            out[tier] = None
+            continue
+        try:
+            models = json.loads(path.read_text()).get("models")
+        except (json.JSONDecodeError, OSError, AttributeError):
+            out[tier] = None
+            continue
+        out[tier] = set(models) if isinstance(models, list) else None
+    return out