@shop-os/modelkit 0.1.11 → 0.2.0

package/dist/catalog.d.cts

@@ -1,4 +1,5 @@
 import { ImageModel, experimental_generateVideo } from 'ai';
+import { z } from 'zod';
 
 /**
  * Canonical vocabulary shared by every adapter. Adapters translate these
@@ -417,11 +418,50 @@ declare class Catalog {
     }): CatalogModel[];
     /** Merge rows by id. Used for catalogOverride. */
     withOverrides(rows: CatalogModel[]): Catalog;
+    /** Atomically swap every row. Builds the maps first so a bad batch throws before anything changes. */
+    replace(rows: CatalogModel[]): void;
 }
 
 /** Seeded from Cowork, Space Builder and trigger-workflows. See catalog/*.ts. */
 declare const MODELS: CatalogModel[];
 
+declare const ADAPTER_IDS: readonly ["ai-sdk-text", "google-image", "openai-image", "google-genai", "ark", "fal", "replicate", "prodia", "higgsfield", "xai-video"];
+declare const CatalogModelSchema: z.ZodType<CatalogModel>;
+declare const CatalogSchema: z.ZodType<CatalogModel[]>;
+
+declare const liveCatalog: Catalog;
+
+interface CatalogCache {
+    get(): Promise<string | null>;
+    set(json: string): Promise<void>;
+}
+type CatalogAuth = {
+    bearer: string;
+} | {
+    apiKey: string;
+};
+interface CatalogSource {
+    baseUrl: string;
+    auth: CatalogAuth;
+    ttlMs?: number;
+    /** Abort a fetch after this many ms. Default 10 s. */
+    timeoutMs?: number;
+    cache?: CatalogCache;
+    fetch?: typeof fetch;
+    logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+}
+type CatalogOrigin = "remote" | "last-good" | "snapshot";
+interface PrimeCatalogResult {
+    origin: CatalogOrigin;
+    rowCount: number;
+    revision?: string;
+    error?: string;
+}
+/** Fetch, validate, swap into liveCatalog. Never throws. Second call returns the same promise. */
+declare function primeCatalog(source: CatalogSource): Promise<PrimeCatalogResult>;
+/** Test seam: stop the refresh timer and reset liveCatalog to MODELS and clear the memo. */
+declare function resetLiveCatalog(): void;
+
 declare const IMAGE_MODELS: CatalogModel[];
 
 declare const VIDEO_MODELS: CatalogModel[];
@@ -476,4 +516,4 @@ declare function isModelKitError(err: unknown): err is ModelKitError;
 /** Resolve caller options against a catalog row, dispatching on `model.type`. */
 declare function resolveOptions(model: CatalogModel, request: ImageRequest | VideoRequest | AudioRequest, onUnsupported?: OnUnsupported): ResolveResult<ImageRequest | VideoRequest | AudioRequest>;
 
-export { type AdapterEndpoints, type AdapterId, type AspectRatio, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogCapabilities, type CatalogDisplay, type CatalogModel, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type Lifecycle, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type ReferenceLimits, type RequiredInput, type ResolveResult, type Routing, type SupportedOption, TEXT_MODELS, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, type VideoResult, type Warning, isModelKitError, nearestAspectRatio, resolveAudioOptions, resolveImageOptions, resolveOptions, resolveVideoOptions };
+export { ADAPTER_IDS, type AdapterEndpoints, type AdapterId, type AspectRatio, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogAuth, type CatalogCache, type CatalogCapabilities, type CatalogDisplay, type CatalogModel, CatalogModelSchema, type CatalogOrigin, CatalogSchema, type CatalogSource, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type Lifecycle, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type ReferenceLimits, type RequiredInput, type ResolveResult, type Routing, type SupportedOption, TEXT_MODELS, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, type VideoResult, type Warning, isModelKitError, liveCatalog, nearestAspectRatio, primeCatalog, resetLiveCatalog, resolveAudioOptions, resolveImageOptions, resolveOptions, resolveVideoOptions };

package/dist/catalog.d.ts

@@ -1,4 +1,5 @@
 import { ImageModel, experimental_generateVideo } from 'ai';
+import { z } from 'zod';
 
 /**
  * Canonical vocabulary shared by every adapter. Adapters translate these
@@ -417,11 +418,50 @@ declare class Catalog {
     }): CatalogModel[];
     /** Merge rows by id. Used for catalogOverride. */
     withOverrides(rows: CatalogModel[]): Catalog;
+    /** Atomically swap every row. Builds the maps first so a bad batch throws before anything changes. */
+    replace(rows: CatalogModel[]): void;
 }
 
 /** Seeded from Cowork, Space Builder and trigger-workflows. See catalog/*.ts. */
 declare const MODELS: CatalogModel[];
 
+declare const ADAPTER_IDS: readonly ["ai-sdk-text", "google-image", "openai-image", "google-genai", "ark", "fal", "replicate", "prodia", "higgsfield", "xai-video"];
+declare const CatalogModelSchema: z.ZodType<CatalogModel>;
+declare const CatalogSchema: z.ZodType<CatalogModel[]>;
+
+declare const liveCatalog: Catalog;
+
+interface CatalogCache {
+    get(): Promise<string | null>;
+    set(json: string): Promise<void>;
+}
+type CatalogAuth = {
+    bearer: string;
+} | {
+    apiKey: string;
+};
+interface CatalogSource {
+    baseUrl: string;
+    auth: CatalogAuth;
+    ttlMs?: number;
+    /** Abort a fetch after this many ms. Default 10 s. */
+    timeoutMs?: number;
+    cache?: CatalogCache;
+    fetch?: typeof fetch;
+    logger?: Pick<Console, "debug" | "info" | "warn" | "error">;
+}
+type CatalogOrigin = "remote" | "last-good" | "snapshot";
+interface PrimeCatalogResult {
+    origin: CatalogOrigin;
+    rowCount: number;
+    revision?: string;
+    error?: string;
+}
+/** Fetch, validate, swap into liveCatalog. Never throws. Second call returns the same promise. */
+declare function primeCatalog(source: CatalogSource): Promise<PrimeCatalogResult>;
+/** Test seam: stop the refresh timer and reset liveCatalog to MODELS and clear the memo. */
+declare function resetLiveCatalog(): void;
+
 declare const IMAGE_MODELS: CatalogModel[];
 
 declare const VIDEO_MODELS: CatalogModel[];
@@ -476,4 +516,4 @@ declare function isModelKitError(err: unknown): err is ModelKitError;
 /** Resolve caller options against a catalog row, dispatching on `model.type`. */
 declare function resolveOptions(model: CatalogModel, request: ImageRequest | VideoRequest | AudioRequest, onUnsupported?: OnUnsupported): ResolveResult<ImageRequest | VideoRequest | AudioRequest>;
 
-export { type AdapterEndpoints, type AdapterId, type AspectRatio, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogCapabilities, type CatalogDisplay, type CatalogModel, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type Lifecycle, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type ReferenceLimits, type RequiredInput, type ResolveResult, type Routing, type SupportedOption, TEXT_MODELS, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, type VideoResult, type Warning, isModelKitError, nearestAspectRatio, resolveAudioOptions, resolveImageOptions, resolveOptions, resolveVideoOptions };
+export { ADAPTER_IDS, type AdapterEndpoints, type AdapterId, type AspectRatio, type AudioRequest, type AudioResult, type CallContext, Catalog, type CatalogAuth, type CatalogCache, type CatalogCapabilities, type CatalogDisplay, type CatalogModel, CatalogModelSchema, type CatalogOrigin, CatalogSchema, type CatalogSource, type GeneratedImage, IMAGE_MODELS, type ImageBytes, type ImageCallOptions, type ImageCallResult, type ImageQuality, type ImageRequest, type ImageResult, type ImageSafetySetting, type ImageSize, type JsonObject, type JsonPrimitive, type JsonValue, type Lifecycle, MODELS, type MediaPart, type MediaRef, type ModelConstraints, type ModelKitConfig, ModelKitError, type ModelKitErrorCode, type ModelKitErrorInit, type ModelType, OTHER_MODELS, type OnUnsupported, type OutputFormat, type PricingKind, type PrimeCatalogResult, type ProviderErrorBody, type ProviderKeyName, type ProviderKeys, type ProviderOptionValue, type ProviderOptions, type ReferenceLimits, type RequiredInput, type ResolveResult, type Routing, type SupportedOption, TEXT_MODELS, type UpscaleOptions, type UsageEvent, type UsageModality, type UsageUnit, VIDEO_MODELS, type VideoCallJob, type VideoCallOptions, type VideoJob, type VideoModel, type VideoRequest, type VideoResolution, type VideoResult, type Warning, isModelKitError, liveCatalog, nearestAspectRatio, primeCatalog, resetLiveCatalog, resolveAudioOptions, resolveImageOptions, resolveOptions, resolveVideoOptions };

package/dist/catalog.js

@@ -93,6 +93,14 @@ var Catalog = class _Catalog {
       ...rows
     ]);
   }
+  /** Atomically swap every row. Builds the maps first so a bad batch throws before anything changes. */
+  replace(rows) {
+    const next = new _Catalog(rows);
+    this.byId.clear();
+    this.byAlias.clear();
+    for (const [id, model] of next.byId) this.byId.set(id, model);
+    for (const [alias, id] of next.byAlias) this.byAlias.set(alias, id);
+  }
 };
 
 // src/catalog/image.ts
@@ -1783,6 +1791,387 @@ var MODELS = [
   ...OTHER_MODELS
 ];
 
+// src/catalog/schema.ts
+import { z } from "zod";
+var ADAPTER_IDS = [
+  "ai-sdk-text",
+  "google-image",
+  "openai-image",
+  "google-genai",
+  "ark",
+  "fal",
+  "replicate",
+  "prodia",
+  "higgsfield",
+  "xai-video"
+];
+var ModelTypeSchema = z.enum(["text", "image", "video", "audio", "upscale", "bg-remove"]);
+var LifecycleSchema = z.enum(["active", "deprecated", "retired"]);
+var AdapterSchema = z.enum(ADAPTER_IDS);
+var AspectRatioSchema = z.enum([
+  "1:1",
+  "16:9",
+  "9:16",
+  "4:3",
+  "3:4",
+  "3:2",
+  "2:3",
+  "4:5",
+  "5:4",
+  "21:9",
+  "9:21",
+  "97:30",
+  "adaptive"
+]);
+var ImageSizeSchema = z.enum(["512", "1K", "2K", "4K"]);
+var VideoResolutionSchema = z.enum(["360p", "480p", "720p", "768p", "1080p", "2k", "4k"]);
+var ImageQualitySchema = z.enum(["auto", "low", "medium", "high", "xhigh", "max"]);
+var OutputFormatSchema = z.enum(["png", "jpeg", "webp"]);
+var RequiredInputSchema = z.enum(["firstFrame", "sourceVideo", "references"]);
+var SupportedOptionSchema = z.enum([
+  "seed",
+  "quality",
+  "negativePrompt",
+  "cfgScale",
+  "generateAudio",
+  "promptExpansion",
+  "lastFrame",
+  "count",
+  "outputFormat",
+  "scaleFactor",
+  "safetySettings",
+  "temperature",
+  "upscale",
+  "watermark",
+  "safetyChecker",
+  "instrumental"
+]);
+var UsageUnitSchema = z.enum([
+  "tokens",
+  "images",
+  "seconds",
+  "reported_cost_usd",
+  "compute_seconds"
+]);
+var PricingKindSchema = z.enum(["token", "image_size", "video_per_second", "flat"]);
+var ProviderOptionValueSchema = z.lazy(
+  () => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.array(ProviderOptionValueSchema),
+    z.record(z.string(), ProviderOptionValueSchema)
+  ])
+);
+var ProviderOptionsSchema = z.record(z.string(), z.record(z.string(), ProviderOptionValueSchema));
+var ReferenceLimitsSchema = z.looseObject({
+  images: z.number().optional(),
+  videos: z.number().optional(),
+  audios: z.number().optional(),
+  total: z.number().optional(),
+  audioOnly: z.boolean().optional()
+});
+var ModelConstraintsSchema = z.looseObject({
+  aspectRatios: z.array(AspectRatioSchema).optional(),
+  sizes: z.array(ImageSizeSchema).optional(),
+  resolutions: z.array(VideoResolutionSchema).optional(),
+  durations: z.union([z.looseObject({ min: z.number(), max: z.number() }), z.array(z.number())]).optional(),
+  durationPresets: z.array(z.number()).optional(),
+  qualityOptions: z.array(z.string()).optional(),
+  exactSizes: z.record(z.string(), z.string()).optional(),
+  references: ReferenceLimitsSchema.optional(),
+  requires: z.array(RequiredInputSchema).optional(),
+  supports: z.array(SupportedOptionSchema).optional(),
+  ratioIgnoredWith: z.array(z.enum(["firstFrame", "sourceVideo"])).optional()
+});
+var MediaRefSchema = z.union([
+  z.looseObject({ url: z.string(), label: z.string().optional() }),
+  z.looseObject({
+    bytes: z.instanceof(Uint8Array),
+    mime: z.string(),
+    label: z.string().optional()
+  })
+]);
+var ImageSafetySettingSchema = z.looseObject({ category: z.string(), threshold: z.string() });
+var UpscaleOptionsSchema = z.looseObject({
+  enhanceModel: z.string().optional(),
+  subjectDetection: z.string().optional(),
+  faceEnhancement: z.boolean().optional(),
+  faceEnhancementCreativity: z.number().optional(),
+  faceEnhancementStrength: z.number().optional()
+});
+var DefaultsSchema = z.looseObject({
+  references: z.array(MediaRefSchema).optional(),
+  aspectRatio: AspectRatioSchema.optional(),
+  size: ImageSizeSchema.optional(),
+  exactSize: z.string().optional(),
+  quality: ImageQualitySchema.optional(),
+  seed: z.number().optional(),
+  count: z.number().optional(),
+  outputFormat: OutputFormatSchema.optional(),
+  scaleFactor: z.number().optional(),
+  safetySettings: z.array(ImageSafetySettingSchema).optional(),
+  temperature: z.number().optional(),
+  upscale: UpscaleOptionsSchema.optional(),
+  firstFrame: MediaRefSchema.optional(),
+  lastFrame: MediaRefSchema.optional(),
+  sourceVideo: MediaRefSchema.optional(),
+  referenceImages: z.array(MediaRefSchema).optional(),
+  referenceVideos: z.array(MediaRefSchema).optional(),
+  referenceAudios: z.array(MediaRefSchema).optional(),
+  resolution: VideoResolutionSchema.optional(),
+  durationSeconds: z.number().optional(),
+  generateAudio: z.boolean().optional(),
+  negativePrompt: z.string().optional(),
+  cfgScale: z.number().optional(),
+  promptExpansion: z.enum(["fast", "balanced", "quality"]).optional(),
+  watermark: z.boolean().optional(),
+  safetyChecker: z.boolean().optional(),
+  mode: z.enum(["standard", "pro"]).optional(),
+  instrumental: z.boolean().optional()
+});
+var CatalogDisplaySchema = z.looseObject({
+  provider: z.string(),
+  description: z.string(),
+  logo: z.string().optional(),
+  costTier: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional(),
+  recommended: z.boolean().optional(),
+  sortOrder: z.number().optional(),
+  chat: z.looseObject({
+    providerOptions: ProviderOptionsSchema.optional(),
+    temperature: z.number().optional()
+  }).optional()
+});
+var CatalogCapabilitiesSchema = z.looseObject({
+  acceptsSourceVideo: z.boolean().optional(),
+  framesExcludeReferences: z.boolean().optional(),
+  reasoning: z.boolean().optional(),
+  vision: z.boolean().optional(),
+  contextWindow: z.number().optional()
+});
+var CatalogModelSchemaBase = z.looseObject({
+  id: z.string().min(1),
+  aliases: z.array(z.string()).default([]),
+  label: z.string().min(1),
+  type: ModelTypeSchema,
+  adapter: AdapterSchema,
+  providerModelId: z.string().min(1),
+  lifecycle: LifecycleSchema,
+  replacedBy: z.string().optional(),
+  exposure: z.enum(["catalog", "internal"]),
+  constraints: ModelConstraintsSchema,
+  defaults: DefaultsSchema,
+  providerOptions: ProviderOptionsSchema.optional(),
+  usage: z.looseObject({
+    unit: UsageUnitSchema,
+    slug: z.string().optional(),
+    providerLabel: z.string().optional()
+  }),
+  pricingKind: PricingKindSchema,
+  display: CatalogDisplaySchema.optional(),
+  capabilities: CatalogCapabilitiesSchema.optional()
+}).superRefine((row, ctx) => {
+  if (row.lifecycle === "active" && !row.display) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["display"],
+      message: "active rows need display"
+    });
+  }
+  if (row.lifecycle === "active" && row.type === "text" && !row.capabilities?.contextWindow) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["capabilities", "contextWindow"],
+      message: "active text rows need contextWindow"
+    });
+  }
+  if (row.replacedBy !== void 0 && row.replacedBy === row.id) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["replacedBy"],
+      message: "replacedBy must not equal id"
+    });
+  }
+});
+var CatalogModelSchema = CatalogModelSchemaBase;
+var CatalogSchema = z.array(CatalogModelSchemaBase).superRefine((rows, ctx) => {
+  const seenIds = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    if (seenIds.has(row.id)) {
+      ctx.addIssue({
+        code: "custom",
+        path: [index, "id"],
+        message: `Duplicate model id "${row.id}"`
+      });
+    } else {
+      seenIds.set(row.id, index);
+    }
+  });
+  const seenAliases = /* @__PURE__ */ new Map();
+  rows.forEach((row, index) => {
+    row.aliases.forEach((alias, aliasIndex) => {
+      const path = [index, "aliases", aliasIndex];
+      if (alias === row.id || seenIds.has(alias)) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `Alias "${alias}" collides with a model id`
+        });
+        return;
+      }
+      if (seenAliases.has(alias)) {
+        ctx.addIssue({
+          code: "custom",
+          path,
+          message: `Duplicate alias "${alias}"`
+        });
+      } else {
+        seenAliases.set(alias, index);
+      }
+    });
+  });
+});
+
+// src/catalog/live.ts
+var liveCatalog = new Catalog(MODELS);
+
+// src/catalog/load.ts
+var memo;
+var timer;
+var revision;
+var origin = "snapshot";
+function rowCount() {
+  return liveCatalog.list({ lifecycle: ["active", "deprecated", "retired"] }).length;
+}
+function authHeaders(auth) {
+  return "bearer" in auth ? { Authorization: `Bearer ${auth.bearer}` } : { "x-api-key": auth.apiKey };
+}
+function describeError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function parseEnvelope(json) {
+  if (typeof json !== "object" || json === null || !("rows" in json)) {
+    throw new Error("invalid catalog response: missing rows");
+  }
+  const rows = CatalogSchema.parse(json.rows);
+  const rev = json.revision;
+  if (typeof rev === "string") return { rows, revision: rev };
+  return { rows };
+}
+function logPrimed(logger, result) {
+  const { origin: loggedOrigin, rowCount: loggedCount, revision: loggedRevision } = result;
+  logger.info("[modelkit] catalog primed", {
+    origin: loggedOrigin,
+    rowCount: loggedCount,
+    revision: loggedRevision
+  });
+}
+async function fetchRemote(source, logger) {
+  const fetchImpl = source.fetch ?? globalThis.fetch;
+  const headers = authHeaders(source.auth);
+  if (revision !== void 0) headers["If-None-Match"] = `"${revision}"`;
+  const res = await fetchImpl(`${source.baseUrl}/models/catalog`, {
+    headers,
+    signal: AbortSignal.timeout(source.timeoutMs ?? 1e4)
+  });
+  if (res.status === 304) return { kept: true };
+  if (!res.ok) throw new Error(`catalog fetch failed with status ${res.status}`);
+  const json = await res.json();
+  const { rows, revision: rev } = parseEnvelope(json);
+  if (rev === void 0) return { rows, fromCache: false };
+  return { rows, revision: rev, fromCache: false };
+}
+async function writeCache(source, logger, rows, rev) {
+  if (!source.cache) return;
+  try {
+    await source.cache.set(JSON.stringify({ rows, revision: rev }));
+  } catch (err) {
+    logger.warn("[modelkit] catalog cache write failed", err);
+  }
+}
+async function prime(source, logger) {
+  try {
+    const fetched = await fetchRemote(source, logger);
+    if ("kept" in fetched) {
+      const result2 = { origin, rowCount: rowCount() };
+      if (revision !== void 0) result2.revision = revision;
+      logPrimed(logger, result2);
+      return result2;
+    }
+    liveCatalog.replace(fetched.rows);
+    origin = "remote";
+    revision = fetched.revision;
+    await writeCache(source, logger, fetched.rows, fetched.revision);
+    const result = { origin, rowCount: rowCount() };
+    if (fetched.revision !== void 0) result.revision = fetched.revision;
+    logPrimed(logger, result);
+    return result;
+  } catch (err) {
+    logger.warn("[modelkit] catalog remote failed, trying cache", err);
+    const error = describeError(err);
+    try {
+      const cached = await source.cache?.get();
+      if (!cached) throw new Error("no cached catalog");
+      const { rows, revision: rev } = parseEnvelope(JSON.parse(cached));
+      liveCatalog.replace(rows);
+      origin = "last-good";
+      revision = rev;
+      const result = { origin, rowCount: rowCount(), error };
+      if (rev !== void 0) result.revision = rev;
+      logPrimed(logger, result);
+      return result;
+    } catch (cacheErr) {
+      logger.warn("[modelkit] catalog cache failed, using snapshot", cacheErr);
+      liveCatalog.replace([...MODELS]);
+      origin = "snapshot";
+      revision = void 0;
+      const result = {
+        origin,
+        rowCount: rowCount(),
+        error
+      };
+      logPrimed(logger, result);
+      return result;
+    }
+  }
+}
+async function refresh(source, logger) {
+  try {
+    const fetched = await fetchRemote(source, logger);
+    if ("kept" in fetched) return;
+    liveCatalog.replace(fetched.rows);
+    origin = "remote";
+    revision = fetched.revision;
+    await writeCache(source, logger, fetched.rows, fetched.revision);
+  } catch (err) {
+    logger.warn("[modelkit] catalog refresh failed, keeping current rows", err);
+  }
+}
+function primeCatalog(source) {
+  if (memo) return memo;
+  const logger = source.logger ?? console;
+  memo = prime(source, logger).then((result) => {
+    const ttlMs = source.ttlMs ?? 3e5;
+    if (ttlMs > 0 && timer === void 0) {
+      timer = setInterval(() => void refresh(source, logger), ttlMs);
+      const maybeUnref = timer;
+      maybeUnref.unref?.();
+    }
+    return result;
+  });
+  return memo;
+}
+function resetLiveCatalog() {
+  if (timer !== void 0) {
+    clearInterval(timer);
+    timer = void 0;
+  }
+  memo = void 0;
+  revision = void 0;
+  origin = "snapshot";
+  liveCatalog.replace([...MODELS]);
+}
+
 // src/resolve-options.ts
 var SIZE_ORDER = ["512", "1K", "2K", "4K"];
 var RESOLUTION_ORDER = ["360p", "480p", "720p", "768p", "1080p", "2k", "4k"];
@@ -2165,7 +2554,10 @@ function resolveOptions(model, request, onUnsupported = "error") {
   }
 }
 export {
+  ADAPTER_IDS,
   Catalog,
+  CatalogModelSchema,
+  CatalogSchema,
   IMAGE_MODELS,
   MODELS,
   ModelKitError,
@@ -2173,7 +2565,10 @@ export {
   TEXT_MODELS,
   VIDEO_MODELS,
   isModelKitError,
+  liveCatalog,
   nearestAspectRatio,
+  primeCatalog,
+  resetLiveCatalog,
   resolveAudioOptions,
   resolveImageOptions,
   resolveOptions,