docs: clarify what meta.modelsInfoUrl points at#22
Conversation
The examples led with a bare relative path (`"modelsInfoUrl": "models"`), which read like a magic keyword and — worse — resolved to a vanilla OpenAI `/v1/models`, which returns sparse data (id/object/owned_by) and none of the fields this plugin maps. So the headline example enriched nothing. Across the top-level README, the package README, and docs/models-info.md: - State plainly that modelsInfoUrl is the HTTP(S) endpoint returning OpenRouter-shaped models JSON. - Lead every example with an absolute URL (OpenRouter's public catalog), removing the "who is `models`?" ambiguity. - Add a callout that a plain OpenAI-compatible /v1/models lacks context_length/pricing, so the URL must serve the richer shape. Docs-only; no code or behavior change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the documentation across README.md, docs/models-info.md, and packages/opencode-models-info/README.md to clarify the usage of the @vymalo/opencode-models-info plugin. Specifically, it highlights that the meta.modelsInfoUrl configuration must point to an endpoint returning OpenRouter-shaped models JSON rather than a standard OpenAI-compatible /v1/models endpoint, which lacks the necessary metadata fields like context length and pricing. The examples have also been updated to use OpenRouter's actual API configuration. There are no review comments to address, and I have no additional feedback to provide.
Emphasize that the plugin cares about the response *shape*, not the *service* — any OpenRouter-compatible endpoint works (self-hosted gateway, LiteLLM proxy, custom metadata route, or OpenRouter itself). - Package README now leads with a "your own gateway" example (relative path) alongside the OpenRouter public-catalog one, and spells out the low compatibility bar: bare top-level array accepted, partial field mapping (emit only what you want enriched). - README + docs/models-info.md reworded so OpenRouter reads as a concrete try-it-now example, not a dependency. Docs-only; no code change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5d3ce5f853
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| } | ||
| ``` | ||
|
|
||
| > **What counts as "compatible"?** Returning the shape below — that's the whole contract. The bar is low: a **bare top-level array** (no `data` wrapper) is accepted, and the mapping is **partial**, so you only need to emit the fields you want enriched (e.g. just `id` + `context_length` + `pricing`). **But note:** a vanilla OpenAI-compatible `/v1/models` returns only `id` / `object` / `owned_by` — *none* of the fields this plugin maps — so pointing `modelsInfoUrl` there fetches successfully and enriches nothing. The endpoint has to actually carry the richer data. |
There was a problem hiding this comment.
When someone follows this guidance and emits only id + context_length + pricing, the context limit will not be enriched: mapOpenRouterEntry only sets limit when both context_length (or top_provider.context_length) and top_provider.max_completion_tokens are present, because OpenCode requires both limit fields. Please include top_provider.max_completion_tokens in the minimal example or clarify that context_length alone is ignored for limit enrichment.
Useful? React with 👍 / 👎.
| ## Usage | ||
|
|
||
| For every provider you want enriched, add `options.meta.modelsInfoUrl`: | ||
| `meta.modelsInfoUrl` is **the HTTP(S) endpoint that returns OpenRouter-shaped models JSON** (see [Expected response shape](#expected-response-shape-openrouter)). The plugin cares about the *response shape*, not the *service* — **any OpenRouter-compatible endpoint works**: OpenRouter itself, a self-hosted gateway, a LiteLLM proxy, or a dedicated metadata route on your own API. `modelsInfoUrl` can be an absolute URL or a path resolved against `options.baseURL`. |
There was a problem hiding this comment.
A stock LiteLLM proxy is not enough to satisfy this contract: the plugin only normalizes a bare array or a data array and then reads OpenRouter fields like top-level context_length, pricing, and top_provider.max_completion_tokens, while LiteLLM's documented /v1/models is OpenAI-style sparse and its richer /model/info nests metadata differently. Users who take this line literally and point modelsInfoUrl at LiteLLM will fetch successfully but get no enrichment, so this should say a proxy must explicitly mirror the OpenRouter schema (or drop LiteLLM from the examples).
Useful? React with 👍 / 👎.
| "baseURL": "https://openrouter.ai/api/v1", | ||
| "meta": { "modelsInfoUrl": "https://openrouter.ai/api/v1/models" } | ||
| }, | ||
| "models": { "anthropic/claude-3.5-sonnet": {} } |
There was a problem hiding this comment.
With the current OpenRouter catalog this exact id is no longer returned, and enrichProvider only enriches when the configured model key (or explicit id) exactly matches a catalog entry. Copying this advertised “try right now” example therefore fetches the public catalog but leaves anthropic/claude-3.5-sonnet unchanged; please use a currently listed model id or an alias that the catalog actually returns.
Useful? React with 👍 / 👎.
Previous revision leaned too far the other way — leading examples used OpenRouter's public catalog URL and "try it right now" framing, which reads as recommending OpenRouter as the thing to use. The plugin targets your own provider; OpenRouter is just the common name for the response shape. - All config examples now use a generic `my-provider` / `https://api.example.com/v1` with a relative `modelsInfoUrl: "models"`. - Removed the openrouter.ai config blocks/URLs from README, package README, and docs/models-info.md. - "OpenRouter" now appears only as the name of the JSON shape ("commonly called the OpenRouter shape … the plugin has no dependency on OpenRouter and never contacts it"). Docs-only; no code change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7ef934d127
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "baseURL": "https://api.example.com/v1", | ||
| "meta": { | ||
| "modelsInfoUrl": "models/info", | ||
| "modelsInfoUrl": "models", |
There was a problem hiding this comment.
For the shown @ai-sdk/openai-compatible provider with baseURL: "https://api.example.com/v1", this relative value resolves to https://api.example.com/v1/models (the README notes this just below), which is exactly the sparse OpenAI-compatible /v1/models shape the new warning says will fetch successfully but enrich nothing unless the server has nonstandard OpenRouter fields. Since this is the primary copy-paste example, users with a normal provider will enable the plugin and see no metadata; use a dedicated metadata route or an absolute OpenRouter-shaped catalog URL in the example.
Useful? React with 👍 / 👎.
Switch the primary config examples from the relative `"models"` to the unambiguous absolute `"https://api.example.com/v1/models"`. The relative form is still documented (and the URL-resolution table kept) as a secondary option, but the headline examples no longer make the reader infer what the path resolves to. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 20b4cbb651
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| "oauth2": { "issuer": "https://auth.example.com", "clientId": "opencode-client", "scopes": ["openid", "offline_access"] }, | ||
| "meta": { "modelsInfoUrl": "models" } | ||
| } | ||
| "meta": { "modelsInfoUrl": "https://api.example.com/v1/models" } |
There was a problem hiding this comment.
In this top-level copy-paste example, a normal @ai-sdk/openai-compatible provider will usually expose a sparse OpenAI /v1/models response at this URL, and the new note below explicitly says that shape lacks the context_length/pricing fields the plugin maps. In that common setup the fetch succeeds but enriches nothing, so the example should use an OpenRouter-shaped metadata route (or an absolute OpenRouter catalog URL) rather than https://api.example.com/v1/models.
Useful? React with 👍 / 👎.
1 participant
Summary
Follow-up to a real point of confusion: the docs examples used a bare relative path
"modelsInfoUrl": "models", which (a) reads like a magic keyword rather than a URL, and (b) resolves to a vanilla OpenAI/v1/models— which returns onlyid/object/owned_by, none of thecontext_length/pricingfields this plugin maps. So the headline example would have enriched nothing.Docs-only — no code or behavior change.
What changed (README, package README, docs/models-info.md)
meta.modelsInfoUrlis the HTTP(S) endpoint that returns OpenRouter-shaped models JSON ({ "data": [ { "id", "context_length", "pricing", … } ] }).https://openrouter.ai/api/v1/models) — so there's no "who ismodels?" ambiguity./v1/modelslacks the rich fields, so the URL must serve the OpenRouter shape (OpenRouter itself, a gateway mirroring it, or a dedicated metadata route).Notes
format:checkstill 62 files clean).🤖 Generated with Claude Code