whatmodel 0.0.2__tar.gz → 0.0.4__tar.gz

whatmodel-0.0.4/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- `whatmodel compare <a> <b>...` puts names side by side and marks the fields that differ.
+- Names with two families say which is the model and which is a source, when the name settles it (`parsed.family_roles`). Otherwise a note says the name leaves it open.
+- About 50 new tokens found by measuring real names: families such as Orca Mini, SQLCoder, OLMo, InternVL, Florence and FLUX; compression formats such as FP8, NVFP4, MXFP8, bitsandbytes and `w4a16`; tunings such as `text`, `python`, `ocr`, `tts` and `asr`.
+- `whatmodel -` reads names from standard input, so `ollama list | whatmodel -` works.
+- `--brief` prints one row per model.
+- Hosted API model IDs (`gpt-4o-2024-08-06`) and OpenRouter IDs (`anthropic/claude-3.5-sonnet:free`) are recognized, and are no longer read as Ollama names.
+- Hugging Face answers are cached on disk for a day. `--no-cache` turns it off.
+- Unknown tokens come with a link that opens a prefilled GitHub issue.
+- `docs/index.html` runs the name reader in the browser.
+- `scripts/coverage.py` measures how much of a list of real names the dictionary understands and lists the most common unknown tokens.
+
+### Fixed
+
+- A name that says nothing about hosting no longer gets a "Runs locally" row. Where a model runs is shown only when the name states it or a lookup confirms it; a model installed in local Ollama is reported as local by that lookup.
+- The `latest` tag Ollama would fill in is no longer shown as a Build row read from the name. It is a note below the table, since a bare name may not be an Ollama name at all.
+- README links work on PyPI.
+
+### Changed
+
+- Rows that a token implies rather than states now show a Source of `name (implied)`, and `implied` in JSON (was `name`).
+
+- `whatmodel tokens` prints grid tables.
+
+### Added
+
+- `whatmodel <name>...` explains Ollama names, Hugging Face repos and GGUF file names in plain English.
+- Layer 1 reads the name offline: family and version, publisher, size, effective size, active parameters, tier, tuning, quantization, format, context, build stamps and hosting.
+- Unknown tokens are reported as unknown, and ambiguous tokens and name formats show every reading.
+- Layer 2 looks up quantization, context length, parameter count, architecture, tool, vision and thinking support, license and file size from the local Ollama API and the Hugging Face Hub API.
+- `whatmodel list` explains every model installed in local Ollama.
+- `whatmodel tokens` prints the token dictionary.
+- Flags `--json`, `--offline`, `--ollama-url`, `--verbose` and `--version`.
+- Library API: `parse()` and `explain()`.
+- Token dictionary in `whatmodel/tokens.yaml`, the only place token meanings live.
+- CI on Python 3.10 to 3.13 across Linux, macOS and Windows.
+- Release workflow that publishes to PyPI with Trusted Publishing when a GitHub Release is published.
+
+[Unreleased]: https://github.com/ShekharBhardwaj/whatmodel/commits/main

{whatmodel-0.0.2 → whatmodel-0.0.4}/CONTRIBUTING.md

@@ -38,6 +38,16 @@ uv run pytest
 
 Label the pull request `tokens` so it lands under "New tokens" in the release notes.
 
+## Finding tokens worth adding
+
+`scripts/coverage.py` reads a file with one model name per line, runs the offline name reader on each, and lists the tokens it could not explain, most common first:
+
+```bash
+uv run python scripts/coverage.py names.txt --top 50
+```
+
+Only add a token when you know what it means. A token left as unknown is correct; a guessed meaning is a bug.
+
 ## Entry fields
 
 | Field | Required | Meaning |

{whatmodel-0.0.2 → whatmodel-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: whatmodel
-Version: 0.0.2
+Version: 0.0.4
 Summary: Explain LLM model names in plain English.
 Project-URL: Homepage, https://github.com/ShekharBhardwaj/whatmodel
 Project-URL: Repository, https://github.com/ShekharBhardwaj/whatmodel
@@ -71,7 +71,7 @@ gemma4:e2b-it-qat
 ├──────────────┼────────────────────────────────────┼──────────────┤
 │ Compression  │ quantization-aware trained         │ name         │
 ├──────────────┼────────────────────────────────────┼──────────────┤
-│ Runs         │ locally                            │ name         │
+│ Runs         │ locally, installed in Ollama here  │ local Ollama │
 ├──────────────┼────────────────────────────────────┼──────────────┤
 │ Parameters   │ 4.6B                               │ local Ollama │
 ├──────────────┼────────────────────────────────────┼──────────────┤
@@ -114,8 +114,6 @@ bartowski/Qwen_Qwen3-30B-A3B-GGUF
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Format       │ GGUF (for llama.cpp, Ollama and LM Studio) │ name         │
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
-│ Runs         │ locally                                    │ name         │
-├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Parameters   │ 30.5B                                      │ Hugging Face │
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Context      │ 32k tokens                                 │ Hugging Face │
@@ -146,8 +144,6 @@ Llama-3-8B-Instruct.Q4_K_M.gguf
 │ Compression │ 4-bit (Q4_K_M, the balanced variant)       │ name   │
 ├─────────────┼────────────────────────────────────────────┼────────┤
 │ Format      │ GGUF (for llama.cpp, Ollama and LM Studio) │ name   │
-├─────────────┼────────────────────────────────────────────┼────────┤
-│ Runs        │ locally                                    │ name   │
 └─────────────┴────────────────────────────────────────────┴────────┘
 ```
 
@@ -158,6 +154,8 @@ A file name has nothing to look up, so every row comes from the name.
 ```text
 whatmodel <name>              explain one name
 whatmodel <name> <name>...    explain several
+whatmodel -                   read names from standard input, one per line
+whatmodel compare <a> <b>     put names side by side and mark what differs
 whatmodel list                explain every model installed in local Ollama
 whatmodel tokens              print the token dictionary
 ```
@@ -168,6 +166,8 @@ whatmodel tokens              print the token dictionary
 | `--offline` | Read the name only and make no network requests. |
 | `--ollama-url URL` | Where Ollama listens. Defaults to `http://localhost:11434`, or `OLLAMA_HOST` if set. |
 | `--verbose`, `-v` | Add a column with a one-sentence explanation of each row. |
+| `--brief`, `-b` | Print one row per model instead of a table each. |
+| `--no-cache` | Do not reuse or save Hugging Face answers on disk. |
 | `--version` | Print the version. |
 
 Accepted name formats:
@@ -175,12 +175,44 @@ Accepted name formats:
 - Ollama: `[host/][namespace/]model[:tag]`, for example `qwen3.5:4b` or `hf.co/bartowski/Qwen_Qwen3-30B-A3B-GGUF:Q4_K_M`
 - Hugging Face: `org/repo`, or a pasted `https://huggingface.co/org/repo` link
 - File names: `Llama-3-8B-Instruct.Q4_K_M.gguf`, with or without a folder in front
+- Hosted API model IDs: `gpt-4o-2024-08-06` or `claude-3-5-sonnet-20241022`. A name is read this way only when every family in it is offered solely as a hosted service.
+- OpenRouter IDs: `anthropic/claude-3.5-sonnet:free`, recognized by an OpenRouter-only tag such as `free` or `nitro`
+
+Piping works with `ollama list`, because only the first column of each line is read:
+
+```bash
+ollama list | whatmodel - --brief
+```
+
+A model that happens to be called `list`, `compare` or `tokens` can be explained with `whatmodel explain list`.
 
-A model that happens to be called `list` or `tokens` can be explained with `whatmodel explain list`.
+### Comparing names
+
+```console
+$ whatmodel compare llama3.1:8b-instruct-q4_K_M llama3.1:8b-instruct-q5_K_M --offline
+
+┌─────────────┬──────────────────────────┬───────────────────────────┬─────────┐
+│             │ llama3.1:8b-instruct-q4_ │ llama3.1:8b-instruct-q5_K │         │
+│ Field       │ K_M                      │ _M                        │ Same?   │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Family      │ Llama 3.1 (Meta)         │ Llama 3.1 (Meta)          │ same    │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Size        │ 8B parameters            │ 8B parameters             │ same    │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Tuning      │ instruction tuned (ready │ instruction tuned (ready  │ same    │
+│             │ for chat)                │ for chat)                 │         │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Compression │ 4-bit (Q4_K_M, the       │ 5-bit (Q5_K_M, the        │ differs │
+│             │ balanced variant)        │ balanced variant)         │         │
+└─────────────┴──────────────────────────┴───────────────────────────┴─────────┘
+Every row is read from the names. Nothing was looked up.
+```
+
+Without `--offline` the looked-up facts are compared too, below a divider. `--json` gives the same rows as data.
 
 ### Unknown and ambiguous tokens
 
-whatmodel never guesses. A token that is not in its dictionary is reported as unknown. A token with two possible meanings is shown with both:
+whatmodel never guesses. A token that is not in its dictionary is reported as unknown, with a link that opens a prefilled GitHub issue so you can report what it means. A token with two possible meanings is shown with both:
 
 ```console
 $ whatmodel qwen-max-0725 --offline
@@ -193,17 +225,43 @@ qwen-max-0725
 ├───────────┼───────────────────────────────────────┼────────┤
 │ Tier      │ max tier (the most capable option)    │ name   │
 ├───────────┼───────────────────────────────────────┼────────┤
-│ Build     │ latest (the default build)            │ name   │
-├───────────┼───────────────────────────────────────┼────────┤
-│ Runs      │ locally                               │ name   │
-├───────────┼───────────────────────────────────────┼────────┤
 │ Ambiguous │ 0725: dated 07-25 (month-day) [build] │ name   │
 │           │ or released 2025-07 [build]           │        │
 └───────────┴───────────────────────────────────────┴────────┘
+No tag in the name. Pulled with Ollama, it would mean latest.
 ```
 
+The same rule covers what a name leaves out. A name alone cannot show where a model runs or which build you would get, so whatmodel adds a Runs row only when the name says so (a `cloud` tag, or a family that is only offered as a hosted service) or a lookup confirms it.
+
 The same applies to a name such as `org/model` with no tag, which fits both a Hugging Face repo and an Ollama model. Both readings are named unless a lookup settles which one it is.
 
+### Names with two families
+
+Fine-tunes and distillations often name two model families. whatmodel says which one is the model only when the name settles it:
+
+```console
+$ whatmodel deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --offline
+
+deepseek-ai/DeepSeek-R1-Distill-Qwen-7B
+┌───────────┬──────────────────────────────────┬────────┐
+│ Field     │ Value                            │ Source │
+├───────────┼──────────────────────────────────┼────────┤
+│ Publisher │ DeepSeek                         │ name   │
+├───────────┼──────────────────────────────────┼────────┤
+│ Family    │ DeepSeek R1 (DeepSeek), a source │ name   │
+│           │ Qwen (Alibaba), the model        │        │
+├───────────┼──────────────────────────────────┼────────┤
+│ Size      │ 7B parameters                    │ name   │
+├───────────┼──────────────────────────────────┼────────┤
+│ Tuning    │ distilled                        │ name   │
+└───────────┴──────────────────────────────────┴────────┘
+Qwen is read as the model and DeepSeek R1 as a source: the family right after
+'Distill' is the one that was trained.
+Read as a Hugging Face repo or an Ollama model (tag latest).
+```
+
+Two rules are used. The family right after `Distill` is the one that was trained. A family that is only offered as a hosted service, such as Claude, has no weights to share, so it is read as a source. When neither rule applies, the output says the name leaves it open.
+
 ### Where the facts come from
 
 The lookup step tries two sources in order and merges them:
@@ -211,7 +269,11 @@ The lookup step tries two sources in order and merges them:
 1. The local Ollama API (`/api/show` and `/api/tags`), for models you have installed.
 2. The Hugging Face Hub API, for names that contain `org/repo`.
 
-Timeouts are short. A source that is offline, slow, or does not know the model is skipped, and the name is still explained. In JSON every item carries a `source` of `name`, `ollama` or `huggingface`, and `lookups` reports what happened with each source.
+Timeouts are short. A source that is offline, slow, or does not know the model is skipped, and the name is still explained. In JSON every item carries a `source` of `name`, `implied`, `ollama` or `huggingface`, and `lookups` reports what happened with each source.
+
+Hugging Face answers are saved on disk for a day, so repeated lookups are instant and still work without a network connection. A note under the table says when a saved copy was used. `--no-cache` turns this off, and `WHATMODEL_CACHE_DIR` moves the folder. Ollama answers are never cached. As a library, `explain()` caches only when you pass `cache_dir`.
+
+A Source of `name (implied)` marks a row that no token states outright but another token settles. `A3B` (3B active parameters) implies a mixture-of-experts design, for example. Run with `-v` to see the reason.
 
 ## Library
 
@@ -221,6 +283,7 @@ from whatmodel import parse, explain
 parsed = parse("qwen3.5:4b")  # the name only, no network
 parsed.family, parsed.version, parsed.size  # ('qwen', '3.5', '4B')
 parsed.unknown  # tokens the dictionary does not know
+parsed.family_roles  # {'qwen': 'model', 'claude': 'source'} when a name has two families
 
 info = explain("qwen3.5:4b")  # the name plus lookups
 info.facts  # looked-up facts, each with its source
@@ -229,6 +292,14 @@ info.to_dict()  # the same data --json prints
 
 `explain(name, offline=True)` makes no requests at all.
 
+## In the browser
+
+[docs/index.html](https://github.com/ShekharBhardwaj/whatmodel/blob/main/docs/index.html) is a single page that runs the same name reader in the browser, with no server and nothing sent anywhere. Served with GitHub Pages it lives at <https://shekharbhardwaj.github.io/whatmodel/>. It reads names only and makes no lookups.
+
+## Coverage
+
+Measured on 5,918 popular Ollama and Hugging Face names on 2026-11-12, whatmodel read 75% of names with no unknown token, and knew 94% of all tokens. New model families appear every week, so the rest are reported as unknown until someone adds them. `scripts/coverage.py` repeats the measurement on any list of names.
+
 ## What the name cannot tell you
 
 A model name is a label chosen by whoever published it. Even a fully understood name leaves these open, which is what the lookup step is for:

{whatmodel-0.0.2 → whatmodel-0.0.4}/README.md

@@ -39,7 +39,7 @@ gemma4:e2b-it-qat
 ├──────────────┼────────────────────────────────────┼──────────────┤
 │ Compression  │ quantization-aware trained         │ name         │
 ├──────────────┼────────────────────────────────────┼──────────────┤
-│ Runs         │ locally                            │ name         │
+│ Runs         │ locally, installed in Ollama here  │ local Ollama │
 ├──────────────┼────────────────────────────────────┼──────────────┤
 │ Parameters   │ 4.6B                               │ local Ollama │
 ├──────────────┼────────────────────────────────────┼──────────────┤
@@ -82,8 +82,6 @@ bartowski/Qwen_Qwen3-30B-A3B-GGUF
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Format       │ GGUF (for llama.cpp, Ollama and LM Studio) │ name         │
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
-│ Runs         │ locally                                    │ name         │
-├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Parameters   │ 30.5B                                      │ Hugging Face │
 ├──────────────┼────────────────────────────────────────────┼──────────────┤
 │ Context      │ 32k tokens                                 │ Hugging Face │
@@ -114,8 +112,6 @@ Llama-3-8B-Instruct.Q4_K_M.gguf
 │ Compression │ 4-bit (Q4_K_M, the balanced variant)       │ name   │
 ├─────────────┼────────────────────────────────────────────┼────────┤
 │ Format      │ GGUF (for llama.cpp, Ollama and LM Studio) │ name   │
-├─────────────┼────────────────────────────────────────────┼────────┤
-│ Runs        │ locally                                    │ name   │
 └─────────────┴────────────────────────────────────────────┴────────┘
 ```
 
@@ -126,6 +122,8 @@ A file name has nothing to look up, so every row comes from the name.
 ```text
 whatmodel <name>              explain one name
 whatmodel <name> <name>...    explain several
+whatmodel -                   read names from standard input, one per line
+whatmodel compare <a> <b>     put names side by side and mark what differs
 whatmodel list                explain every model installed in local Ollama
 whatmodel tokens              print the token dictionary
 ```
@@ -136,6 +134,8 @@ whatmodel tokens              print the token dictionary
 | `--offline` | Read the name only and make no network requests. |
 | `--ollama-url URL` | Where Ollama listens. Defaults to `http://localhost:11434`, or `OLLAMA_HOST` if set. |
 | `--verbose`, `-v` | Add a column with a one-sentence explanation of each row. |
+| `--brief`, `-b` | Print one row per model instead of a table each. |
+| `--no-cache` | Do not reuse or save Hugging Face answers on disk. |
 | `--version` | Print the version. |
 
 Accepted name formats:
@@ -143,12 +143,44 @@ Accepted name formats:
 - Ollama: `[host/][namespace/]model[:tag]`, for example `qwen3.5:4b` or `hf.co/bartowski/Qwen_Qwen3-30B-A3B-GGUF:Q4_K_M`
 - Hugging Face: `org/repo`, or a pasted `https://huggingface.co/org/repo` link
 - File names: `Llama-3-8B-Instruct.Q4_K_M.gguf`, with or without a folder in front
+- Hosted API model IDs: `gpt-4o-2024-08-06` or `claude-3-5-sonnet-20241022`. A name is read this way only when every family in it is offered solely as a hosted service.
+- OpenRouter IDs: `anthropic/claude-3.5-sonnet:free`, recognized by an OpenRouter-only tag such as `free` or `nitro`
+
+Piping works with `ollama list`, because only the first column of each line is read:
+
+```bash
+ollama list | whatmodel - --brief
+```
+
+A model that happens to be called `list`, `compare` or `tokens` can be explained with `whatmodel explain list`.
 
-A model that happens to be called `list` or `tokens` can be explained with `whatmodel explain list`.
+### Comparing names
+
+```console
+$ whatmodel compare llama3.1:8b-instruct-q4_K_M llama3.1:8b-instruct-q5_K_M --offline
+
+┌─────────────┬──────────────────────────┬───────────────────────────┬─────────┐
+│             │ llama3.1:8b-instruct-q4_ │ llama3.1:8b-instruct-q5_K │         │
+│ Field       │ K_M                      │ _M                        │ Same?   │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Family      │ Llama 3.1 (Meta)         │ Llama 3.1 (Meta)          │ same    │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Size        │ 8B parameters            │ 8B parameters             │ same    │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Tuning      │ instruction tuned (ready │ instruction tuned (ready  │ same    │
+│             │ for chat)                │ for chat)                 │         │
+├─────────────┼──────────────────────────┼───────────────────────────┼─────────┤
+│ Compression │ 4-bit (Q4_K_M, the       │ 5-bit (Q5_K_M, the        │ differs │
+│             │ balanced variant)        │ balanced variant)         │         │
+└─────────────┴──────────────────────────┴───────────────────────────┴─────────┘
+Every row is read from the names. Nothing was looked up.
+```
+
+Without `--offline` the looked-up facts are compared too, below a divider. `--json` gives the same rows as data.
 
 ### Unknown and ambiguous tokens
 
-whatmodel never guesses. A token that is not in its dictionary is reported as unknown. A token with two possible meanings is shown with both:
+whatmodel never guesses. A token that is not in its dictionary is reported as unknown, with a link that opens a prefilled GitHub issue so you can report what it means. A token with two possible meanings is shown with both:
 
 ```console
 $ whatmodel qwen-max-0725 --offline
@@ -161,17 +193,43 @@ qwen-max-0725
 ├───────────┼───────────────────────────────────────┼────────┤
 │ Tier      │ max tier (the most capable option)    │ name   │
 ├───────────┼───────────────────────────────────────┼────────┤
-│ Build     │ latest (the default build)            │ name   │
-├───────────┼───────────────────────────────────────┼────────┤
-│ Runs      │ locally                               │ name   │
-├───────────┼───────────────────────────────────────┼────────┤
 │ Ambiguous │ 0725: dated 07-25 (month-day) [build] │ name   │
 │           │ or released 2025-07 [build]           │        │
 └───────────┴───────────────────────────────────────┴────────┘
+No tag in the name. Pulled with Ollama, it would mean latest.
 ```
 
+The same rule covers what a name leaves out. A name alone cannot show where a model runs or which build you would get, so whatmodel adds a Runs row only when the name says so (a `cloud` tag, or a family that is only offered as a hosted service) or a lookup confirms it.
+
 The same applies to a name such as `org/model` with no tag, which fits both a Hugging Face repo and an Ollama model. Both readings are named unless a lookup settles which one it is.
 
+### Names with two families
+
+Fine-tunes and distillations often name two model families. whatmodel says which one is the model only when the name settles it:
+
+```console
+$ whatmodel deepseek-ai/DeepSeek-R1-Distill-Qwen-7B --offline
+
+deepseek-ai/DeepSeek-R1-Distill-Qwen-7B
+┌───────────┬──────────────────────────────────┬────────┐
+│ Field     │ Value                            │ Source │
+├───────────┼──────────────────────────────────┼────────┤
+│ Publisher │ DeepSeek                         │ name   │
+├───────────┼──────────────────────────────────┼────────┤
+│ Family    │ DeepSeek R1 (DeepSeek), a source │ name   │
+│           │ Qwen (Alibaba), the model        │        │
+├───────────┼──────────────────────────────────┼────────┤
+│ Size      │ 7B parameters                    │ name   │
+├───────────┼──────────────────────────────────┼────────┤
+│ Tuning    │ distilled                        │ name   │
+└───────────┴──────────────────────────────────┴────────┘
+Qwen is read as the model and DeepSeek R1 as a source: the family right after
+'Distill' is the one that was trained.
+Read as a Hugging Face repo or an Ollama model (tag latest).
+```
+
+Two rules are used. The family right after `Distill` is the one that was trained. A family that is only offered as a hosted service, such as Claude, has no weights to share, so it is read as a source. When neither rule applies, the output says the name leaves it open.
+
 ### Where the facts come from
 
 The lookup step tries two sources in order and merges them:
@@ -179,7 +237,11 @@ The lookup step tries two sources in order and merges them:
 1. The local Ollama API (`/api/show` and `/api/tags`), for models you have installed.
 2. The Hugging Face Hub API, for names that contain `org/repo`.
 
-Timeouts are short. A source that is offline, slow, or does not know the model is skipped, and the name is still explained. In JSON every item carries a `source` of `name`, `ollama` or `huggingface`, and `lookups` reports what happened with each source.
+Timeouts are short. A source that is offline, slow, or does not know the model is skipped, and the name is still explained. In JSON every item carries a `source` of `name`, `implied`, `ollama` or `huggingface`, and `lookups` reports what happened with each source.
+
+Hugging Face answers are saved on disk for a day, so repeated lookups are instant and still work without a network connection. A note under the table says when a saved copy was used. `--no-cache` turns this off, and `WHATMODEL_CACHE_DIR` moves the folder. Ollama answers are never cached. As a library, `explain()` caches only when you pass `cache_dir`.
+
+A Source of `name (implied)` marks a row that no token states outright but another token settles. `A3B` (3B active parameters) implies a mixture-of-experts design, for example. Run with `-v` to see the reason.
 
 ## Library
 
@@ -189,6 +251,7 @@ from whatmodel import parse, explain
 parsed = parse("qwen3.5:4b")  # the name only, no network
 parsed.family, parsed.version, parsed.size  # ('qwen', '3.5', '4B')
 parsed.unknown  # tokens the dictionary does not know
+parsed.family_roles  # {'qwen': 'model', 'claude': 'source'} when a name has two families
 
 info = explain("qwen3.5:4b")  # the name plus lookups
 info.facts  # looked-up facts, each with its source
@@ -197,6 +260,14 @@ info.to_dict()  # the same data --json prints
 
 `explain(name, offline=True)` makes no requests at all.
 
+## In the browser
+
+[docs/index.html](https://github.com/ShekharBhardwaj/whatmodel/blob/main/docs/index.html) is a single page that runs the same name reader in the browser, with no server and nothing sent anywhere. Served with GitHub Pages it lives at <https://shekharbhardwaj.github.io/whatmodel/>. It reads names only and makes no lookups.
+
+## Coverage
+
+Measured on 5,918 popular Ollama and Hugging Face names on 2026-11-12, whatmodel read 75% of names with no unknown token, and knew 94% of all tokens. New model families appear every week, so the rest are reported as unknown until someone adds them. `scripts/coverage.py` repeats the measurement on any list of names.
+
 ## What the name cannot tell you
 
 A model name is a label chosen by whoever published it. Even a fully understood name leaves these open, which is what the lookup step is for:

{whatmodel-0.0.2 → whatmodel-0.0.4}/tests/conftest.py

@@ -26,3 +26,11 @@ def _no_network(monkeypatch: pytest.MonkeyPatch) -> None:
     monkeypatch.setattr(socket.socket, "connect", blocked)
     monkeypatch.setattr(socket.socket, "connect_ex", blocked)
     monkeypatch.setattr(socket, "getaddrinfo", blocked)
+
+
+@pytest.fixture(autouse=True)
+def _private_cache(
+    monkeypatch: pytest.MonkeyPatch, tmp_path_factory: pytest.TempPathFactory
+) -> None:
+    """Point the lookup cache at an empty folder, never at the developer's real one."""
+    monkeypatch.setenv("WHATMODEL_CACHE_DIR", str(tmp_path_factory.mktemp("cache")))

whatmodel-0.0.4/tests/test_cache.py

@@ -0,0 +1,96 @@
+"""The on-disk lookup cache."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+import pytest
+
+from whatmodel import cache, explain
+
+BODY = {"id": "org/repo", "cardData": {"license": "mit"}}
+
+
+def test_round_trip(tmp_path: Path) -> None:
+    assert cache.read(tmp_path, "org/repo") is None
+    cache.write(tmp_path, "org/repo", BODY)
+    assert cache.read(tmp_path, "org/repo") == BODY
+    assert cache.read(tmp_path, "Org/Repo") == BODY  # repo names ignore case
+    assert cache.read(tmp_path, "org/other") is None
+
+
+def test_entries_expire(tmp_path: Path) -> None:
+    cache.write(tmp_path, "org/repo", BODY, now=1000.0)
+    assert cache.read(tmp_path, "org/repo", now=1000.0 + cache.MAX_AGE - 1) == BODY
+    assert cache.read(tmp_path, "org/repo", now=1000.0 + cache.MAX_AGE + 1) is None
+    assert cache.read(tmp_path, "org/repo", now=999.0) is None  # saved in the future
+
+
+def test_broken_files_are_ignored(tmp_path: Path) -> None:
+    cache.write(tmp_path, "org/repo", BODY)
+    (file,) = tmp_path.glob("*.json")
+    file.write_text("not json", encoding="utf-8")
+    assert cache.read(tmp_path, "org/repo") is None
+
+
+def test_unwritable_cache_is_ignored(tmp_path: Path) -> None:
+    blocker = tmp_path / "file"
+    blocker.write_text("", encoding="utf-8")
+    cache.write(blocker / "sub", "org/repo", BODY)  # must not raise
+    assert cache.read(blocker / "sub", "org/repo") is None
+
+
+def test_clear(tmp_path: Path) -> None:
+    cache.write(tmp_path, "a/b", BODY)
+    cache.write(tmp_path, "c/d", BODY)
+    assert cache.clear(tmp_path) == 2
+    assert cache.read(tmp_path, "a/b") is None
+    assert cache.clear(tmp_path / "missing") == 0
+
+
+def test_default_dir_follows_the_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(cache.ENV_VAR, "/somewhere/else")
+    assert cache.default_cache_dir() == Path("/somewhere/else")
+    monkeypatch.delenv(cache.ENV_VAR)
+    assert cache.default_cache_dir().name.lower() in {"whatmodel", "cache"}
+
+
+def _client(calls: list[str]) -> httpx.Client:
+    def handler(request: httpx.Request) -> httpx.Response:
+        calls.append(request.url.host)
+        if request.url.host == "huggingface.co":
+            return httpx.Response(200, json=BODY)
+        return httpx.Response(404, json={})
+
+    return httpx.Client(transport=httpx.MockTransport(handler))
+
+
+def test_second_lookup_is_served_from_the_cache(tmp_path: Path) -> None:
+    calls: list[str] = []
+    first = explain("org/repo", client=_client(calls), cache_dir=tmp_path)
+    assert first.cached == ()
+    assert calls.count("huggingface.co") == 1
+
+    second = explain("org/repo", client=_client(calls), cache_dir=tmp_path)
+    assert second.cached == ("huggingface",)
+    assert calls.count("huggingface.co") == 1  # no second request
+    assert second.facts == first.facts
+    assert second.lookups["huggingface"] == "ok"
+
+
+def test_nothing_touches_disk_without_a_cache_dir(tmp_path: Path) -> None:
+    calls: list[str] = []
+    explain("org/repo", client=_client(calls))
+    explain("org/repo", client=_client(calls))
+    assert calls.count("huggingface.co") == 2
+    assert list(tmp_path.iterdir()) == []
+
+
+def test_failed_lookups_are_not_cached(tmp_path: Path) -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(404, json={})
+
+    client = httpx.Client(transport=httpx.MockTransport(handler))
+    explain("org/repo", client=client, cache_dir=tmp_path)
+    assert list(tmp_path.glob("*.json")) == []