@gaunt-sloth/core 2.0.0-alpha.2 → 2.0.0-alpha.21

package/dist/providers/modelCatalog.d.ts

@@ -0,0 +1,109 @@
+import type { ProviderId } from '#src/providers/modelDiscovery.js';
+/** The single models.dev dataset endpoint (whole catalog; sliced per-provider on our side). */
+export declare const MODELS_DEV_URL = "https://models.dev/api.json";
+/**
+ * Cache freshness window. Pricing/limit metadata is near-static, so a day between refreshes is
+ * plenty; `gth models --refresh` is the manual escape hatch when a newer number is needed sooner.
+ */
+export declare const CATALOG_TTL_MS: number;
+/**
+ * Catalog fetch timeout. Deliberately generous (and separate from `/v1/models` discovery's 2 s
+ * interactive-path probe): `api.json` is a few MB and this fetch runs off the explicit `gth models`
+ * cache-fill path, not a first-run keystroke, so latency headroom matters more than snappiness.
+ */
+export declare const CATALOG_TIMEOUT_MS = 10000;
+/** Shown next to any enriched price/metadata. Costs from models.dev are US$ per 1M tokens. */
+export declare const CATALOG_ATTRIBUTION = "* model prices provided by models.dev";
+/**
+ * Map a Gaunt Sloth {@link ProviderId} to its models.dev top-level provider key. Cloud providers
+ * only; local/self-hosted providers (`ollama`) are intentionally absent so they get NO catalog
+ * lookup. Returns `undefined` for any provider without a models.dev slice.
+ */
+export declare const MODELS_DEV_PROVIDER_KEY: Partial<Record<ProviderId, string>>;
+/** Per-token cost metadata (US$ per 1M tokens), as published by models.dev. */
+export interface ModelCost {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+/** Context / output token limits. */
+export interface ModelLimit {
+    context?: number;
+    output?: number;
+}
+/** Input/output modalities (e.g. `text`, `image`, `pdf`). */
+export interface ModelModalities {
+    input?: string[];
+    output?: string[];
+}
+/**
+ * Normalised catalog metadata for one model id — the models.dev fields we surface, camelCased and
+ * detached from models.dev's raw JSON shape so a schema change there is absorbed in the parser.
+ */
+export interface ModelCatalogEntry {
+    /** models.dev display name (e.g. "Claude Opus 4.5"). */
+    name?: string;
+    cost?: ModelCost;
+    limit?: ModelLimit;
+    modalities?: ModelModalities;
+    /** True when the model exposes an extended-reasoning / thinking mode. */
+    reasoning?: boolean;
+    /** True when the model supports tool/function calling. */
+    toolCall?: boolean;
+}
+/** A provider's catalog slice: model-id → metadata, plus provenance for TTL / display. */
+export interface ProviderCatalog {
+    /** Gaunt Sloth provider id this slice belongs to. */
+    providerId: ProviderId;
+    /** models.dev provider key it was sliced from. */
+    providerKey: string;
+    /** Epoch ms the slice was fetched (drives TTL freshness). */
+    fetchedAt: number;
+    /** Metadata keyed by model id, exactly as models.dev keys them. */
+    models: Record<string, ModelCatalogEntry>;
+}
+/** Options shared by catalog reads; every field is injectable for hermetic tests. */
+export interface CatalogOptions {
+    /** Force a network refresh even when a fresh cache exists (backs `gth models --refresh`). */
+    refresh?: boolean;
+    /** Override the cache directory (defaults to `~/.gsloth/model-catalog`). */
+    cacheDir?: string;
+    /** Override "now" for TTL math (defaults to `Date.now()`). */
+    now?: number;
+    /** Override the fetch implementation (defaults to the global `fetch`). */
+    fetchImpl?: typeof fetch;
+    /** Override the TTL window in ms (defaults to {@link CATALOG_TTL_MS}). */
+    ttlMs?: number;
+}
+/**
+ * Get the models.dev catalog slice for one provider, cache-first.
+ *
+ * - **Local / self-hosted** (`ollama`, or any provider without a {@link MODELS_DEV_PROVIDER_KEY}):
+ *   returns `null` immediately, with **no network call**.
+ * - **Cloud, fresh cache** (and not `refresh`): returns the cached slice, no network call.
+ * - **Cloud, missing / stale cache, or `refresh`**: fetches `api.json` once, slices this provider,
+ *   writes the slice to the per-provider cache, and returns it.
+ * - **Fetch fails**: returns the stale cached slice if one exists (degrade, don't blank), else `null`.
+ *
+ * NEVER throws — catalog availability must never block model use.
+ */
+export declare function getProviderCatalog(providerId: ProviderId, options?: CatalogOptions): Promise<ProviderCatalog | null>;
+/** A {@link ModelInfo}-shaped record decorated with optional catalog metadata. */
+export interface EnrichedModel {
+    id: string;
+    preferred: boolean;
+    /** models.dev metadata for this id, when the catalog has an entry; absent = unenriched. */
+    enrichment?: ModelCatalogEntry;
+}
+/**
+ * Enrich a provider's discovered model list with catalog metadata, cache-first.
+ *
+ * `/v1/models` stays authoritative: every input model is returned, in order, whether or not
+ * models.dev knows it. Matched ids gain an `enrichment`; unmatched ids (and every model when the
+ * catalog is unavailable or the provider is local) are returned untouched. NEVER throws.
+ */
+export declare function enrichModels(providerId: ProviderId, models: ReadonlyArray<{
+    id: string;
+    preferred: boolean;
+}>, options?: CatalogOptions): Promise<EnrichedModel[]>;

package/dist/providers/modelCatalog.js

@@ -0,0 +1,245 @@
+/**
+ * @packageDocumentation
+ * Model catalog (GS2-6 / B16) — enriches CLOUD model entries with cost, context-limit and
+ * capability metadata sourced from {@link https://models.dev | models.dev} (MIT-licensed).
+ *
+ * ## What this is (and is not)
+ * This is an **enrichment** layer, never a gate. The authoritative set of callable models stays
+ * `/v1/models` live discovery (see `modelDiscovery.ts`). models.dev only decorates cloud model
+ * ids with `{ cost, limit, modalities, reasoning, toolCall }` where a match exists; a cloud model
+ * that models.dev has never heard of is still listed and still callable, just unenriched. If
+ * models.dev is unreachable (offline / on-prem no-egress / down) every model keeps working — it
+ * simply carries no metadata until the cache fills. Nothing here ever blocks model use.
+ *
+ * ## Fetch / cache shape
+ * models.dev publishes a **single** dataset at {@link MODELS_DEV_URL} (`api.json`, ~3 MB); there is
+ * no per-provider endpoint. So "lazy, per-provider" is realised on the **cache side**: on a miss for
+ * provider *X* we fetch `api.json` once, **slice out just X's models**, and persist that slice to a
+ * per-provider cache file (`~/.gsloth/model-catalog/<providerKey>.json`). Subsequent reads are served
+ * **cache-first** from that per-provider file and never touch the network within the {@link CATALOG_TTL_MS}
+ * TTL. A stale cache is refreshed on read, or on demand via `gth models --refresh`. If a refresh fetch
+ * fails but a stale slice exists, the stale slice is returned (degrade, don't blank).
+ *
+ * ## Local / self-hosted
+ * Only cloud providers have a models.dev key (see {@link MODELS_DEV_PROVIDER_KEY}). `ollama` and any
+ * other local/self-hosted provider return `null` from {@link getProviderCatalog} **without any network
+ * call** — they rely solely on `/v1/models` discovery.
+ *
+ * ## Attribution
+ * Wherever enriched prices/metadata are shown, surface {@link CATALOG_ATTRIBUTION}. models.dev is MIT
+ * licensed; we do not bundle or redistribute a seed dataset here, so no license file needs shipping.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { getGlobalGslothDir } from '#src/utils/globalConfigUtils.js';
+import { displayDebug } from '#src/utils/consoleUtils.js';
+/** The single models.dev dataset endpoint (whole catalog; sliced per-provider on our side). */
+export const MODELS_DEV_URL = 'https://models.dev/api.json';
+/**
+ * Cache freshness window. Pricing/limit metadata is near-static, so a day between refreshes is
+ * plenty; `gth models --refresh` is the manual escape hatch when a newer number is needed sooner.
+ */
+export const CATALOG_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+/**
+ * Catalog fetch timeout. Deliberately generous (and separate from `/v1/models` discovery's 2 s
+ * interactive-path probe): `api.json` is a few MB and this fetch runs off the explicit `gth models`
+ * cache-fill path, not a first-run keystroke, so latency headroom matters more than snappiness.
+ */
+export const CATALOG_TIMEOUT_MS = 10_000;
+/** Shown next to any enriched price/metadata. Costs from models.dev are US$ per 1M tokens. */
+export const CATALOG_ATTRIBUTION = '* model prices provided by models.dev';
+/**
+ * Map a Gaunt Sloth {@link ProviderId} to its models.dev top-level provider key. Cloud providers
+ * only; local/self-hosted providers (`ollama`) are intentionally absent so they get NO catalog
+ * lookup. Returns `undefined` for any provider without a models.dev slice.
+ */
+export const MODELS_DEV_PROVIDER_KEY = {
+    anthropic: 'anthropic',
+    openai: 'openai',
+    'google-genai': 'google',
+    vertexai: 'google-vertex',
+    groq: 'groq',
+    deepseek: 'deepseek',
+    xai: 'xai',
+    openrouter: 'openrouter',
+    huggingface: 'huggingface',
+    // ollama — local, no models.dev entry (excluded on purpose).
+};
+/** Resolve the per-provider cache directory. */
+function catalogCacheDir(options) {
+    return options.cacheDir ?? resolve(getGlobalGslothDir(), 'model-catalog');
+}
+/** Resolve the cache file path for one models.dev provider key. */
+function catalogCacheFile(providerKey, options) {
+    return resolve(catalogCacheDir(options), `${providerKey}.json`);
+}
+/**
+ * Coerce one models.dev raw model object into a {@link ModelCatalogEntry}, keeping only the fields
+ * we surface and only when they are the expected type (defensive against dataset drift).
+ */
+function normaliseEntry(raw) {
+    const m = (raw ?? {});
+    const entry = {};
+    if (typeof m.name === 'string')
+        entry.name = m.name;
+    if (typeof m.reasoning === 'boolean')
+        entry.reasoning = m.reasoning;
+    if (typeof m.tool_call === 'boolean')
+        entry.toolCall = m.tool_call;
+    const cost = m.cost;
+    if (cost && typeof cost === 'object') {
+        const c = {};
+        if (typeof cost.input === 'number')
+            c.input = cost.input;
+        if (typeof cost.output === 'number')
+            c.output = cost.output;
+        if (typeof cost.cache_read === 'number')
+            c.cacheRead = cost.cache_read;
+        if (typeof cost.cache_write === 'number')
+            c.cacheWrite = cost.cache_write;
+        if (Object.keys(c).length > 0)
+            entry.cost = c;
+    }
+    const limit = m.limit;
+    if (limit && typeof limit === 'object') {
+        const l = {};
+        if (typeof limit.context === 'number')
+            l.context = limit.context;
+        if (typeof limit.output === 'number')
+            l.output = limit.output;
+        if (Object.keys(l).length > 0)
+            entry.limit = l;
+    }
+    const modalities = m.modalities;
+    if (modalities && typeof modalities === 'object') {
+        const mod = {};
+        if (Array.isArray(modalities.input))
+            mod.input = modalities.input.filter((x) => typeof x === 'string');
+        if (Array.isArray(modalities.output))
+            mod.output = modalities.output.filter((x) => typeof x === 'string');
+        if ((mod.input?.length ?? 0) > 0 || (mod.output?.length ?? 0) > 0)
+            entry.modalities = mod;
+    }
+    return entry;
+}
+/**
+ * Slice one provider's models out of the full models.dev `api.json` payload and normalise them.
+ * Returns `{}` when the provider key is absent or malformed — an empty-but-present slice, which the
+ * caller still caches (models.dev simply has no data for that provider yet).
+ */
+function sliceProvider(payload, providerKey) {
+    const providerBlock = payload?.[providerKey];
+    const models = providerBlock?.models;
+    if (!models || typeof models !== 'object')
+        return {};
+    const out = {};
+    for (const [id, raw] of Object.entries(models)) {
+        out[id] = normaliseEntry(raw);
+    }
+    return out;
+}
+/** Read and validate a cached per-provider slice; returns null on any miss / parse failure. */
+function readCache(providerKey, options) {
+    const file = catalogCacheFile(providerKey, options);
+    if (!existsSync(file))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed.fetchedAt === 'number' && parsed.models)
+            return parsed;
+        return null;
+    }
+    catch (e) {
+        displayDebug(`Model catalog cache for "${providerKey}" is unreadable: ${errMsg(e)}`);
+        return null;
+    }
+}
+/** Persist a per-provider slice to the cache (best-effort; a write failure is non-fatal). */
+function writeCache(catalog, options) {
+    try {
+        const dir = catalogCacheDir(options);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(catalogCacheFile(catalog.providerKey, options), JSON.stringify(catalog), 'utf8');
+    }
+    catch (e) {
+        displayDebug(`Failed to write model catalog cache for "${catalog.providerKey}": ${errMsg(e)}`);
+    }
+}
+function errMsg(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** True when a cached slice is still within the TTL window. */
+function isFresh(cache, options) {
+    const now = options.now ?? Date.now();
+    const ttl = options.ttlMs ?? CATALOG_TTL_MS;
+    return now - cache.fetchedAt < ttl;
+}
+/**
+ * Get the models.dev catalog slice for one provider, cache-first.
+ *
+ * - **Local / self-hosted** (`ollama`, or any provider without a {@link MODELS_DEV_PROVIDER_KEY}):
+ *   returns `null` immediately, with **no network call**.
+ * - **Cloud, fresh cache** (and not `refresh`): returns the cached slice, no network call.
+ * - **Cloud, missing / stale cache, or `refresh`**: fetches `api.json` once, slices this provider,
+ *   writes the slice to the per-provider cache, and returns it.
+ * - **Fetch fails**: returns the stale cached slice if one exists (degrade, don't blank), else `null`.
+ *
+ * NEVER throws — catalog availability must never block model use.
+ */
+export async function getProviderCatalog(providerId, options = {}) {
+    const providerKey = MODELS_DEV_PROVIDER_KEY[providerId];
+    if (!providerKey)
+        return null; // local / unmapped provider → no catalog lookup at all.
+    const cached = readCache(providerKey, options);
+    if (cached && !options.refresh && isFresh(cached, options)) {
+        return cached;
+    }
+    const fetchImpl = options.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(MODELS_DEV_URL, {
+            method: 'GET',
+            headers: { Accept: 'application/json' },
+            signal: AbortSignal.timeout(CATALOG_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            displayDebug(`models.dev returned HTTP ${res.status}; using cached catalog if available.`);
+            return cached; // may be stale; may be null.
+        }
+        const payload = await res.json();
+        const catalog = {
+            providerId,
+            providerKey,
+            fetchedAt: options.now ?? Date.now(),
+            models: sliceProvider(payload, providerKey),
+        };
+        writeCache(catalog, options);
+        return catalog;
+    }
+    catch (e) {
+        // Offline / on-prem no-egress / timeout / malformed — degrade to the stale slice or nothing.
+        displayDebug(`models.dev fetch failed: ${errMsg(e)}; using cached catalog if available.`);
+        return cached;
+    }
+}
+/**
+ * Enrich a provider's discovered model list with catalog metadata, cache-first.
+ *
+ * `/v1/models` stays authoritative: every input model is returned, in order, whether or not
+ * models.dev knows it. Matched ids gain an `enrichment`; unmatched ids (and every model when the
+ * catalog is unavailable or the provider is local) are returned untouched. NEVER throws.
+ */
+export async function enrichModels(providerId, models, options = {}) {
+    let catalog = null;
+    try {
+        catalog = await getProviderCatalog(providerId, options);
+    }
+    catch {
+        catalog = null; // defensive: getProviderCatalog already swallows, but never let enrichment throw.
+    }
+    return models.map((m) => {
+        const enrichment = catalog?.models[m.id];
+        return enrichment ? { ...m, enrichment } : { id: m.id, preferred: m.preferred };
+    });
+}
+//# sourceMappingURL=modelCatalog.js.map

package/dist/providers/modelCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelCatalog.js","sourceRoot":"","sources":["../../src/providers/modelCatalog.ts"],"names":[],"mappings":"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"}

package/dist/providers/modelDiscovery.d.ts

@@ -148,9 +148,83 @@ export declare function findApiKeyEnvVar(descriptor: ProviderDescriptor): string
  * - When `discoveredModels` is omitted, the curated `preferredModels` are
  *   returned, all flagged ⭐ preferred.
  * - When provided, every discovered model is listed; those that also appear in
- *   the curated `preferredModels` are flagged ⭐ preferred.
+ *   the curated `preferredModels` are flagged ⭐ preferred. The list is ordered
+ *   **preferred first** (in curated order, so the recommended default sits on top
+ *   and is pre-selected), then every other discovered model **alphabetically** —
+ *   so a large catalog (e.g. OpenRouter's 200+ models) is navigable instead of
+ *   arriving in the endpoint's arbitrary order.
  */
 export declare function buildModelList(descriptor: ProviderDescriptor, discoveredModels?: string[]): ModelInfo[];
+/**
+ * The single fallback source of truth for a provider's default model id (CFG-14).
+ *
+ * Returns the top curated ⭐ `preferredModels` entry for the provider — the one
+ * id that provider factories fall back to when a config carries no `model`, and
+ * the id first-run writes when live discovery is impossible. Centralising it here
+ * means the fallback lives in exactly ONE place (the curated registry above)
+ * instead of being duplicated as a literal in every `providers/<id>.ts`.
+ *
+ * Every registered provider is required to carry at least one curated model, so
+ * this always resolves for a known id; it throws for an unknown provider or a
+ * provider whose `preferredModels` is empty (a developer error — the invariant
+ * that the fallback source is complete would otherwise fail silently).
+ *
+ * @returns the curated default model id (always defined for a known provider).
+ */
+export declare function getCuratedFallbackModel(providerId: ProviderId): string;
+/**
+ * Build the minimal `.gsloth.config.json` body an `init` template writes for a
+ * provider (CFG-14). When `model` is omitted, the `model` key is left OUT of the
+ * config entirely, so the provider factory resolves it at run time from
+ * {@link getCuratedFallbackModel} — the single curated source that tracks the
+ * installed version, rather than a literal frozen into the user's file that 404s
+ * once the model is retired.
+ *
+ * A `$schema` pointer ({@link CONFIG_SCHEMA_POINTER}) is written first so editors offer
+ * autocomplete/validation against the shipped JSON Schema (GS2-1). `$schema` is a known,
+ * runtime-ignored config field (see the zod schema), so it never affects loading.
+ */
+export declare function buildInitConfigContent(providerId: ProviderId, model?: string): string;
+/**
+ * CFG-21 — the timeout for the *interactive* first-run model fetch. The dialog is
+ * blocking on a human who just picked a provider, so it can afford to wait a lot
+ * longer than the background probes for a large cloud catalog (OpenRouter ~300
+ * models) to arrive over a cold connection, rather than losing the 2s race and
+ * silently dropping to a 3-item curated stub. Threaded per-call so ONLY the dialog
+ * uses it — `detectProviders` / `resolveInitModel` stay on the short
+ * {@link DISCOVERY_TIMEOUT_MS} probe (a long global would hang the *provider* step
+ * whenever the local Ollama daemon is down).
+ */
+export declare const INTERACTIVE_MODEL_FETCH_TIMEOUT_MS = 12000;
+/**
+ * Provenance of a returned model list (CFG-21). Distinguishes the three outcomes so
+ * an interactive caller can tell an honest "couldn't reach the provider" degrade
+ * apart from a by-design curated list:
+ *
+ * - `live`     — a successful, non-empty live `/v1/models` query.
+ * - `fallback` — a live query WAS attempted (key present / ollama probed) but
+ *   failed: network error/timeout, non-2xx, or an empty/malformed payload. THIS is
+ *   the "couldn't reach" case the first-run dialog surfaces.
+ * - `curated`  — no live query was attempted, by design: a `kind:'none'` provider
+ *   (google-genai, vertexai) or a cloud provider with no API key present. The
+ *   curated catalog is the expected result here, NOT a degrade, so the dialog must
+ *   NOT show a "couldn't reach" notice for it.
+ */
+export type ModelDiscoveryStatus = 'live' | 'fallback' | 'curated';
+/** Per-call discovery options (CFG-21). */
+export interface ModelDiscoveryOptions {
+    /**
+     * Live-fetch timeout in ms. Defaults to the short {@link DISCOVERY_TIMEOUT_MS} so
+     * every existing caller is unchanged; the interactive first-run dialog passes the
+     * generous {@link INTERACTIVE_MODEL_FETCH_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
+}
+/** A model list plus its {@link ModelDiscoveryStatus} provenance (CFG-21). */
+export interface ModelDiscoveryResult {
+    models: ModelInfo[];
+    status: ModelDiscoveryStatus;
+}
 /**
  * Discover the models for a single provider.
  *
@@ -167,15 +241,49 @@ export declare function buildModelList(descriptor: ProviderDescriptor, discovere
  * the curated catalog is returned directly. Ollama (no key, local daemon) is
  * always probed.
  */
-export declare function discoverModels(providerId: ProviderId): Promise<ModelInfo[]>;
+export declare function discoverModels(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelInfo[]>;
 /**
  * List the models for a single provider.
  *
  * Live-discovers from the provider's models endpoint where possible (with a
  * curated fallback); returns the curated set for `kind: 'none'` providers. Does
  * not require the provider to be "available".
+ *
+ * `options.timeoutMs` (CFG-21) overrides the default short live-fetch timeout; the
+ * bare `listModels(providerId)` call is unchanged.
+ */
+export declare function listModels(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelInfo[]>;
+/**
+ * CFG-21 — like {@link discoverModels} but also returns the model list's
+ * {@link ModelDiscoveryStatus} provenance, so an interactive caller (the first-run
+ * dialog) can tell an honest "couldn't reach the provider" degrade (`fallback`)
+ * apart from a by-design curated list (`curated`) and a real live catalog (`live`).
+ * Kept as a separate export so `listModels` / `discoverModels` keep their existing
+ * `(providerId) => ModelInfo[]` signatures other callers rely on.
+ *
+ * Never throws for a discovery failure (that degrades to `fallback`); it only
+ * throws for an unknown provider id, mirroring {@link discoverModels}.
+ */
+export declare function discoverModelsWithProvenance(providerId: ProviderId, options?: ModelDiscoveryOptions): Promise<ModelDiscoveryResult>;
+/**
+ * Resolve the model id that `init` should bake into a generated config for a
+ * provider (CFG-14) — the safeguard against writing a speculative id that 404s
+ * once the model is retired.
+ *
+ * - **Live discovery possible** (a key / running daemon and a responding
+ *   `/v1/models` endpoint): returns a *verified-present* id — the highest-ranked
+ *   curated ⭐ id that is actually in the live list (matched tolerant of an
+ *   `:latest` suffix), or, when no curated id is live, the first live id.
+ * - **Live discovery impossible** (`kind: 'none'`, no key, offline, empty
+ *   catalog): returns `undefined`. This is the ONLY speculative path, and it
+ *   deliberately declines to invent a literal: the caller OMITS `model` so the
+ *   provider factory falls back to {@link getCuratedFallbackModel} at run time
+ *   (a single curated source that upgrades with the installed version).
+ *
+ * Never throws — a bad key or network error degrades to `undefined`, mirroring
+ * {@link discoverModels}.
  */
-export declare function listModels(providerId: ProviderId): Promise<ModelInfo[]>;
+export declare function resolveInitModel(providerId: ProviderId): Promise<string | undefined>;
 /**
  * Detect every known provider on this machine and list its models.
  *