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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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,8 @@
1
+ """``python -m facet`` -> the CLI."""
2
+
3
+ import sys
4
+
5
+ from .cli import main
6
+
7
+ if __name__ == "__main__":
8
+ sys.exit(main())
@@ -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))