modelroster 0.1.0__tar.gz

modelroster-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+src/modelroster/data/cache/
+src/modelroster/data/*.previous.json
+src/modelroster/data/discovered/
+src/modelroster/data/*.tmp
+.env

modelroster-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+Two version numbers matter:
+
+* the **package version** (`modelroster.__version__`) — API/CLI compatibility;
+* the **parser version** (`modelroster.PARSER_VERSION`, stamped into every
+  record) — bumped whenever any adapter's output for the same input could change.
+
+## [Unreleased]
+
+## [0.1.0] — 2026-08-23
+
+Initial release, ported from the `model_registry` prototype.
+
+### Added
+- One normalized `ModelRecord` schema with tri-state capabilities, modalities,
+  endpoints, built-in tools, pricing, provenance, and warnings.
+- Providers: anthropic, openai (docs parser + listing), xai, mistral, google,
+  cohere, nvidia, inception, ollama; `modelroster.providers` entry-point group.
+- Discovery tier: huggingface, ollama_library, nvidia_nim.
+- Consumer API: `load()`, `Registry.models(**filters)`, `ModelRef`, predicates.
+- CLI: `update`, `list`, `show`, `diff`, `validate`, `emit`, `discover`,
+  `providers`, `capture`.
+- Shared HTTP layer with retries, caching, content-hash change detection,
+  full `--offline` coverage, and fixture replay.
+- Validation gates (page failures, parser regression, catalog shrink,
+  header-fact loss, generic shrink) with byte-for-byte preservation on refusal.
+- Shipped data for anthropic, openai, nvidia, inception (retrieved 2026-08-23);
+  xai, mistral, cohere, google populate via `modelroster update` with keys.
+- Runtime alias index: documented aliases, snapshots, and `ft:` bases resolve
+  through `Registry.get`/`resolve`/`ModelRef` even when the listing does not
+  carry them.
+- `py.typed` marker for downstream type-checkers.
+- GitHub Actions: offline tests on push, daily live refresh, PyPI publish on tags.

modelroster-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zach Hanson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

modelroster-0.1.0/MAINTAINERS.md

@@ -0,0 +1,128 @@
+# Maintaining modelroster
+
+This file is written for the agent (or person) operating the refresh loop.
+Everything below is scriptable; nothing requires judgment until a gate fires.
+
+## The loop
+
+```
+modelroster update --all            # 1. refresh every provider you have keys for
+modelroster diff                    # 2. read the drift reports
+modelroster validate -v             # 3. inspect warnings
+```
+
+1. **Run the update.** One provider failing never blocks the others. Exit
+   status is the worst stage: `0` everything written, `2` at least one provider
+   refused (its previous data is untouched), `3` a fetch failed, `4` usage.
+   A provider whose key is absent is *skipped* with exit 0 — check the summary
+   line (`xai: skipped (...)`) to make sure that is what you expected.
+2. **Read the drift report** (`modelroster diff`, or `<provider>.drift.json`).
+   New/removed models and snapshots are normal. Post the report where the team
+   will see it. A `changed_capabilities` entry that flips a documented value
+   (`true -> false`) on many models at once is a parser problem until proven
+   otherwise — see "Deciding whether the parser broke".
+3. **Inspect warnings.** The categories you will see:
+   * `No official model documentation record matched this API model ID` —
+     the listing has ids the docs don't (search/tts variants). Informational.
+   * `id X claimed by A, B; resolved to A` — alias pages claiming another
+     family's snapshot; resolved deterministically. Informational.
+   * `contradiction: ...` — the page says two things. Informational, but
+     worth a glance.
+   * `unrecognised <thing> ... (kept)` — **new vocabulary**. The value is
+     retained, so nothing is lost, but the known-vocabulary tuples in
+     `schema.py` / the provider module should be extended so the value gets a
+     stable key and absence starts meaning `False` where a positive list is
+     present. This is a parser change → bump `PARSER_VERSION`.
+   * `unparseable knowledge cutoff` — extend `parse_cutoff`. Parser change.
+   * `no Endpoints section found` / `no Model details section found` on
+     pages that used to have them — format change. See below.
+
+## Deciding whether the parser broke
+
+A gate firing (exit 2) means the data on disk is still the last good run. Do
+**not** delete `<provider>.json` or `.previous.json` to "fix" it.
+
+* `PARSER REGRESSION suspected` / `HEADER PARSE REGRESSION suspected` —
+  fetch one affected page (`curl https://developers.openai.com/api/docs/models/<slug>.md`)
+  and compare with `tests/fixtures/openai_docs/<slug>.md`. If a heading was
+  renamed or a bullet format changed, update the regexes / section constants
+  in `providers/openai_docs.py`, refresh the fixture, add a test, bump
+  `PARSER_VERSION`.
+* `documentation catalog shrank` — open `models.md`; the link format probably
+  changed (`discover_model_pages`).
+* `N/M documentation pages failed to fetch/parse` — transient (rerun, the
+  fetcher retries and falls back to cache) unless the failures are `parse:` —
+  then a format change.
+* `model list shrank` — compare the raw listing (`modelroster capture`) with
+  the previous data. Real mass retirements happen; if it is real, the gate can
+  be overridden by deleting *only* `<provider>.previous.json`… but first post
+  the diff and get a human ack.
+
+## Parser version and releases
+
+`PARSER_VERSION` (`schema.py`) is stamped into every record. Bump it whenever
+an adapter's output for the same input could change: new vocabulary, a new
+regex, a changed mapping, a new provider-wide fact. The date-based format is
+`YYYY.MM.DD-N`.
+
+Release when data or code changed in a way consumers should pick up:
+
+1. `CHANGELOG.md`: move items from Unreleased under a new version heading.
+2. Bump `src/modelroster/_version.py` (semver: data-only refresh = patch;
+   new provider/field = minor; schema or API break = major — also bump
+   `SCHEMA_VERSION`).
+3. `pytest -q && modelroster validate`.
+4. Tag `vX.Y.Z` and push the tag — `publish.yml` builds, re-validates, checks
+   the tag matches `__version__`, and publishes via PyPI trusted publishing
+   (configure the `pypi` environment once in the repository settings).
+
+Before the **first** publish, confirm the name is still free:
+`pip index versions modelroster` should report nothing.
+
+## Automation in place
+
+* `ci.yml` — offline suite on every push (3.11–3.13), fixture replay of the
+  full OpenAI/Anthropic pipeline, shipped-data validation, and a clean-venv
+  install test of the built wheel.
+* `refresh.yml` — daily at 06:17 UTC: `modelroster update --all --no-cache`
+  with whatever secrets are configured, the live test suite, then commits
+  `src/modelroster/data/*.json` (data + drift reports) on success. On exit ≠ 0
+  it opens a GitHub issue labelled `refresh-failure` with the log tail and
+  fails the run.
+* `publish.yml` — on tags.
+
+Secrets to configure for the refresh: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+and optionally `XAI_API_KEY`, `MISTRAL_API_KEY`, `GOOGLE_API_KEY`,
+`COHERE_API_KEY`, `NVIDIA_API_KEY`, `INCEPTION_API_KEY`. Missing ones skip
+the provider.
+
+## Fixtures
+
+`tests/fixtures/README.md` records the provenance of every fixture. When a
+provider's response shape changes or a key becomes available for a provider
+whose fixture is reference-shaped, run `modelroster capture --provider <name>`
+(writes under `tests/fixtures/listings/`) and commit the result. OpenAI
+documentation pages are refreshed by copying `<data-dir>/cache/openai/*.body`
+files to `tests/fixtures/openai_docs/<slug>.md` (the `.meta.json` beside each
+body records its URL).
+
+## Adding a provider
+
+1. `src/modelroster/providers/<name>.py` — subclass `OpenAICompatProvider`
+   or `BaseProvider`; set `name`, `auth`, `describe`; implement
+   `enrich_record`/`enrich`; point `fixtures()` at captured responses.
+2. Add it to `_BUILTIN` in `providers/__init__.py` (third parties use the
+   entry-point group instead).
+3. `tests/fixtures/listings/<name>_models.json` + a test in
+   `tests/test_compat_providers.py` that asserts the tri-state mapping.
+4. Document the row in the README table; add the key to `refresh.yml`.
+
+## Things that must stay true
+
+* No generation probes. Availability from listings, capabilities from
+  official docs/metadata only.
+* `None` is never turned into `False`.
+* Exact-id matching only.
+* A refused update leaves the previous file byte-identical.
+* No key is ever read from anywhere but the environment / `.env`, and never
+  written to disk (the HTTP cache stores response bodies, not request headers).

modelroster-0.1.0/PKG-INFO

@@ -0,0 +1,258 @@
+Metadata-Version: 2.5
+Name: modelroster
+Version: 0.1.0
+Summary: Accurate, current LLM model identifiers and capabilities for every provider — shipped as data, refreshed from official sources.
+Project-URL: Homepage, https://github.com/ZlaylowZ/modelroster
+Project-URL: Repository, https://github.com/ZlaylowZ/modelroster
+Project-URL: Changelog, https://github.com/ZlaylowZ/modelroster/blob/main/CHANGELOG.md
+Author-email: Zach Hanson <zhanson1@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anthropic,capabilities,llm,models,openai,registry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.25
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: dotenv
+Requires-Dist: python-dotenv>=1.0; extra == 'dotenv'
+Description-Content-Type: text/markdown
+
+# modelroster
+
+**Accurate, current LLM model identifiers and capabilities for every provider —
+shipped as data, refreshed from official sources, never guessed.**
+
+```bash
+pip install modelroster
+```
+
+```python
+import modelroster
+
+r = modelroster.load()                                   # works offline, no keys
+for m in r.models(tool_calling=True, reasoning=True):
+    print(m.ref, m.context_window, m.capabilities.reasoning_efforts)
+
+ref = modelroster.ModelRef.parse("openai/gpt-5.4").validate()   # raises on unknown/retired ids
+modelroster.context_window("claude-opus-5")              # 1000000
+modelroster.supports_tool_calling("text-embedding-3-small")     # None  (not documented — NOT False)
+```
+
+## Why
+
+Providers add, rename, alias, snapshot and retire models constantly, and each
+publishes its list differently. Every project that calls an LLM ends up with a
+hand-maintained model table that silently rots. `modelroster` is one package
+that any project — or any agent — installs to get the exact id strings a
+provider accepts today and what each model supports, with enough validation
+that an upstream format change fails loudly instead of shipping a broken
+catalog.
+
+## Principles
+
+1. **Tri-state capabilities.** Every capability is `True` / `False` / `None`.
+   `None` means *the source does not say* and is never collapsed into `False`.
+   `False` only arises from an explicit "not supported" statement, or from
+   absence in a positively enumerated list whose section is present.
+2. **No generation probes.** Availability comes from listing endpoints;
+   capabilities come from official documentation or official API metadata.
+   The registry never sends a completion request to find out what a model does.
+3. **Provenance on every fact.** Each field carries `{section, evidence, ...}`
+   naming the document section or API field it came from
+   (`modelroster show gpt-5.4 --provenance`).
+4. **Exact ids only.** Aliases, snapshots and fine-tune bases resolve through an
+   explicit index built from provider statements; there is no fuzzy matching and
+   no inference from date suffixes.
+5. **Refuse rather than rot.** Validation gates refuse to overwrite good data
+   when a parser stops understanding a page; the previous data survives
+   byte-for-byte and a drift report says what changed.
+
+## What is in the box
+
+| Provider | Availability | Capabilities | Key |
+|---|---|---|---|
+| `anthropic` | `GET /v1/models` (paginated) | the same call's `capabilities` object | `ANTHROPIC_API_KEY` |
+| `openai` | `GET /v1/models` | official Markdown docs (`developers.openai.com/api/docs/models/*.md`), 96 pages | `OPENAI_API_KEY` |
+| `xai` | `GET /v1/models` | `GET /v1/language-models` (modalities, aliases) | `XAI_API_KEY` |
+| `mistral` | `GET /v1/models` | the listing's `capabilities` object | `MISTRAL_API_KEY` |
+| `google` | OpenAI-compat shim `/v1beta/openai/models` | native `/v1beta/models` (limits, methods) | `GOOGLE_API_KEY` / `GEMINI_API_KEY` |
+| `cohere` | `GET /v1/models` | the same call (endpoints, features, context) | `COHERE_API_KEY` |
+| `nvidia` | `GET integrate.api.nvidia.com/v1/models` (public) | — (ids only) | optional |
+| `inception` | `GET api.inceptionlabs.ai/v1/models` (public) | the same call (modalities, limits, features, pricing) | optional |
+| `ollama` | local `GET /api/tags` | local `POST /api/show` (capabilities, context) | none (`OLLAMA_HOST`) |
+
+**Data coverage.** The wheel ships *live* data for **anthropic, openai,
+nvidia, and inception** — the providers refreshable at release time with the
+keys at hand or public listings (`modelroster providers` shows what is loaded
+and when it was retrieved). **xai, mistral, cohere, and google** currently
+have no shipped data: their test fixtures are reference-shaped (hand-written
+to each provider's public API reference, see `tests/fixtures/README.md`)
+pending real keys — the Google key available at build time was rejected with
+HTTP 400 and needs replacement. Run `modelroster update` with your own keys to
+populate them; a missing key skips that provider, it is never an error, and
+the daily refresh workflow behaves the same way.
+
+A separate **discovery tier** (`modelroster discover huggingface|ollama_library|nvidia_nim`)
+lists candidate models from broad registries with mostly-unknown capabilities.
+They are labelled `tier="discovered"` and never enter the verified catalog.
+
+## Consumer API
+
+```python
+r = modelroster.load()                       # every provider with data
+r = modelroster.load("openai")               # one provider
+r = modelroster.load(data_dir="~/my/data")   # a refreshed copy (also $MODELROSTER_DATA_DIR)
+
+r.providers(); r.info()                      # retrieved_at, parser_version, counts
+r.get("gpt-5.4"); r.get("openai/gpt-5.4"); r.get(ModelRef("openai", "gpt-5.4"))
+r.resolve("gpt-4o-2024-08-06")               # -> the gpt-4o family record
+r.models(provider="openai", tool_calling=True, image_input=True, endpoint="responses")
+r.models(reasoning=True, unknown_ok=True)    # let None pass too
+r.models(relationship="canonical", include_retired=False, strict=True)
+r.ids(...); r.refs(...)                      # plain ids / ModelRefs
+```
+
+Filters accept every capability name (`reasoning`, `reasoning_efforts`,
+`extended_thinking`, `tool_calling`, `structured_outputs`, `streaming`,
+`prompt_caching`, `fine_tuning`, `batch`, `citations`, `code_execution`,
+`pdf_input`), modality flags (`image_input`, `audio_output`, …), any
+`capabilities.extra` key, and `endpoint=` / `builtin_tool=`. A `True`/`False`
+filter matches only a *documented* value; pass `unknown_ok=True` to let `None`
+through.
+
+Module-level predicates mirror the record fields and are provider-agnostic:
+`supports(model, cap)`, `supports_tool_calling`, `supports_reasoning`,
+`supported_reasoning_efforts`, `supports_endpoint`, `supports_builtin_tool`,
+`supports_modality`, `context_window`, `max_input_tokens`, `max_output_tokens`,
+`models_supporting(cap, provider)`, `available_models(provider)`.
+
+### `ModelRef` — a type for model names
+
+```python
+from modelroster import ModelRef, UnknownModelError, RetiredModelError
+
+ModelRef.parse("openai/gpt-5.4")        # explicit
+ModelRef.parse("gpt-5.4")               # provider found by exact lookup in the registry
+ModelRef.parse("gpt-99").inferred       # True: only the documented prefix heuristic matched
+ModelRef("openai", "gpt-5.4").validate()            # raises UnknownModelError / RetiredModelError
+ModelRef("openai", "gpt-4o-2024-08-06").resolve()   # canonical family record
+```
+
+### Dependency-free snapshot
+
+```bash
+modelroster emit --out my_models.py --provider openai --provider anthropic -c tool_calling
+```
+
+writes a compiled-checked module with `MODELS`, `OPENAI_MODELS`,
+`OPENAI_MODEL_IDS`, … for projects that vendor a file instead of depending on
+`modelroster`.
+
+### Scheduled refresh from an agent
+
+```python
+report = modelroster.refresh(["openai", "anthropic"])   # {provider: {code, drift, errors, ...}}
+```
+
+## CLI
+
+```
+modelroster update [--provider X ...] [--offline] [--dry-run] [--no-cache] [--fixtures DIR] [--emit FILE]
+modelroster list [--provider X] [-c reasoning -c tool_calling[=true|false|unknown]] [--endpoint K] [--json]
+modelroster show <id | provider/id> [--provenance] [--json]
+modelroster diff [--provider X]          # last drift report
+modelroster validate [--provider X] [-v] # re-run the gates on stored data
+modelroster emit --out FILE [--provider X] [-c ...]
+modelroster discover <huggingface|ollama_library|nvidia_nim> [--limit N] [--write]
+modelroster providers [-v]
+modelroster capture --provider X         # save live listing responses as test fixtures
+```
+
+Exit status: `0` ok · `2` validation refused the write (previous data preserved)
+· `3` fetch failure · `4` usage. Providers run independently; the exit status
+is the worst stage.
+
+`--offline` serves *every* request — documentation pages and listing calls —
+from the on-disk cache (`<data-dir>/cache/<provider>/`) and never opens a
+socket. `--fixtures tests/fixtures` replays the captured fixtures instead.
+
+Keys are read from the environment (`<PROVIDER>_API_KEY`), optionally from a
+`.env` in the working directory when `python-dotenv` is installed
+(`pip install modelroster[dotenv]`); existing environment variables are never
+overridden. No key is ever written anywhere.
+
+## Record shape
+
+```
+ModelRecord
+  provider, model_id                exact string the API accepts
+  display_name, description, family (canonical id), aliases, snapshots,
+  default_snapshot, routes_to, relationship (canonical|snapshot|alias|fine_tune_inherited|unknown)
+  released, deprecated, shutdown_date
+  context_window, max_input_tokens, max_output_tokens
+  knowledge_cutoff (ISO), knowledge_cutoff_raw
+  modalities {text,image,audio,video} x {input,output}
+  capabilities  reasoning, reasoning_efforts, default_effort, extended_thinking, tool_calling,
+                structured_outputs, streaming, prompt_caching, fine_tuning, batch, citations,
+                code_execution, pdf_input, extra{provider-specific keys}
+  endpoints {key: tri}, builtin_tools {key: tri} | None, pricing {input, output, cached_input} | None
+  tier (verified|discovered), provenance, sources, raw, retrieved_at, parser_version, warnings
+```
+
+**Provider-wide facts.** An adapter may set a capability from provider-wide
+official documentation (rather than a per-model source) only when the statement
+covers every model the listing returns; such values carry
+`provenance = {"section": "provider_docs", "evidence": "provider-wide statement", "url": ...}`.
+Anthropic uses this for `tool_calling` and `streaming`. Nothing else is inferred.
+
+## Validation gates
+
+Generic: empty listing; model count shrinks by more than half when the previous
+run had at least 5 models. OpenAI: more than 10 % of documentation pages fail
+to fetch/parse; parser regression (more than 25 % or at least 10
+previously-understood pages now parse to nothing); documentation catalog shrinks
+by more than half; loss of header-region facts (reasoning-effort sentence, prose
+alias) on at least 25 % of the pages that previously carried them. The emitted
+snapshot module must compile. On refusal the previous file is untouched and the
+CLI exits 2.
+
+Every successful update writes `<provider>.drift.json` beside the data: added /
+removed models and families, new / removed snapshots, per-model capability
+deltas (`None` printed as `unknown`), and warnings.
+
+## Adding a provider
+
+Subclass `OpenAICompatProvider` (or `BaseProvider`), set `name`, `base_url`,
+`auth`, override `enrich_record` if the provider publishes per-model metadata,
+and point `fixtures()` at a captured response. Register it with
+`modelroster.providers.register(MyProvider())` or via the entry-point group
+`modelroster.providers`. No core file changes are needed (see
+`tests/test_compat_providers.py::test_plugin_provider_needs_no_core_edits`).
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q                                   # offline, ~1 s
+MODELROSTER_LIVE=1 pytest tests/test_live.py -q    # hits the real endpoints
+modelroster update --fixtures tests/fixtures --dry-run   # full pipeline on fixtures
+```
+
+See [MAINTAINERS.md](MAINTAINERS.md) for the refresh loop, `docs/DESIGN.md`
+for the design note, and `docs/DIFFERENCES.md` for where this package
+intentionally differs from the prototype it was ported from.
+
+## License
+
+MIT.