@dbx-tools/model 0.3.20 → 0.3.22

package/README.md

@@ -21,7 +21,10 @@ Key features:
   endpoint id.
 - Supports class ceilings so callers can ask for a capability band without
   accidentally escalating to a larger model.
-- Caches enriched catalogues per workspace host through AppKit cache utilities.
+- Caches enriched catalogues per workspace host through AppKit cache utilities,
+  and re-lists once on a resolve miss so a newly deployed model still resolves.
+- Builds the invocations URL and mints per-request auth headers for callers that
+  issue their own OpenAI-shaped HTTP requests.
 - Provides a small static fallback floor for local tools and degraded workspace
   access.
 
@@ -137,6 +140,38 @@ Fuzzy matching is intentionally a server concern because it depends on the live
 workspace catalogue and may re-list on misses. Disable it in callers that require
 exact endpoint ids.
 
+## Resolve Against A Catalogue That May Be Stale
+
+```ts
+const resolved = await resolve.rankModelIdLive((force) => loadCatalogue(force), "opus");
+```
+
+`rankModelIdLive()` matches the catalogue you already hold and, on a miss,
+reloads once with `force` before giving up, so a model deployed after your cache
+warmed still resolves without a restart. You supply the loader, so the caching
+policy stays yours: `listServingEndpoints` and its `CacheManager`, a plain field
+in a long-lived CLI, or a test double. `rankModelId()` is the pure form over a
+single snapshot; unlike `serving.resolveModelId` it breaks equal match scores by
+class and then version, so `"opus"` prefers `opus-5` over `opus-4-7`.
+
+## Call An Endpoint Directly
+
+```ts
+import { invoke } from "@dbx-tools/model";
+
+const response = await fetch(invoke.invocationsUrl(host, endpointId), {
+  method: "POST",
+  headers: { ...(await invoke.authHeaders(client)), "content-type": "application/json" },
+  body: JSON.stringify({ messages }),
+});
+```
+
+Use `invoke` when you need to issue your own request against a serving endpoint
+with an OpenAI-shaped body - a proxy, a passthrough route, a streaming client -
+rather than the SDK's typed `servingEndpoints.query`. Mint `authHeaders()` per
+request: the SDK refreshes the underlying token as it nears expiry, so you never
+track lifetimes yourself.
+
 ## Use Static Fallbacks
 
 ```ts
@@ -157,9 +192,11 @@ policy decisions; fallbacks are a last resort.
   resolver functions.
 - `serving` - Databricks serving-endpoint listing, cache management, fuzzy
   search, and endpoint-id resolution.
+- `invoke` - invocations URL construction and per-request auth headers for
+  calling an endpoint over raw HTTP.
 - `classes` - model-class parsing, ordering, and class-ceiling helpers.
 - `fallback` - static fallback model ids per class.
 
 The AppKit-Mastra integration uses this package through
 [`@dbx-tools/appkit-mastra`](../appkit-mastra); the local OpenAI-compatible
-gateway uses it through [`@dbx-tools/model-proxy`](../../cli/model-proxy).
+gateway uses it through [`@dbx-tools/cli-model-proxy`](../../cli/model-proxy).

package/index.ts

@@ -4,7 +4,9 @@
 
 export * as classes from "./src/classes";
 export * as fallback from "./src/fallback";
+export * as invoke from "./src/invoke";
 export * as resolve from "./src/resolve";
 export * as serving from "./src/serving";
+export type { AuthenticatingClientLike } from "./src/invoke";
 export type { ResolveModelInput, ResolvedModelSelection, SelectModelInput, SearchModelsInput } from "./src/resolve";
 export type { WorkspaceClientLike, ListServingEndpointsOptions, ResolvedModel, ResolveModelOptions, ScoredEndpoint } from "./src/serving";

package/package.json

@@ -13,16 +13,16 @@
   "dependencies": {
     "@databricks/appkit": "^0.43.0",
     "fuse.js": "^7.4.2",
-    "@dbx-tools/appkit": "0.3.20",
-    "@dbx-tools/shared-core": "0.3.20",
-    "@dbx-tools/shared-model": "0.3.20"
+    "@dbx-tools/shared-core": "0.3.22",
+    "@dbx-tools/shared-model": "0.3.22",
+    "@dbx-tools/appkit": "0.3.22"
   },
   "main": "index.ts",
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.20",
+  "version": "0.3.22",
   "types": "index.ts",
   "type": "module",
   "exports": {

package/src/invoke.ts

@@ -0,0 +1,68 @@
+/**
+ * Calling a Model Serving endpoint directly over HTTP.
+ *
+ * The SDK's `servingEndpoints.query` covers the typed request shapes, but an
+ * OpenAI-compatible caller (a proxy, a passthrough route, a streaming client)
+ * needs to issue its own `fetch` against the endpoint's `invocations` URL with
+ * an OpenAI body. That needs exactly two things the SDK doesn't hand out
+ * directly: the URL ({@link invocationsUrl}) and a currently-valid set of auth
+ * headers ({@link authHeaders}).
+ *
+ * Auth is delegated entirely to the Databricks SDK: `config.authenticate`
+ * re-runs the configured credential provider on every call and refreshes the
+ * underlying OAuth / PAT token when it is close to expiry, so a caller never
+ * manages token lifetimes itself - mint headers per request and each one is
+ * signed with a valid bearer token.
+ *
+ * @module
+ */
+
+/**
+ * Path segment appended to a serving endpoint for OpenAI-compatible requests.
+ * Databricks routes `/serving-endpoints/<name>/invocations` to the endpoint's
+ * OpenAI-shaped surface (`messages` in, `choices` out).
+ */
+export const INVOCATIONS_SUFFIX = "invocations";
+
+/**
+ * The OpenAI-compatible invocations URL for an endpoint id.
+ *
+ * @param host - Workspace host, e.g. `https://my-workspace.cloud.databricks.com/`.
+ *   Pass the value resolved from `client.config.getHost()`.
+ * @param endpoint - Endpoint id (already resolved; not fuzzy-matched here).
+ */
+export function invocationsUrl(host: string, endpoint: string): string {
+  return new URL(
+    `serving-endpoints/${encodeURIComponent(endpoint)}/${INVOCATIONS_SUFFIX}`,
+    host,
+  ).toString();
+}
+
+/**
+ * Minimal structural shape {@link authHeaders} needs. Declared narrowly rather
+ * than as a full `WorkspaceClientLike` so a caller holding its own
+ * `@databricks/sdk-experimental` `WorkspaceClient` satisfies it regardless of
+ * which SDK version resolved in its tree.
+ */
+export interface AuthenticatingClientLike {
+  config: {
+    authenticate(headers: Headers): Promise<void>;
+  };
+}
+
+/**
+ * Mint auth headers for one upstream request as a plain object, ready to spread
+ * into a `fetch` init. Call it per request: the SDK refreshes the underlying
+ * token when needed, so a long-lived process never has to track expiry itself.
+ */
+export async function authHeaders(
+  client: AuthenticatingClientLike,
+): Promise<Record<string, string>> {
+  const headers = new Headers();
+  await client.config.authenticate(headers);
+  const out: Record<string, string> = {};
+  headers.forEach((value, key) => {
+    out[key] = value;
+  });
+  return out;
+}

package/src/resolve.ts

@@ -20,6 +20,7 @@
  * @module
  */
 
+import { object } from "@dbx-tools/shared-core";
 import {
   classify,
   model,
@@ -27,11 +28,16 @@ import {
   type RankedModel,
   type ServingEndpointSummary,
 } from "@dbx-tools/shared-model";
-import { object } from "@dbx-tools/shared-core";
 
 import { CHAT_CLASS_ORDER, classesAtOrBelow, MODEL_CLASS_ORDER } from "./classes";
 import { FALLBACK_MODEL_IDS, modelsForClass } from "./fallback";
-import { listServingEndpoints, searchServingEndpoints, type WorkspaceClientLike } from "./serving";
+import {
+  listServingEndpoints,
+  searchServingEndpoints,
+  type ResolvedModel,
+  type ResolveModelOptions,
+  type WorkspaceClientLike,
+} from "./serving";
 
 type ModelClass = model.ModelClass;
 
@@ -154,6 +160,56 @@ export function rankModels(
   return query.limit !== undefined ? ranked.slice(0, Math.max(0, query.limit)) : ranked;
 }
 
+/**
+ * Collapse {@link rankModels} to a single id: the closest endpoint to `search`
+ * in a catalogue snapshot, or the input verbatim when nothing scores within the
+ * threshold.
+ *
+ * The rank-based counterpart to the Fuse-only {@link resolveModelId}: equal
+ * match scores are broken by class and then within-class version, so a loose
+ * `"opus"` prefers `opus-5` over `opus-4-7` instead of picking whichever
+ * sibling Fuse happened to order first. Returning the input unmatched (rather
+ * than a near neighbour) is deliberate - a deliberate endpoint id is never
+ * silently rewritten, and Databricks surfaces a clean 404.
+ */
+export function rankModelId(
+  endpoints: readonly ServingEndpointSummary[],
+  search: string,
+  options: ResolveModelOptions = {},
+): ResolvedModel {
+  const [top] = rankModels(endpoints, {
+    search,
+    limit: 1,
+    ...(options.threshold !== undefined ? { threshold: options.threshold } : {}),
+  });
+  if (!top) return { modelId: search, matched: false };
+  return { modelId: top.endpoint.name, matched: true, score: top.score };
+}
+
+/**
+ * {@link rankModelId} against a catalogue the caller may be holding stale:
+ * match the loaded snapshot, and on a miss reload once with `force` and match
+ * again. That way a model deployed after the catalogue was cached still
+ * resolves on first use, without a restart and without giving up caching.
+ *
+ * The catalogue arrives as a loader rather than a client so the caller keeps
+ * ownership of *how* it is cached - {@link listServingEndpoints} and its
+ * `CacheManager`, a plain process-lifetime field in a CLI, or a test double.
+ * Only one reload is attempted: a genuinely unknown name should fail fast
+ * rather than re-list on every request.
+ *
+ * @param load - Returns the catalogue; `force` asks it to bypass its cache.
+ */
+export async function rankModelIdLive(
+  load: (force: boolean) => Promise<readonly ServingEndpointSummary[]>,
+  search: string,
+  options: ResolveModelOptions = {},
+): Promise<ResolvedModel> {
+  const resolved = rankModelId(await load(false), search, options);
+  if (resolved.matched) return resolved;
+  return rankModelId(await load(true), search, options);
+}
+
 /**
  * Rank a workspace's catalogue in one call: list its `/serving-endpoints`
  * (cached) and run {@link rankModels} over the result. The list counterpart to