facet-models 2026.9.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- facet_models-2026.9.0/LICENSE +21 -0
- facet_models-2026.9.0/PKG-INFO +234 -0
- facet_models-2026.9.0/README.md +211 -0
- facet_models-2026.9.0/pyproject.toml +43 -0
- facet_models-2026.9.0/setup.cfg +4 -0
- facet_models-2026.9.0/src/facet/__init__.py +27 -0
- facet_models-2026.9.0/src/facet/__main__.py +8 -0
- facet_models-2026.9.0/src/facet/_find.py +89 -0
- facet_models-2026.9.0/src/facet/_identity.py +35 -0
- facet_models-2026.9.0/src/facet/_table.py +73 -0
- facet_models-2026.9.0/src/facet/_version.py +2 -0
- facet_models-2026.9.0/src/facet/cli.py +100 -0
- facet_models-2026.9.0/src/facet/data/model-registry.json +1 -0
- facet_models-2026.9.0/src/facet/py.typed +0 -0
- facet_models-2026.9.0/src/facet_models.egg-info/PKG-INFO +234 -0
- facet_models-2026.9.0/src/facet_models.egg-info/SOURCES.txt +21 -0
- facet_models-2026.9.0/src/facet_models.egg-info/dependency_links.txt +1 -0
- facet_models-2026.9.0/src/facet_models.egg-info/entry_points.txt +2 -0
- facet_models-2026.9.0/src/facet_models.egg-info/top_level.txt +1 -0
- facet_models-2026.9.0/tests/test_package.py +262 -0
- facet_models-2026.9.0/tests/test_pick_model.py +124 -0
- facet_models-2026.9.0/tests/test_sync.py +259 -0
- facet_models-2026.9.0/tests/test_verify.py +615 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Facet contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,234 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: facet-models
|
|
3
|
+
Version: 2026.9.0
|
|
4
|
+
Summary: Thin fact client for the Facet model registry: load the table, resolve names, find candidates. Zero runtime dependencies.
|
|
5
|
+
Author: Facet contributors
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/hsliuping/Facet
|
|
8
|
+
Keywords: llm,model-registry,model-selection,ai,facts
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
18
|
+
Classifier: Typing :: Typed
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
License-File: LICENSE
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Facet
|
|
25
|
+
|
|
26
|
+
**English** | [简体中文](README.zh-CN.md)
|
|
27
|
+
|
|
28
|
+
**Facet answers one question for your application: "for this task, which model should I use?"**
|
|
29
|
+
|
|
30
|
+
It is not a router. It is a **facts table** — a single JSON file describing
|
|
31
|
+
the capabilities, limits, and prices of ~2,400 models across 217 providers —
|
|
32
|
+
plus the tools that keep the table fresh and a demo consumer. Your project
|
|
33
|
+
reads the table, applies its own business rules, and picks a model.
|
|
34
|
+
|
|
35
|
+
```
|
|
36
|
+
models.dev (primary, 217 providers) OpenRouter /api/v1/models (secondary)
|
|
37
|
+
│ │
|
|
38
|
+
└──────────── weekly sync ───────────────┘
|
|
39
|
+
│ tools/sync_models_dev.py
|
|
40
|
+
▼
|
|
41
|
+
registry/model-registry.json ← the deliverable: one file, < 1 MB, zero deps
|
|
42
|
+
│
|
|
43
|
+
├── your service (fetch the JSON, filter, decide)
|
|
44
|
+
└── examples/pick_model.py (reference consumer / demo)
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Why a table instead of a router?
|
|
48
|
+
|
|
49
|
+
- Routers encode *someone else's* policy. Your business rules are yours.
|
|
50
|
+
- A router is a dependency; a JSON file is data. Fetch it, vendor it, or copy
|
|
51
|
+
the fields you need.
|
|
52
|
+
- Facts change weekly (prices, limits, new models). Policy changes daily. We
|
|
53
|
+
ship the part that changes weekly.
|
|
54
|
+
|
|
55
|
+
## The table
|
|
56
|
+
|
|
57
|
+
`registry/model-registry.json` — keyed `provider/model_id`, one record per
|
|
58
|
+
model identity, deduped across providers (aggregator copies lose to
|
|
59
|
+
first-party ones; ties prefer richer records).
|
|
60
|
+
|
|
61
|
+
| Field | Meaning | Notes |
|
|
62
|
+
|---|---|---|
|
|
63
|
+
| `provider` | endpoint owner (e.g. `openai`, `volcengine`) | the only mandatory field |
|
|
64
|
+
| `aliases` | other names for the same model, incl. aggregator spellings | name matching ignores case, dots, hyphens: `glm-5.3` = `glm5.3` = `GLM5.3` |
|
|
65
|
+
| `context_window`, `max_output` | token limits | |
|
|
66
|
+
| `tool_call`, `reasoning`, `structured_output`, `attachment` | capability booleans | |
|
|
67
|
+
| `modalities` | `{"input": [...], "output": [...]}` | |
|
|
68
|
+
| `open_weights` | weights publicly available | |
|
|
69
|
+
| `cost` | `{"input_per_mtok", "output_per_mtok", "cache_read_per_mtok"}` | **USD per MTok, always** |
|
|
70
|
+
| `quota_tier` | `free_forever` / `free_daily` / `paid` | manual, never auto-filled |
|
|
71
|
+
| `release_date`, `last_updated` | `YYYY-MM-DD` or `YYYY-MM` | freshness hints |
|
|
72
|
+
| `family` | model family | |
|
|
73
|
+
| `quality_hint` | 1-5 subjective prior | the ONLY subjective field, manual |
|
|
74
|
+
|
|
75
|
+
### Hard rules
|
|
76
|
+
|
|
77
|
+
1. **Single file < 1 MB.**
|
|
78
|
+
2. **ABSENT == null.** Unknown facts are omitted (never `null` in the file,
|
|
79
|
+
never a default). Consumers use `.get()` and treat absence as unknown.
|
|
80
|
+
3. **Facts only** — except `quality_hint`, which is clearly marked subjective
|
|
81
|
+
and ignorable.
|
|
82
|
+
4. **USD per MTok, always.** Any other currency/unit never enters the table.
|
|
83
|
+
5. **Fields are append-only.** Semantics never change within a
|
|
84
|
+
`schema_version`; breaking changes bump it. Consumers ignore unknown
|
|
85
|
+
fields.
|
|
86
|
+
|
|
87
|
+
The full standard: [schema/model-registry.schema.json](schema/model-registry.schema.json).
|
|
88
|
+
|
|
89
|
+
## Consume it
|
|
90
|
+
|
|
91
|
+
Fetch the JSON from this repo (raw URL / CDN) at whatever cadence you like,
|
|
92
|
+
then decide with your own rules:
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
import json, urllib.request
|
|
96
|
+
|
|
97
|
+
table = json.load(urllib.request.urlopen(
|
|
98
|
+
"https://raw.githubusercontent.com/hsliuping/Facet/main/registry/model-registry.json"))
|
|
99
|
+
|
|
100
|
+
candidates = [
|
|
101
|
+
(key, rec) for key, rec in table["models"].items()
|
|
102
|
+
if (rec.get("context_window") or 0) >= 200_000 # absent == unknown
|
|
103
|
+
and rec.get("tool_call") is True
|
|
104
|
+
and "image" in (rec.get("modalities") or {}).get("input", [])
|
|
105
|
+
and (rec.get("cost") or {}).get("output_per_mtok", 1e9) <= 2.0
|
|
106
|
+
]
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Or try the demo (stdlib only):
|
|
110
|
+
|
|
111
|
+
```bash
|
|
112
|
+
python examples/pick_model.py --min-context 200000 --tools --image-input --limit 5
|
|
113
|
+
python examples/pick_model.py claude-sonnet-4.5 # resolve one model + aliases
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Install (pip)
|
|
117
|
+
|
|
118
|
+
The same read → resolve → find logic ships as a tiny package with **zero
|
|
119
|
+
runtime dependencies** (stdlib only):
|
|
120
|
+
|
|
121
|
+
```bash
|
|
122
|
+
pip install facet-models
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
```python
|
|
126
|
+
import facet
|
|
127
|
+
|
|
128
|
+
t = facet.load() # bundled snapshot (package version = table date)
|
|
129
|
+
t = facet.load("path/to/table.json") # explicit local path
|
|
130
|
+
t = facet.load(refresh=True) # fetch the latest table (see below)
|
|
131
|
+
|
|
132
|
+
facet.resolve(t, "glm-5.3") # -> "alibaba-cn/glm-5.3"
|
|
133
|
+
facet.find(t, tool_call=True, min_context=200_000, image_input=True,
|
|
134
|
+
max_output_price=2.0, provider="zhipuai", limit=10)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
- The wheel bundles a snapshot of the table; **the package version is the
|
|
138
|
+
snapshot date** (`2026.9.0` = the September 2026 table). Install and use
|
|
139
|
+
offline; upgrade the package or `load(refresh=True)` for freshness.
|
|
140
|
+
- Refresh URL resolution: `url=` argument → `FACET_TABLE_URL` env var →
|
|
141
|
+
built-in default (the raw table on this repo's main). Failures raise —
|
|
142
|
+
never a silent fallback to stale facts.
|
|
143
|
+
- Fetching the JSON directly (below) stays fully supported — the package is a
|
|
144
|
+
convenience, not a lock-in.
|
|
145
|
+
|
|
146
|
+
CLI: `facet "glm-5.3"`, `facet --tools --min-context 200000 --limit 5`.
|
|
147
|
+
|
|
148
|
+
### Integration contract: three names, three layers
|
|
149
|
+
|
|
150
|
+
A model carries three different names across your stack. Keep them apart:
|
|
151
|
+
|
|
152
|
+
| Name | Example | Lives in |
|
|
153
|
+
|---|---|---|
|
|
154
|
+
| facet key | `zhipuai/glm-5.3` | your scheduler: selection, logs, quota, audit |
|
|
155
|
+
| wire name | `rec.model_id` (request body `model`) | the access layer |
|
|
156
|
+
| gateway name | whatever your one-api/new-api deployment lists in `/v1/models` | derived at startup, never configured |
|
|
157
|
+
|
|
158
|
+
The table record **is the handoff**: pass (key, provider, model_id, aliases)
|
|
159
|
+
from the scheduler to the access layer. The access layer picks the adapter and
|
|
160
|
+
credentials by `provider`, and `model_id` goes into the request body.
|
|
161
|
+
|
|
162
|
+
Gateway channels need **no mapping config** — the gateway already knows its
|
|
163
|
+
own names (`GET /v1/models`); derive the mapping at startup with the resolver
|
|
164
|
+
you already have (it tolerates spelling drift by design):
|
|
165
|
+
|
|
166
|
+
```python
|
|
167
|
+
names = [m["id"] for m in get(f"{GW_URL}/v1/models").json()["data"]]
|
|
168
|
+
wire = {name: facet.resolve(t, name) for name in names} # gateway name -> facet key
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
The one convention that makes this work: keep the vendor's original model
|
|
172
|
+
names on the gateway (one-api/new-api do by default). A name that resolves to
|
|
173
|
+
`None` was invented by the gateway admin — fix it on the gateway side, not
|
|
174
|
+
with config.
|
|
175
|
+
|
|
176
|
+
## Maintain it
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
python tools/sync_models_dev.py # models.dev -> table (weekly, or on demand)
|
|
180
|
+
python tools/validate_registry.py # quality gate (size, nulls, shapes, counts)
|
|
181
|
+
python -m unittest discover -s tests # unit tests
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
A GitHub Action (`sync.yml`) refreshes the table weekly and opens a PR.
|
|
185
|
+
Manual annotations (`quota_tier`, `quality_hint`) survive refreshes
|
|
186
|
+
automatically. Sources: [models.dev](https://models.dev) (primary, widest
|
|
187
|
+
provider coverage) + [OpenRouter](https://openrouter.ai/api/v1/models)
|
|
188
|
+
(secondary, fills capability gaps — notably `structured_output`). Capability
|
|
189
|
+
fields may be borrowed across channels of the same model (fill-only, never
|
|
190
|
+
overwritten); prices are never borrowed since channel pricing differs. No
|
|
191
|
+
benchmark scores — those are judgments, not facts; add your own via
|
|
192
|
+
`quality_hint`.
|
|
193
|
+
|
|
194
|
+
## Verify claims (optional)
|
|
195
|
+
|
|
196
|
+
Everything in the table is an upstream *claim*, never a measurement.
|
|
197
|
+
`tools/verify_claims.py` calls a model for real and checks whether its declared
|
|
198
|
+
capabilities hold — tool calling, structured output, reasoning traces, and
|
|
199
|
+
image input. Results land in `reports/verify-results.json` (match / mismatch /
|
|
200
|
+
discovery / inconclusive) and are **never written back to the table**: the
|
|
201
|
+
registry stays a pure claims aggregation, and humans decide what to do with
|
|
202
|
+
contradictions.
|
|
203
|
+
|
|
204
|
+
```bash
|
|
205
|
+
python tools/verify_claims.py gpt-5 --dry-run # plan only, no network
|
|
206
|
+
python tools/verify_claims.py gpt-5 # resolve by name or alias
|
|
207
|
+
python tools/verify_claims.py --provider zhipuai # cheapest models first
|
|
208
|
+
python tools/verify_claims.py --base-url http://localhost:1234/v1 --api-key ... local-model
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
The table keeps ONE record per model identity (the dedup winner), but the
|
|
212
|
+
same model is often served by several vendors — and capability differs per
|
|
213
|
+
channel. Qualify the vendor to pin the endpoint: `volcengine/glm-5.3`,
|
|
214
|
+
`zhipuai/glm-5.3` and `alibaba-cn/glm-5.3` test the same identity at
|
|
215
|
+
different vendors' endpoints (declared facts come from the table record and
|
|
216
|
+
are traced via `table_key` in the report). A bare name tests the winner's
|
|
217
|
+
channel.
|
|
218
|
+
|
|
219
|
+
Bring your own API key (environment variables — `OPENAI_API_KEY`,
|
|
220
|
+
`ZHIPU_API_KEY`, `ARK_API_KEY`, ...; or `--api-key`). Keys are never stored in
|
|
221
|
+
reports. First-party providers are built in; anything else takes
|
|
222
|
+
`--base-url --protocol`. Probes cost a few hundred tokens per model;
|
|
223
|
+
`--max-models` (default 20) caps `--provider` scans. Found a mismatch? Open an
|
|
224
|
+
issue with the report attached, or fix the row via `manual-overrides.json`.
|
|
225
|
+
|
|
226
|
+
## Non-goals
|
|
227
|
+
|
|
228
|
+
No routing, no API keys, no telemetry, no per-request ranking service, no
|
|
229
|
+
benchmark aggregation. If you need those, build them on the table.
|
|
230
|
+
|
|
231
|
+
## Governance
|
|
232
|
+
|
|
233
|
+
MIT licensed. Contributions under the CLA in [CLA.md](CLA.md). Process in
|
|
234
|
+
[CONTRIBUTING.md](CONTRIBUTING.md).
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# Facet
|
|
2
|
+
|
|
3
|
+
**English** | [简体中文](README.zh-CN.md)
|
|
4
|
+
|
|
5
|
+
**Facet answers one question for your application: "for this task, which model should I use?"**
|
|
6
|
+
|
|
7
|
+
It is not a router. It is a **facts table** — a single JSON file describing
|
|
8
|
+
the capabilities, limits, and prices of ~2,400 models across 217 providers —
|
|
9
|
+
plus the tools that keep the table fresh and a demo consumer. Your project
|
|
10
|
+
reads the table, applies its own business rules, and picks a model.
|
|
11
|
+
|
|
12
|
+
```
|
|
13
|
+
models.dev (primary, 217 providers) OpenRouter /api/v1/models (secondary)
|
|
14
|
+
│ │
|
|
15
|
+
└──────────── weekly sync ───────────────┘
|
|
16
|
+
│ tools/sync_models_dev.py
|
|
17
|
+
▼
|
|
18
|
+
registry/model-registry.json ← the deliverable: one file, < 1 MB, zero deps
|
|
19
|
+
│
|
|
20
|
+
├── your service (fetch the JSON, filter, decide)
|
|
21
|
+
└── examples/pick_model.py (reference consumer / demo)
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Why a table instead of a router?
|
|
25
|
+
|
|
26
|
+
- Routers encode *someone else's* policy. Your business rules are yours.
|
|
27
|
+
- A router is a dependency; a JSON file is data. Fetch it, vendor it, or copy
|
|
28
|
+
the fields you need.
|
|
29
|
+
- Facts change weekly (prices, limits, new models). Policy changes daily. We
|
|
30
|
+
ship the part that changes weekly.
|
|
31
|
+
|
|
32
|
+
## The table
|
|
33
|
+
|
|
34
|
+
`registry/model-registry.json` — keyed `provider/model_id`, one record per
|
|
35
|
+
model identity, deduped across providers (aggregator copies lose to
|
|
36
|
+
first-party ones; ties prefer richer records).
|
|
37
|
+
|
|
38
|
+
| Field | Meaning | Notes |
|
|
39
|
+
|---|---|---|
|
|
40
|
+
| `provider` | endpoint owner (e.g. `openai`, `volcengine`) | the only mandatory field |
|
|
41
|
+
| `aliases` | other names for the same model, incl. aggregator spellings | name matching ignores case, dots, hyphens: `glm-5.3` = `glm5.3` = `GLM5.3` |
|
|
42
|
+
| `context_window`, `max_output` | token limits | |
|
|
43
|
+
| `tool_call`, `reasoning`, `structured_output`, `attachment` | capability booleans | |
|
|
44
|
+
| `modalities` | `{"input": [...], "output": [...]}` | |
|
|
45
|
+
| `open_weights` | weights publicly available | |
|
|
46
|
+
| `cost` | `{"input_per_mtok", "output_per_mtok", "cache_read_per_mtok"}` | **USD per MTok, always** |
|
|
47
|
+
| `quota_tier` | `free_forever` / `free_daily` / `paid` | manual, never auto-filled |
|
|
48
|
+
| `release_date`, `last_updated` | `YYYY-MM-DD` or `YYYY-MM` | freshness hints |
|
|
49
|
+
| `family` | model family | |
|
|
50
|
+
| `quality_hint` | 1-5 subjective prior | the ONLY subjective field, manual |
|
|
51
|
+
|
|
52
|
+
### Hard rules
|
|
53
|
+
|
|
54
|
+
1. **Single file < 1 MB.**
|
|
55
|
+
2. **ABSENT == null.** Unknown facts are omitted (never `null` in the file,
|
|
56
|
+
never a default). Consumers use `.get()` and treat absence as unknown.
|
|
57
|
+
3. **Facts only** — except `quality_hint`, which is clearly marked subjective
|
|
58
|
+
and ignorable.
|
|
59
|
+
4. **USD per MTok, always.** Any other currency/unit never enters the table.
|
|
60
|
+
5. **Fields are append-only.** Semantics never change within a
|
|
61
|
+
`schema_version`; breaking changes bump it. Consumers ignore unknown
|
|
62
|
+
fields.
|
|
63
|
+
|
|
64
|
+
The full standard: [schema/model-registry.schema.json](schema/model-registry.schema.json).
|
|
65
|
+
|
|
66
|
+
## Consume it
|
|
67
|
+
|
|
68
|
+
Fetch the JSON from this repo (raw URL / CDN) at whatever cadence you like,
|
|
69
|
+
then decide with your own rules:
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import json, urllib.request
|
|
73
|
+
|
|
74
|
+
table = json.load(urllib.request.urlopen(
|
|
75
|
+
"https://raw.githubusercontent.com/hsliuping/Facet/main/registry/model-registry.json"))
|
|
76
|
+
|
|
77
|
+
candidates = [
|
|
78
|
+
(key, rec) for key, rec in table["models"].items()
|
|
79
|
+
if (rec.get("context_window") or 0) >= 200_000 # absent == unknown
|
|
80
|
+
and rec.get("tool_call") is True
|
|
81
|
+
and "image" in (rec.get("modalities") or {}).get("input", [])
|
|
82
|
+
and (rec.get("cost") or {}).get("output_per_mtok", 1e9) <= 2.0
|
|
83
|
+
]
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Or try the demo (stdlib only):
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
python examples/pick_model.py --min-context 200000 --tools --image-input --limit 5
|
|
90
|
+
python examples/pick_model.py claude-sonnet-4.5 # resolve one model + aliases
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
## Install (pip)
|
|
94
|
+
|
|
95
|
+
The same read → resolve → find logic ships as a tiny package with **zero
|
|
96
|
+
runtime dependencies** (stdlib only):
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
pip install facet-models
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
```python
|
|
103
|
+
import facet
|
|
104
|
+
|
|
105
|
+
t = facet.load() # bundled snapshot (package version = table date)
|
|
106
|
+
t = facet.load("path/to/table.json") # explicit local path
|
|
107
|
+
t = facet.load(refresh=True) # fetch the latest table (see below)
|
|
108
|
+
|
|
109
|
+
facet.resolve(t, "glm-5.3") # -> "alibaba-cn/glm-5.3"
|
|
110
|
+
facet.find(t, tool_call=True, min_context=200_000, image_input=True,
|
|
111
|
+
max_output_price=2.0, provider="zhipuai", limit=10)
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
- The wheel bundles a snapshot of the table; **the package version is the
|
|
115
|
+
snapshot date** (`2026.9.0` = the September 2026 table). Install and use
|
|
116
|
+
offline; upgrade the package or `load(refresh=True)` for freshness.
|
|
117
|
+
- Refresh URL resolution: `url=` argument → `FACET_TABLE_URL` env var →
|
|
118
|
+
built-in default (the raw table on this repo's main). Failures raise —
|
|
119
|
+
never a silent fallback to stale facts.
|
|
120
|
+
- Fetching the JSON directly (below) stays fully supported — the package is a
|
|
121
|
+
convenience, not a lock-in.
|
|
122
|
+
|
|
123
|
+
CLI: `facet "glm-5.3"`, `facet --tools --min-context 200000 --limit 5`.
|
|
124
|
+
|
|
125
|
+
### Integration contract: three names, three layers
|
|
126
|
+
|
|
127
|
+
A model carries three different names across your stack. Keep them apart:
|
|
128
|
+
|
|
129
|
+
| Name | Example | Lives in |
|
|
130
|
+
|---|---|---|
|
|
131
|
+
| facet key | `zhipuai/glm-5.3` | your scheduler: selection, logs, quota, audit |
|
|
132
|
+
| wire name | `rec.model_id` (request body `model`) | the access layer |
|
|
133
|
+
| gateway name | whatever your one-api/new-api deployment lists in `/v1/models` | derived at startup, never configured |
|
|
134
|
+
|
|
135
|
+
The table record **is the handoff**: pass (key, provider, model_id, aliases)
|
|
136
|
+
from the scheduler to the access layer. The access layer picks the adapter and
|
|
137
|
+
credentials by `provider`, and `model_id` goes into the request body.
|
|
138
|
+
|
|
139
|
+
Gateway channels need **no mapping config** — the gateway already knows its
|
|
140
|
+
own names (`GET /v1/models`); derive the mapping at startup with the resolver
|
|
141
|
+
you already have (it tolerates spelling drift by design):
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
names = [m["id"] for m in get(f"{GW_URL}/v1/models").json()["data"]]
|
|
145
|
+
wire = {name: facet.resolve(t, name) for name in names} # gateway name -> facet key
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The one convention that makes this work: keep the vendor's original model
|
|
149
|
+
names on the gateway (one-api/new-api do by default). A name that resolves to
|
|
150
|
+
`None` was invented by the gateway admin — fix it on the gateway side, not
|
|
151
|
+
with config.
|
|
152
|
+
|
|
153
|
+
## Maintain it
|
|
154
|
+
|
|
155
|
+
```bash
|
|
156
|
+
python tools/sync_models_dev.py # models.dev -> table (weekly, or on demand)
|
|
157
|
+
python tools/validate_registry.py # quality gate (size, nulls, shapes, counts)
|
|
158
|
+
python -m unittest discover -s tests # unit tests
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
A GitHub Action (`sync.yml`) refreshes the table weekly and opens a PR.
|
|
162
|
+
Manual annotations (`quota_tier`, `quality_hint`) survive refreshes
|
|
163
|
+
automatically. Sources: [models.dev](https://models.dev) (primary, widest
|
|
164
|
+
provider coverage) + [OpenRouter](https://openrouter.ai/api/v1/models)
|
|
165
|
+
(secondary, fills capability gaps — notably `structured_output`). Capability
|
|
166
|
+
fields may be borrowed across channels of the same model (fill-only, never
|
|
167
|
+
overwritten); prices are never borrowed since channel pricing differs. No
|
|
168
|
+
benchmark scores — those are judgments, not facts; add your own via
|
|
169
|
+
`quality_hint`.
|
|
170
|
+
|
|
171
|
+
## Verify claims (optional)
|
|
172
|
+
|
|
173
|
+
Everything in the table is an upstream *claim*, never a measurement.
|
|
174
|
+
`tools/verify_claims.py` calls a model for real and checks whether its declared
|
|
175
|
+
capabilities hold — tool calling, structured output, reasoning traces, and
|
|
176
|
+
image input. Results land in `reports/verify-results.json` (match / mismatch /
|
|
177
|
+
discovery / inconclusive) and are **never written back to the table**: the
|
|
178
|
+
registry stays a pure claims aggregation, and humans decide what to do with
|
|
179
|
+
contradictions.
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
python tools/verify_claims.py gpt-5 --dry-run # plan only, no network
|
|
183
|
+
python tools/verify_claims.py gpt-5 # resolve by name or alias
|
|
184
|
+
python tools/verify_claims.py --provider zhipuai # cheapest models first
|
|
185
|
+
python tools/verify_claims.py --base-url http://localhost:1234/v1 --api-key ... local-model
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
The table keeps ONE record per model identity (the dedup winner), but the
|
|
189
|
+
same model is often served by several vendors — and capability differs per
|
|
190
|
+
channel. Qualify the vendor to pin the endpoint: `volcengine/glm-5.3`,
|
|
191
|
+
`zhipuai/glm-5.3` and `alibaba-cn/glm-5.3` test the same identity at
|
|
192
|
+
different vendors' endpoints (declared facts come from the table record and
|
|
193
|
+
are traced via `table_key` in the report). A bare name tests the winner's
|
|
194
|
+
channel.
|
|
195
|
+
|
|
196
|
+
Bring your own API key (environment variables — `OPENAI_API_KEY`,
|
|
197
|
+
`ZHIPU_API_KEY`, `ARK_API_KEY`, ...; or `--api-key`). Keys are never stored in
|
|
198
|
+
reports. First-party providers are built in; anything else takes
|
|
199
|
+
`--base-url --protocol`. Probes cost a few hundred tokens per model;
|
|
200
|
+
`--max-models` (default 20) caps `--provider` scans. Found a mismatch? Open an
|
|
201
|
+
issue with the report attached, or fix the row via `manual-overrides.json`.
|
|
202
|
+
|
|
203
|
+
## Non-goals
|
|
204
|
+
|
|
205
|
+
No routing, no API keys, no telemetry, no per-request ranking service, no
|
|
206
|
+
benchmark aggregation. If you need those, build them on the table.
|
|
207
|
+
|
|
208
|
+
## Governance
|
|
209
|
+
|
|
210
|
+
MIT licensed. Contributions under the CLA in [CLA.md](CLA.md). Process in
|
|
211
|
+
[CONTRIBUTING.md](CONTRIBUTING.md).
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "facet-models"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Thin fact client for the Facet model registry: load the table, resolve names, find candidates. Zero runtime dependencies."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "Facet contributors" }]
|
|
13
|
+
keywords = ["llm", "model-registry", "model-selection", "ai", "facts"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"Operating System :: OS Independent",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3.10",
|
|
20
|
+
"Programming Language :: Python :: 3.11",
|
|
21
|
+
"Programming Language :: Python :: 3.12",
|
|
22
|
+
"Programming Language :: Python :: 3.13",
|
|
23
|
+
"Topic :: Software Development :: Libraries",
|
|
24
|
+
"Typing :: Typed",
|
|
25
|
+
]
|
|
26
|
+
|
|
27
|
+
[project.urls]
|
|
28
|
+
Homepage = "https://github.com/hsliuping/Facet"
|
|
29
|
+
|
|
30
|
+
[project.scripts]
|
|
31
|
+
facet = "facet.cli:main"
|
|
32
|
+
|
|
33
|
+
[tool.setuptools]
|
|
34
|
+
package-dir = { "" = "src" }
|
|
35
|
+
|
|
36
|
+
[tool.setuptools.packages.find]
|
|
37
|
+
where = ["src"]
|
|
38
|
+
|
|
39
|
+
[tool.setuptools.package-data]
|
|
40
|
+
facet = ["py.typed", "data/model-registry.json"]
|
|
41
|
+
|
|
42
|
+
[tool.setuptools.dynamic]
|
|
43
|
+
version = { attr = "facet._version.__version__" }
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""facet-models: a thin fact client for the Facet model registry.
|
|
2
|
+
|
|
3
|
+
Facts only — load the table, resolve names, filter and rank. Decisions stay
|
|
4
|
+
with the caller. Zero runtime dependencies (stdlib only).
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from ._find import check, find, rank
|
|
8
|
+
from ._identity import build_lookup, identity, resolve
|
|
9
|
+
from ._table import BUNDLED_TABLE, DEFAULT_TABLE_URL, load
|
|
10
|
+
|
|
11
|
+
try: # written by tools/build_package.py; absent in a raw source tree
|
|
12
|
+
from ._version import __version__
|
|
13
|
+
except ImportError: # pragma: no cover
|
|
14
|
+
__version__ = "0.0.0.dev0"
|
|
15
|
+
|
|
16
|
+
__all__ = [
|
|
17
|
+
"BUNDLED_TABLE",
|
|
18
|
+
"DEFAULT_TABLE_URL",
|
|
19
|
+
"__version__",
|
|
20
|
+
"build_lookup",
|
|
21
|
+
"check",
|
|
22
|
+
"find",
|
|
23
|
+
"identity",
|
|
24
|
+
"load",
|
|
25
|
+
"rank",
|
|
26
|
+
"resolve",
|
|
27
|
+
]
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""Filter + rank: hard requirements AND together; absence counts as unknown.
|
|
2
|
+
|
|
3
|
+
Same semantics as examples/pick_model.py check + rank. A fact that is ABSENT
|
|
4
|
+
can never *satisfy* a requirement, and an unknown price sorts last (price 0 is
|
|
5
|
+
treated as unknown — free-plan mirrors don't expose real pricing).
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def check(
|
|
12
|
+
rec: dict,
|
|
13
|
+
*,
|
|
14
|
+
min_context: int | None = None,
|
|
15
|
+
max_input_price: float | None = None,
|
|
16
|
+
max_output_price: float | None = None,
|
|
17
|
+
tool_call: bool = False,
|
|
18
|
+
reasoning: bool = False,
|
|
19
|
+
json_output: bool = False,
|
|
20
|
+
image_input: bool = False,
|
|
21
|
+
provider: str | None = None,
|
|
22
|
+
) -> list[str]:
|
|
23
|
+
"""Return the list of failed requirements (empty = the record qualifies)."""
|
|
24
|
+
failed: list[str] = []
|
|
25
|
+
if min_context is not None and (rec.get("context_window") or 0) < min_context:
|
|
26
|
+
failed.append(f"context>={min_context}")
|
|
27
|
+
for want, field in ((tool_call, "tool_call"), (reasoning, "reasoning"), (json_output, "structured_output")):
|
|
28
|
+
if want and rec.get(field) is not True:
|
|
29
|
+
failed.append(field)
|
|
30
|
+
if image_input and "image" not in (rec.get("modalities") or {}).get("input", []):
|
|
31
|
+
failed.append("image-input")
|
|
32
|
+
if provider is not None and rec.get("provider") != provider:
|
|
33
|
+
failed.append(f"provider={provider}")
|
|
34
|
+
cost = rec.get("cost") or {}
|
|
35
|
+
if max_input_price is not None:
|
|
36
|
+
p = cost.get("input_per_mtok")
|
|
37
|
+
if p is None or p > max_input_price:
|
|
38
|
+
failed.append(f"input-price<={max_input_price}")
|
|
39
|
+
if max_output_price is not None:
|
|
40
|
+
p = cost.get("output_per_mtok")
|
|
41
|
+
if p is None or p > max_output_price:
|
|
42
|
+
failed.append(f"output-price<={max_output_price}")
|
|
43
|
+
return failed
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def rank(entries: list[tuple[str, dict]]) -> list[tuple[str, dict]]:
|
|
47
|
+
"""Cheapest output first; unknown price last (0 == unknown); bigger context wins ties."""
|
|
48
|
+
def key(item: tuple[str, dict]):
|
|
49
|
+
_, rec = item
|
|
50
|
+
out = (rec.get("cost") or {}).get("output_per_mtok")
|
|
51
|
+
if not out:
|
|
52
|
+
out = None
|
|
53
|
+
return (out is None, out or 0.0, -(rec.get("context_window") or 0))
|
|
54
|
+
|
|
55
|
+
return sorted(entries, key=key)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
def find(
|
|
59
|
+
table: dict,
|
|
60
|
+
*,
|
|
61
|
+
min_context: int | None = None,
|
|
62
|
+
max_input_price: float | None = None,
|
|
63
|
+
max_output_price: float | None = None,
|
|
64
|
+
tool_call: bool = False,
|
|
65
|
+
reasoning: bool = False,
|
|
66
|
+
json_output: bool = False,
|
|
67
|
+
image_input: bool = False,
|
|
68
|
+
provider: str | None = None,
|
|
69
|
+
limit: int | None = 10,
|
|
70
|
+
) -> list[tuple[str, dict]]:
|
|
71
|
+
"""Filter the table by hard requirements and rank what survives.
|
|
72
|
+
|
|
73
|
+
Returns [(key, rec), ...] — cheapest output price first, unknown prices
|
|
74
|
+
last, ties broken by larger context window. Every filter ANDs; an absent
|
|
75
|
+
fact never qualifies.
|
|
76
|
+
"""
|
|
77
|
+
kwargs = dict(
|
|
78
|
+
min_context=min_context,
|
|
79
|
+
max_input_price=max_input_price,
|
|
80
|
+
max_output_price=max_output_price,
|
|
81
|
+
tool_call=tool_call,
|
|
82
|
+
reasoning=reasoning,
|
|
83
|
+
json_output=json_output,
|
|
84
|
+
image_input=image_input,
|
|
85
|
+
provider=provider,
|
|
86
|
+
)
|
|
87
|
+
entries = [(k, r) for k, r in table["models"].items() if not check(r, **kwargs)]
|
|
88
|
+
entries = rank(entries)
|
|
89
|
+
return entries if limit is None else entries[:limit]
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Name identity: normalization, lookup build, resolve.
|
|
2
|
+
|
|
3
|
+
Same logic as examples/pick_model.py (copied, not imported — tools/ scripts
|
|
4
|
+
stay independently runnable).
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import re
|
|
10
|
+
|
|
11
|
+
# Same normalization as tools/sync_models_dev.py: case, dots and hyphens are
|
|
12
|
+
# presentation, they never distinguish capabilities ('glm-5.3' == 'glm5.3').
|
|
13
|
+
_PREFIX_RE = re.compile(r"^[a-z0-9_~-]+/")
|
|
14
|
+
_NON_ALNUM_RE = re.compile(r"[^a-z0-9]+")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def identity(name: str) -> str:
|
|
18
|
+
"""'OpenRouter/Anthropic/Claude-Sonnet-4.5' -> 'claudesonnet45'."""
|
|
19
|
+
return _NON_ALNUM_RE.sub("", _PREFIX_RE.sub("", name.strip().lower()))
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def build_lookup(table: dict) -> dict[str, str]:
|
|
23
|
+
"""normalized name -> table key. Canonical keys first, then aliases."""
|
|
24
|
+
lookup: dict[str, str] = {}
|
|
25
|
+
for key, rec in table["models"].items():
|
|
26
|
+
bare = key.split("/", 1)[1]
|
|
27
|
+
lookup.setdefault(identity(bare), key)
|
|
28
|
+
for alias in rec.get("aliases", []):
|
|
29
|
+
lookup.setdefault(identity(alias), key)
|
|
30
|
+
return lookup
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def resolve(table: dict, name: str) -> str | None:
|
|
34
|
+
"""Resolve a user-supplied name or alias to its table key (None if unknown)."""
|
|
35
|
+
return build_lookup(table).get(identity(name))
|