@dbx-tools/model 0.1.57 → 0.1.67

package/README.md

@@ -62,14 +62,43 @@ rankModels(endpoints, { search: "opus", limit: 3 }); // ranked list
 resolveModel(endpoints, { modelClass: "chat-fast" }); // single id + source
 ```
 
+### Listing the catalogue directly
+
+`selectModel` / `searchModels` list endpoints for you, but you can also
+reach the catalogue functions:
+
+```ts
+import {
+  listServingEndpoints,
+  listServingEndpointsUncached,
+  searchServingEndpoints,
+  clearServingEndpointsCache,
+} from "@dbx-tools/model";
+
+// Cached + enriched (model-class stamp, embedding dimensions) through
+// AppKit's CacheManager. Keyed by `host`.
+const endpoints = await listServingEndpoints(client, host);
+
+// One-shot, dependency-light: straight from the SDK, no cache and no
+// enrichment. For CLIs / non-AppKit contexts that only need names.
+const raw = await listServingEndpointsUncached(client);
+
+// Fuzzy-rank a held list by name (the core resolveModelId builds on).
+searchServingEndpoints("claude sonnet", endpoints); // ScoredEndpoint[]
+
+// Force-evict one host's cache entry (or all when omitted).
+await clearServingEndpointsCache(host);
+```
+
 ## How resolution works
 
 1. **Explicit ask** - fuzzy-matched within the optional class ceiling
    (or returned verbatim when `fuzzy: false`).
-2. **No explicit ask** - an operator-pinned `fallback` that exists in
-   the live catalogue wins first, then the ranked live catalogue, then a
-   small static `FALLBACK_MODEL_IDS` floor when the catalogue yields
-   nothing in range (so a model id is always returned even offline).
+2. **No explicit ask** - the first operator-pinned `fallbacks` entry
+   that exists in the live catalogue wins first, then the ranked live
+   catalogue, then a small static `FALLBACK_MODEL_IDS` floor when the
+   catalogue yields nothing in range (so a model id is always returned
+   even offline).
 
 Capability bands are derived from the live workspace catalogue (the
 Foundation Model API quality/speed/cost scores), not a hand-maintained

package/dist/index.d.ts

@@ -1,22 +1,291 @@
+import { ModelClass, ModelQuery, RankedModel, ServingEndpointSummary } from "@dbx-tools/model-shared";
+import { appkitUtils } from "@dbx-tools/shared";
+export * from "@dbx-tools/model-shared";
+
+//#region packages/model/src/classes.d.ts
+/**
+ * Chat capability ladder in descending order - most capable
+ * ({@link ModelClass.ChatThinking}) first, least
+ * ({@link ModelClass.ChatFast}) last. {@link ModelClass.Embedding} is a
+ * separate modality and is deliberately absent: the ceiling never spans
+ * it. This is the order used to filter "this class and below" and to
+ * break ranking ties toward the more capable model.
+ */
+declare const CHAT_CLASS_ORDER: readonly ModelClass[];
 /**
- * `@dbx-tools/model` public surface.
+ * Every class in display order: the chat ladder followed by
+ * {@link ModelClass.Embedding}. Used when flattening a full
+ * classification (e.g. stamping the class onto each cached endpoint).
+ */
+declare const MODEL_CLASS_ORDER: readonly ModelClass[];
+/** Whether `cls` is one of the chat capability bands (vs. embedding). */
+declare function isChatClass(cls: ModelClass): boolean;
+/**
+ * Coerce an arbitrary value (query string, header, body field) to a
+ * {@link ModelClass}, returning `null` when it isn't a known class.
+ * Lets a route accept a class request without throwing on junk input.
  *
- * Bundles the package's Node-side Model Serving access (cached
- * `/serving-endpoints` listing plus fuzzy name resolution), the
- * workspace-aware {@link resolveModel} selector, and the server-only
- * offline fallback opinion (`FALLBACK_MODEL_IDS` / `modelsForClass`)
- * with a re-export of the pure `@dbx-tools/model-shared` surface
- * (capability tiers, the score profile, the endpoint descriptor, and
- * the tier classifier) so a single `from "@dbx-tools/model"` import
- * serves server-side consumers.
+ * Matches the full slug first (`"chat-fast"`, `"embedding"`), then -
+ * for a bare chat band - retries with a `chat-` prefix, so the shorthand
+ * `"thinking"` / `"balanced"` / `"fast"` resolves to the corresponding
+ * `chat-*` class.
+ */
+declare function parseModelClass(value: unknown): ModelClass | null;
+/**
+ * Classes at or below `cls` in chat capability: the class itself plus
+ * every less-capable chat band, in {@link CHAT_CLASS_ORDER}. Treats a
+ * chat `cls` as a ceiling - requesting {@link ModelClass.ChatBalanced}
+ * yields `[ChatBalanced, ChatFast]`, never
+ * {@link ModelClass.ChatThinking} - so a class ask can degrade downward
+ * to a smaller chat model but never escalate to a larger one.
  *
- * Browser-side consumers should import `@dbx-tools/model-shared`
- * directly: the serving driver pulls in `WorkspaceClient` and AppKit's
- * `CacheManager` and is Node-only, whereas the re-exported surface is
- * pure (types + sync functions) and safe for any runtime.
+ * {@link ModelClass.Embedding} is its own modality, not a rung on the
+ * chat ladder, so it yields just `[Embedding]`. An unrecognized class
+ * yields the full chat ladder.
  */
-export * from "@dbx-tools/model-shared";
-export * from "./src/classes.js";
-export * from "./src/fallback.js";
-export * from "./src/resolve.js";
-export * from "./src/serving.js";
+declare function classesAtOrBelow(cls: ModelClass): ModelClass[];
+//#endregion
+//#region packages/model/src/fallback.d.ts
+/**
+ * Static fallback model ids for a chat class, drawn from the small
+ * built-in {@link FALLBACK_MODEL_NAMES} list and ordered best-first by
+ * family rank. Sync and workspace-independent: this is the *fallback
+ * opinion* used to seed default lists or when the live catalogue is
+ * unreachable - live resolution prefers `classifyEndpoints`. Returns
+ * `[]` for {@link ModelClass.Embedding} (the floor is chat-only).
+ */
+declare function modelsForClass(cls: ModelClass): readonly string[];
+/** Top static fallback model id for a chat class. */
+declare function modelForClass(cls: ModelClass): string;
+/**
+ * Priority-ordered fallback chain (ChatThinking -> ChatBalanced ->
+ * ChatFast) over the small built-in list. The floor walked at resolve
+ * time when no agent / plugin / env / request model is set *and* the
+ * live catalogue yields nothing.
+ */
+declare const FALLBACK_MODEL_IDS: readonly string[];
+//#endregion
+//#region packages/model/src/serving.d.ts
+/**
+ * Structural type for the Databricks workspace client, re-exported from
+ * `@dbx-tools/shared` so the rest of this package can keep importing it
+ * from here. See `appkitUtils.WorkspaceClientLike` for the canonical
+ * definition.
+ */
+type WorkspaceClientLike = appkitUtils.WorkspaceClientLike;
+/** Default TTL for the in-memory endpoint cache. Matches the Databricks SDK's session lifetime budget. */
+declare const DEFAULT_MODEL_CACHE_TTL_MS: number;
+/** Default Fuse.js score threshold below which a fuzzy match is accepted. */
+declare const DEFAULT_FUZZY_THRESHOLD = 0.4;
+/** Options for {@link listServingEndpoints}. */
+interface ListServingEndpointsOptions {
+  /**
+   * Override the default cache TTL for this call, in milliseconds.
+   * Forwarded to `CacheManager` as seconds.
+   */
+  ttlMs?: number;
+}
+/**
+ * List Model Serving endpoints for the workspace owning `client`,
+ * routed through AppKit's `CacheManager`. The manager gives us
+ * everything `cachetools.TTLCache` provides plus what
+ * `cachetools-async` adds on top: per-entry TTL, in-flight request
+ * coalescing (concurrent callers share one fetch via the manager's
+ * internal `inFlightRequests` map), bounded size, telemetry spans
+ * (`cache.getOrExecute`), and optional Lakebase persistence so the
+ * catalogue survives restarts when the lakebase plugin is wired up.
+ *
+ * Returns plain {@link ServingEndpointSummary} objects (a stable
+ * subset of the SDK type) so cache hits never expose stale SDK
+ * internals. Errors from `CacheManager` or the SDK fetch propagate
+ * to the caller - we don't swallow them so users see the real
+ * auth / network issue.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()` so multi-host apps share
+ *   one entry per workspace.
+ * @param options.ttlMs - Override the default TTL just for this call.
+ *   Forwarded to `CacheManager` as seconds.
+ */
+declare function listServingEndpoints(client: WorkspaceClientLike, host: string, options?: ListServingEndpointsOptions): Promise<ServingEndpointSummary[]>;
+/**
+ * List the workspace's serving endpoints as minimal
+ * {@link ServingEndpointSummary} objects straight from the SDK: no
+ * caching, and none of the cache-load enrichment ({@link listServingEndpoints}
+ * adds the {@link ModelClass} stamp and the embedding-dimension probe).
+ * Use this for a one-shot, dependency-light listing - e.g. a CLI that
+ * only needs names/tasks for fuzzy resolution and doesn't want AppKit's
+ * `CacheManager` or the per-embedding ping cost. Prefer
+ * {@link listServingEndpoints} for the cached, enriched view.
+ */
+declare function listServingEndpointsUncached(client: WorkspaceClientLike): Promise<ServingEndpointSummary[]>;
+/**
+ * Force-evict cached endpoint listings via AppKit's `CacheManager`.
+ * With a `host` deletes that one workspace's entry; without one
+ * clears every cache entry on the manager (since `CacheManager`
+ * doesn't expose a namespace-scoped clear, this is the brute-force
+ * path - fine for tests, avoid in steady-state code).
+ */
+declare function clearServingEndpointsCache(host?: string): Promise<void>;
+/**
+ * Result of fuzzy-resolving a user-supplied model name against the
+ * live endpoint list. `score` is Fuse.js's distance (`0` is exact,
+ * `1` is no match); `matched` is `false` when the score exceeds the
+ * configured threshold so callers can fall back to the original
+ * input (Databricks will then return a clean 404).
+ */
+interface ResolvedModel {
+  modelId: string;
+  matched: boolean;
+  score?: number;
+}
+/** Options accepted by {@link resolveModelId} / {@link searchServingEndpoints}. */
+interface ResolveModelOptions {
+  /** Fuse.js threshold (0 = exact, 1 = anything). Default `0.4`. */
+  threshold?: number;
+}
+/** A serving endpoint paired with its fuzzy-match distance for a query. */
+interface ScoredEndpoint {
+  endpoint: ServingEndpointSummary;
+  /** Fuse.js distance: `0` is exact, `1` is no match. */
+  score: number;
+}
+/**
+ * Fuzzy-rank endpoints by how closely their `name` matches `input`,
+ * best (lowest score) first, keeping only those within `threshold`:
+ *
+ * 1. An exact name match short-circuits to a single `score: 0` result.
+ * 2. Otherwise the input is tokenized (dashes / underscores / spaces
+ *    become separators) and fed through Fuse.js extended search, which
+ *    AND-s each token with fuzzy matching enabled - the "tokenized
+ *    fuzzy match" a caller reaches for when they type `"claude sonnet"`
+ *    instead of the full endpoint name.
+ *
+ * Returns `[]` for an empty endpoint list or when `input` tokenizes to
+ * nothing, so callers fall back to the raw input and let Databricks
+ * surface a clean 404. This multi-result core is shared by
+ * {@link resolveModelId} (single best) and the ranked `rankModels`
+ * selector.
+ */
+declare function searchServingEndpoints(input: string, endpoints: readonly ServingEndpointSummary[], options?: ResolveModelOptions): ScoredEndpoint[];
+/**
+ * Snap a user-supplied model name to the single closest configured
+ * serving endpoint via {@link searchServingEndpoints}. Returns the
+ * input unchanged with `matched: false` when nothing scores within the
+ * threshold (or the catalogue is empty), so a deliberate model id is
+ * never silently rewritten to a similar-looking neighbour and the
+ * upstream call surfaces the canonical 404.
+ */
+declare function resolveModelId(input: string, endpoints: readonly ServingEndpointSummary[], options?: ResolveModelOptions): ResolvedModel;
+//#endregion
+//#region packages/model/src/resolve.d.ts
+/** Caller intent passed to {@link resolveModel}. */
+interface ResolveModelInput {
+  /**
+   * Explicit model id / loose name (per-request override, agent /
+   * plugin default, or env var). When set it wins over `modelClass`
+   * and `fallbacks`.
+   */
+  explicit?: string;
+  /**
+   * Fuzzy-match an `explicit` name against the live catalogue so loose
+   * names like `"claude sonnet"` resolve. Default `true`. When `false`
+   * the explicit input is returned verbatim (Databricks surfaces the
+   * canonical 404 if it doesn't exist).
+   */
+  fuzzy?: boolean;
+  /** Fuse.js threshold forwarded to {@link resolveModelId}. */
+  threshold?: number;
+  /**
+   * Chat capability class to resolve when no `explicit` id is given.
+   * The live catalogue is classified by its Foundation Model API scores
+   * and the top available model in the class (and the chat bands below
+   * it) wins, falling back to the class's small static list.
+   */
+  modelClass?: ModelClass;
+  /**
+   * Operator-supplied fallback ids tried *first* in the no-explicit,
+   * no-class path (e.g. a regulated workspace pinned to an approved
+   * subset), ahead of the auto-classified catalogue.
+   */
+  fallbacks?: readonly string[];
+}
+/** Outcome of {@link resolveModel}: the chosen id plus how it was reached. */
+interface ResolvedModelSelection {
+  modelId: string;
+  source: "explicit" | "fuzzy-match" | "class" | "fallback";
+}
+/** Intent + catalogue knobs passed to {@link selectModel}. */
+interface SelectModelInput extends ResolveModelInput {
+  /** TTL override for the cached `/serving-endpoints` listing, in ms. */
+  ttlMs?: number;
+}
+/** TTL override merged into a {@link ModelQuery} for {@link searchModels}. */
+interface SearchModelsInput extends ModelQuery {
+  /** TTL override for the cached `/serving-endpoints` listing, in ms. */
+  ttlMs?: number;
+}
+/**
+ * Rank the live catalogue against a {@link ModelQuery}, best-first.
+ *
+ * Candidates are the classified endpoints in the eligible classes:
+ * {@link classesAtOrBelow} the requested `modelClass`, or - when none is
+ * given - the chat bands only ({@link CHAT_CLASS_ORDER}), so a general
+ * ask never surfaces an embedding endpoint. Each class bucket is
+ * already best-first from {@link classifyEndpoints}. Ranking is **match
+ * then class**:
+ *
+ * 1. With a `search`, only endpoints matching it survive, ordered by
+ *    match distance (bucketed via {@link matchBucket} so near-identical
+ *    scores tie), then by class (more capable first), then by the stable
+ *    within-class rank.
+ * 2. Without a `search`, the class-then-rank candidate order stands.
+ *
+ * A `limit` truncates the result. Returns `[]` when nothing is
+ * eligible or matches - callers layer their own fallback.
+ */
+declare function rankModels(endpoints: readonly ServingEndpointSummary[], query?: ModelQuery): RankedModel[];
+/**
+ * Rank a workspace's catalogue in one call: list its
+ * `/serving-endpoints` (cached) and run {@link rankModels} over the
+ * result. The list counterpart to {@link selectModel}, for a consumer
+ * that wants the full ranked set (a model picker, a CLI) rather than a
+ * single id. Catalogue fetches fail loud: network / auth errors
+ * propagate so the caller sees the real SDK message.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()`.
+ */
+declare function searchModels(client: WorkspaceClientLike, host: string, input?: SearchModelsInput): Promise<RankedModel[]>;
+/**
+ * Resolve a model id for a workspace in one call: list its
+ * `/serving-endpoints` (cached) and run {@link resolveModel} over the
+ * result. This is the entry point for any consumer that holds a
+ * `WorkspaceClient` and just wants a usable model name - a Lakeflow
+ * job, a one-off script, or the Mastra plugin alike.
+ *
+ * Cheap exit: when an `explicit` name is given and `fuzzy` is off, the
+ * catalogue is never fetched - the name is returned verbatim and
+ * Databricks surfaces the canonical 404 if it doesn't exist. Catalogue
+ * fetches otherwise fail loud: network / auth errors propagate so the
+ * caller sees the real SDK message instead of a silent fallback.
+ *
+ * @param host - Workspace host used as the cache key. Pass the value
+ *   resolved from `client.config.getHost()`.
+ */
+declare function selectModel(client: WorkspaceClientLike, host: string, input?: SelectModelInput): Promise<ResolvedModelSelection>;
+/**
+ * Resolve a single model id from the live catalogue and caller intent,
+ * delegating the live selection to {@link rankModels} with `limit: 1`.
+ *
+ * 1. **Explicit ask**: with `fuzzy` off, returned verbatim; otherwise
+ *    fuzzy-ranked within the (optional) class ceiling and the best taken,
+ *    falling back to the input verbatim when nothing matches.
+ * 2. **No explicit ask**: an operator-pinned `fallback` that exists in
+ *    the live catalogue wins first; then the ranked live catalogue
+ *    (class ceiling applied); then the static {@link FALLBACK_MODEL_IDS}
+ *    floor when the catalogue yields nothing in range.
+ */
+declare function resolveModel(endpoints: readonly ServingEndpointSummary[], input?: ResolveModelInput): ResolvedModelSelection;
+//#endregion
+export { CHAT_CLASS_ORDER, DEFAULT_FUZZY_THRESHOLD, DEFAULT_MODEL_CACHE_TTL_MS, FALLBACK_MODEL_IDS, ListServingEndpointsOptions, MODEL_CLASS_ORDER, ResolveModelInput, ResolveModelOptions, ResolvedModel, ResolvedModelSelection, ScoredEndpoint, SearchModelsInput, SelectModelInput, WorkspaceClientLike, classesAtOrBelow, clearServingEndpointsCache, isChatClass, listServingEndpoints, listServingEndpointsUncached, modelForClass, modelsForClass, parseModelClass, rankModels, resolveModel, resolveModelId, searchModels, searchServingEndpoints, selectModel };