Generic HTTP-based model listing backed by an ETS TTL cache.
Reads the model_discovery block from a ProviderSpec and fetches the
list of available model IDs from the provider's API endpoint. Results are
cached in an ETS table for ttl_seconds (default: 300) before re-fetching.
model_discovery block
{
"url": "https://openrouter.ai/api/v1/models",
"path": "data.id",
"headers": {"Authorization": "Bearer sk-or-..."},
"ttl_seconds": 300
}| Field | Required | Description |
|---|---|---|
url | yes | HTTP GET endpoint that returns model metadata |
path | no | Dot-delimited path into the JSON response to extract IDs (default: "data.id") |
headers | no | Additional request headers (e.g. auth) |
ttl_seconds | no | Cache lifetime in seconds (default: 300) |
Path extraction
path is a dot-delimited string. Traversal descends through map keys; when a
list is encountered the remaining path is applied to each element and results
are flattened. Examples:
"data.id"— extractsresp["data"][*]["id"]"id"— extractsresp[*]["id"]when the root is a list""— returns root list elements (when they are strings)
Summary
Functions
Memoise fun's successful result under key for ttl_ms.
Returns a specification to start this module under a supervisor.
Return the list of available model IDs for the provider described by spec.
Functions
@spec cached(term(), non_neg_integer() | :no_cache, (-> result)) :: result when result: term()
Memoise fun's successful result under key for ttl_ms.
This is the cache behind every kind of model listing in ExAthena — the
ProviderSpec fetch above and the live endpoint enumeration in
ExAthena.ModelListing both land here, so there is exactly one table, one
TTL policy and one thing to clear in tests.
Only {:ok, _} is stored. Caching an error would turn a momentarily
unreachable local daemon into an empty model picker for the rest of the TTL,
which reads as "you have no models" rather than "I could not reach it".
Pass :no_cache as the TTL to force a fresh computation (and refresh the
entry) — a user hitting "reload models" means it.
Returns a specification to start this module under a supervisor.
See Supervisor.
@spec list_models(ExAthena.ProviderSpec.t()) :: {:ok, [String.t()]} | {:error, term()}
Return the list of available model IDs for the provider described by spec.
Returns {:ok, [String.t()]} from the ETS cache when a fresh entry exists,
or fetches from the provider's model_discovery.url and caches the result.
Returns {:error, :no_model_discovery} when spec.model_discovery is nil.