Files
Bundle OKF 0.2 · 7 conceitos · smoochy/openrouter-model-list
Open source Repository Open in the app JSON README (API)
About
# Files
- [Quickstart](quickstart.md) - Get started with the repository for consumers and contributors. Provides an overview of the model lists, how to use them, and how to run the generation locally.
- [Source Map](source-map.md) - Maps documentation concepts to their canonical source files, symbols, and test coverage for the openrouter-model-list pipeline.
# Directories
- [architecture](architecture/)
- [configuration](configuration/)
- [operations](operations/)
- [testing](testing/)
- [workflows](workflows/)
Details
- Kind
- OKF bundles
- Topic
- Maps, weather & travel
- Publisher
- smoochy
- Origin
- okf_github
- Category
- dados
- Version
- 0.2
- Open pull requests
- 1
- Last push
- 2026-09-08T08:02:13Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-09-08 09:02:43
- Updated
- 2026-09-08 09:02:43
- Origin id
smoochy/openrouter-model-list:openwiki/index.md
README
# openrouter-model-list
[](https://github.com/RichardLitt/standard-readme)
[](https://github.com/smoochy/openrouter-model-list/actions)
[](https://coindrop.to/smoochy) [](https://www.buymeacoffee.com/smoochy84) [](https://ko-fi.com/smoochy)
> Daily-refreshed, scored lists of free OpenRouter models for different use cases. Consumers point at the file matching their requirements; the workflow keeps it current without manual upkeep.
This repository publishes `models-mengram.json`: a ranked, scored set of free
OpenRouter models that meet mengram's extraction requirements (context
length, output tokens, structured-output support). A scheduled GitHub
Actions workflow re-fetches the OpenRouter catalog, probes each candidate
model, and rewrites `models-mengram.json` so consumers always have a working
fallback list without manual upkeep.
If this project saves you time or helps your setup, you can support ongoing
maintenance via Coindrop, Ko-fi, or Buy Me a Coffee.
## Table of Contents
- [Background](#background)
- [How It Works](#how-it-works)
- [Configuration](#configuration)
- [Output Format](#output-format)
- [Consuming](#consuming)
- [When the Workflow Runs](#when-the-workflow-runs)
- [Anthropic Model List](#anthropic-model-list)
- [Probe History](#probe-history)
- [Transparency](#transparency)
- [Security](#security)
- [Maintainers](#maintainers)
- [Contributing](#contributing)
- [License](#license)
## Background
mengram's self-hosted LLM config previously pointed at a single hardcoded
free OpenRouter model. Free models on OpenRouter occasionally get retired or
renamed, which made that configuration brittle and caused silent extraction
failures. This repository provides a maintained, automatically updated
fallback list so mengram can select from several known-good free models
instead of relying on one.
## Available Model Lists
| File | Use Case | Key Requirement |
| ---- | -------- | --------------- |
| [`models-mengram.json`](models-mengram.json) | [mengram](https://github.com/alibaizhanov/mengram) knowledge extraction | Structured output (`response_format`) support, ≥40k context |
| [`models-yt-summarizer.json`](models-yt-summarizer.json) | [yt-transcript-distiller](https://github.com/smoochy/yt-transcript-distiller) — YouTube transcript summarization | ≥32k context, plain text generation (no structured output required) |
| [`anthropic-models.json`](anthropic-models.json) | [yt-transcript-distiller](https://github.com/smoochy/yt-transcript-distiller) — Claude model selector | List of current Anthropic Claude models (fetched weekly from Anthropic API) |
Each file is independently generated with its own `thresholds-*.yaml` configuration. Point your `model_list_url` at the file matching your use case.
## How It Works
1. Fetch all OpenRouter models and keep the free ones
(`pricing.prompt == "0"` and `pricing.completion == "0"`).
2. Filter the remaining models by `thresholds-mengram.yaml`:
- `min_param_b` — hard floor, never buffered. Parsed from the model id
(e.g. `qwen/qwen3-32b:free` -> 32). Models where no size can be parsed
are excluded unless listed in `allowlist`.
- `min_context_length` / `min_max_output_tokens` — buffered by
`buffer_pct`. If too few models pass, `buffer_pct` is reduced toward 0
until `min_candidate_pool` models pass. A missing or null
`max_completion_tokens` is treated as unknown (not zero) and doesn't by
itself fail this check.
- `require_structured_output` — requires `response_format` or
`structured_outputs` in the model's `supported_parameters`.
- `min_uptime` / `max_latency_ms` — optional post-probe filters, applied to
OpenRouter's aggregated endpoint stats (`uptime` / `latency_ms`, see
[Probe History](#probe-history)). Leave empty to disable.
- `allowlist` — model IDs that always enter the candidate pool, skipping
`min_param_b` and the context/output thresholds, but still subject to
`require_structured_output` (if enabled) — excluded with a warning if
the model doesn't report structured-output support. Still probed and
scored normally. Use this for models known to be suitable whose id
doesn't encode a parseable size (e.g. `openrouter/owl-alpha`).
- `hardallowlist` — model IDs that always enter the candidate pool,
skipping all of the checks above including `require_structured_output`.
Still probed and scored normally. Use this for models known to be
suitable that don't report structured-output support via the catalog
API.
3. For each surviving candidate, fetch OpenRouter's aggregated endpoint stats
(`uptime_last_1d`, `latency_last_30m.p50`) via the `/endpoints` API,
averaged across the model's free endpoints. If no free endpoints are
reported (or the request fails), fall back to a neutral 0.5 uptime and no
latency score, and log a warning.
4. Also probe each candidate once with a 1-token completion request and
record `{timestamp, success, latency_ms}` to `history/<model>.jsonl`
(rolling 30-day window). A failed probe logs a warning. The 30-day success
rate from this history (`own_uptime`) acts as a malus multiplier on the
final score — new models default to a neutral 0.5 malus until they
accumulate 3+ probes.
5. Score each candidate as
`(0.6*uptime + 0.3*latency_norm + 0.1*capability_norm) * own_uptime`
(OpenRouter's uptime matters most, then latency, then context/parameter
size, all multiplied by our own reliability malus) and sort descending
into the output file.
## Configuration
All tuning happens in `thresholds-mengram.yaml`:
```yaml
min_param_b: 28
min_context_length: 40000
min_max_output_tokens: 8000
buffer_pct: 5
require_structured_output: true
min_uptime:
max_latency_ms:
min_candidate_pool: 3
hardallowlist: []
allowlist:
- openrouter/owl-alpha
```
Edit the file and either wait for the next scheduled run or trigger
`workflow_dispatch` manually.
## Output Format
`models-mengram.json`:
```json
{
"generated_at": "2026-06-14T03:00:00Z",
"schema_version": 2,
"models": [
{
"id": "nvidia/nemotron-3-super-120b-a12b:free",
"score": 0.8123,
"context_length": 131072,
"max_output_tokens": 32768,
"uptime": 1.0,
"latency_ms": 842,
"own_uptime": 1.0,
"sanity_ok": true
}
]
}
```
- `uptime` — OpenRouter's aggregated `uptime_last_1d`, averaged across the
model's free endpoints (0-1 fraction). Falls back to 0.5 (neutral) if no
free endpoint stats are available.
- `latency_ms` — OpenRouter's aggregated `latency_last_30m.p50`, averaged
across free endpoints (ms). `null` if unavailable.
- `own_uptime` — our own 30-day rolling sanity-probe success rate (0-1
fraction), used as a malus multiplier on the score. Defaults to 0.5 for new
models with fewer than 3 probes.
- `sanity_ok` — whether today's 1-token sanity probe succeeded.
`schema_version` increments whenever a field is added, removed, or changes
meaning, so consumers can detect incompatible changes.
## Consuming
```
https://raw.githubusercontent.com/smoochy/openrouter-model-list/main/models-mengram.json
```
mengram reads this URL via its `model_list_url` config option and falls back
through the ranked list if the primary model becomes unavailable.
## When the Workflow Runs
`.github/workflows/update-models.yml` runs:
- **Scheduled**: daily at 03:00 UTC
- **Manual**: via `workflow_dispatch`
Each run regenerates the model list files and the per-model probe history under
`history/`, and commits the changes only if something changed.
## Anthropic Model List
`anthropic-models.json` contains the current set of Anthropic Claude models,
fetched weekly from `https://api.anthropic.com/v1/models`. Format:
```json
[
{ "id": "claude-haiku-4-5-20251001", "display_name": "Claude Haiku 4.5", "type": "model", "created_at": 1748995200 },
{ "id": "claude-opus-4-8", "display_name": "Claude Opus 4.8", "type": "model", "created_at": 1749600000 },
{ "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6", "type": "model", "created_at": 1749600000 }
]
```
Only entries with `type == "model"` are included; sorted by `id` ascending. Note: the field is `display_name` (native Anthropic API field name), not `name`.
**Consumers** fetch this list from raw.githubusercontent.com:
```
https://raw.githubusercontent.com/smoochy/openrouter-model-list/main/anthropic-models.json
```
The [update-anthropic-models.yml](.github/workflows/update-anthropic-models.yml) workflow runs
every Tuesday at 03:00 UTC (plus `workflow_dispatch`) and commits only when the list changes.
## Probe History
Each candidate model has a rolling 30-day probe history at
`history/<safe-model-id>.jsonl`, one JSON object per probe
(`{timestamp, success, latency_ms}`). This history feeds `own_uptime`, a
malus multiplier applied to the OpenRouter-derived score (see
[How It Works](#how-it-works)). The optional `min_uptime` / `max_latency_ms`
post-probe filters now apply to OpenRouter's aggregated endpoint stats
(`uptime` / `latency_ms`), not this history.
## Transparency
The code, documentation, and related project materials in this repository
were created and refined with AI assistance. All generated output was
reviewed and adapted before publication.
## Security
- No secrets are committed to the repository
- The workflow uses the `OPENROUTER_API_KEY` repository secret to fetch the
catalog and probe candidate models
- The built-in `GITHUB_TOKEN` is used to commit the model list files and
`history/` updates
## Maintainers
- smoochy
## Contributing
Issues and pull requests are welcome. Keep `thresholds-*.yaml`, the filtering
and scoring code, and this README aligned so the published model list
behavior stays easy to audit.
## License
[MIT](./LICENSE) 2026 [smoochy](https://github.com/smoochy)