@shop-os/modelkit 0.1.3 → 0.1.4

package/README.md

@@ -89,13 +89,13 @@ cannot express (image `quality`/`outputFormat`, video `sourceVideo`, tiered
 `resolution`, ...) is dropped with an `option_ignored` warning, never silently. Use it
 for a model the catalog does not carry yet; the next step is a catalog row.
 
-| `ai` function                                                                                   | Here                                                                                                                                                                                                                                                   |
-| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `generateText`, `streamText`                                                                    | Same. Catalog `providerOptions` are merged under the caller's; `prepareStep` model switches resolve through the catalog; usage per step.                                                                                                               |
-| `generateObject`, `streamObject`                                                                | Same, including `output: "array" \| "enum" \| "no-schema"`.                                                                                                                                                                                            |
-| `generateImage`                                                                                 | Takes `n`, `size: "WxH"`, `aspectRatio`, `seed`, `abortSignal`, `providerOptions` plus the kit's `references`, `size: "2K"`, `quality`, `outputFormat`. Returns `image` and `images` with `uint8Array`, `base64`, `mediaType` next to `bytes`, `mime`. |
-| `experimental_generateVideo`                                                                    | The kit's `generateVideo` returns a job; `duration` is an alias of `durationSeconds`. An `ai` video model instance is wrapped as a settled job. The `ai` function is also re-exported as-is.                                                           |
-| `experimental_generateSpeech`, `transcribe`, `embed`, `embedMany`, `rerank`, agents, UI streams | Re-exported from `ai` unchanged; the catalog has no rows for them.                                                                                                                                                                                     |
+| `ai` function                                                                                   | Here                                                                                                                                                                                                                                                                                                                              |
+| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `generateText`, `streamText`                                                                    | Same. Catalog `providerOptions` are merged under the caller's; `prepareStep` model switches resolve through the catalog; usage per step.                                                                                                                                                                                          |
+| `generateObject`, `streamObject`                                                                | Same, including `output: "array" \| "enum" \| "no-schema"`.                                                                                                                                                                                                                                                                       |
+| `generateImage`                                                                                 | Takes `n`, `size: "WxH"`, `aspectRatio`, `seed`, `abortSignal`, `providerOptions` plus the kit's `references`, `size: "2K"`, `quality`, `outputFormat`, `scaleFactor` (upscalers). Returns `image` and `images` with `uint8Array`, `base64`, `mediaType` next to `bytes`, `mime`; `outputUrl` when the provider hands back a URL. |
+| `experimental_generateVideo`                                                                    | The kit's `generateVideo` returns a job; `duration` is an alias of `durationSeconds`. An `ai` video model instance is wrapped as a settled job. The `ai` function is also re-exported as-is.                                                                                                                                      |
+| `experimental_generateSpeech`, `transcribe`, `embed`, `embedMany`, `rerank`, agents, UI streams | Re-exported from `ai` unchanged; the catalog has no rows for them.                                                                                                                                                                                                                                                                |
 
 An optional second `CallContext` argument selects enterprise keys, adds cancellation
 (combined with `abortSignal`), and sets `onUnsupported`. Package-level functions read
@@ -117,16 +117,16 @@ The kit keeps its `Warning` type for coercions; the SDK's warning type is `AiWar
 
 ## What the package owns
 
-| Concern     | Rule                                                                                                                                                                                                                                                                                                                        |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Ids         | `id` is the pro-backend pricing key. Every historical id (`nb-pro`, `veo-3.1-generate-001`, `kling-v2.5-turbo-pro`) is an alias.                                                                                                                                                                                            |
-| Options     | `resolveOptions` fills catalog defaults, coerces aspect ratio to the nearest supported one, errors on unsupported size or resolution (`onUnsupported: "coerce"` snaps down instead), clamps duration, trims references (audio first, then video), and drops options the model ignores with a warning.                       |
-| Keys        | Enterprise keys win only when every key the adapter (and its route, e.g. the cloudflare token for gateway-routed text) needs is set on the enterprise tier.                                                                                                                                                                 |
-| Routing     | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions. OpenRouter optional for text.                                                                                                                                                                                |
-| Retry       | One classifier. Never on content blocks or 4xx except 429.                                                                                                                                                                                                                                                                  |
-| Errors      | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`.                                                                                                                                                                                               |
-| Usage       | One event per call with the canonical model id. Video usage is emitted on completion. Audio: Lyria 3 returns no duration, so it emits `unit: "images", quantity: 1` (token counts ride along as `inputTokens`/`outputTokens`); Replicate audio (Lyria 2, MMAudio) emits `unit: "compute_seconds"` with the prediction time. |
-| Media parts | `prepareMediaPart` turns a `MediaRef` into an AI SDK file part. Google inlines bytes up to 20 MB and uploads larger payloads through the Files API; call the returned `cleanup` after the request. Other providers get the reference inline.                                                                                |
+| Concern     | Rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Ids         | `id` is the pro-backend pricing key. Every historical id (`nb-pro`, `veo-3.1-generate-001`, `kling-v2.5-turbo-pro`) is an alias.                                                                                                                                                                                                                                                                                                                                                |
+| Options     | Image tiers are `512` (Gemini 3.1 Flash only), `1K`, `2K`, `4K`. `resolveOptions` fills catalog defaults, coerces aspect ratio to the nearest supported one, errors on unsupported size or resolution (`onUnsupported: "coerce"` snaps down instead), clamps duration, trims references (audio first, then video), and drops options the model ignores with a warning.                                                                                                          |
+| Keys        | Enterprise keys win only when every key the adapter (and its route, e.g. the cloudflare token for gateway-routed text) needs is set on the enterprise tier.                                                                                                                                                                                                                                                                                                                     |
+| Routing     | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions. OpenRouter optional for text.                                                                                                                                                                                                                                                                                                                                    |
+| Retry       | One classifier. Never on content blocks or 4xx except 429.                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| Errors      | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`.                                                                                                                                                                                                                                                                                                                                                   |
+| Usage       | One event per call with the canonical model id. Gemini image events carry the token counts too (`inputTokens`/`outputTokens`); Google's raw `usageMetadata` rides on `raw.providerMetadata.google`. Video usage is emitted on completion. Audio: Lyria 3 returns no duration, so it emits `unit: "images", quantity: 1` (token counts ride along as `inputTokens`/`outputTokens`); Replicate audio (Lyria 2, MMAudio) emits `unit: "compute_seconds"` with the prediction time. |
+| Media parts | `prepareMediaPart` turns a `MediaRef` into an AI SDK file part. Google inlines bytes up to 20 MB and uploads larger payloads through the Files API; call the returned `cleanup` after the request. Other providers get the reference inline.                                                                                                                                                                                                                                    |
 
 ## Add a model
 

package/dist/index.cjs

@@ -165,7 +165,18 @@ var Catalog = class _Catalog {
 
 // src/catalog/image.ts
 var IMAGE_USAGE = { unit: "images", modality: "IMAGE" };
-var GEMINI_RATIOS = ["1:1", "16:9", "9:16", "4:3", "3:4", "21:9", "4:5", "5:4"];
+var GEMINI_RATIOS = [
+  "1:1",
+  "2:3",
+  "3:2",
+  "16:9",
+  "9:16",
+  "4:3",
+  "3:4",
+  "21:9",
+  "4:5",
+  "5:4"
+];
 function geminiImage(id, label, aliases, sizes) {
   const model = {
     id,
@@ -188,7 +199,8 @@ var IMAGE_MODELS = [
     "gemini-3.1-flash-image-preview",
     "Nano Banana Flash",
     ["nb-2"],
-    ["1K", "2K", "4K"]
+    // Flash 3.1 is the only Gemini image model with the 512 tier.
+    ["512", "1K", "2K", "4K"]
   ),
   geminiImage("gemini-3.1-flash-lite-image", "Nano Banana Lite", ["nb-lite"], ["1K"]),
   // trigger-workflows validates 1K only; pricing seeds 2K/4K rows so allow all three.
@@ -533,8 +545,12 @@ var OTHER_MODELS = [
     adapter: "replicate",
     providerModelId: "topazlabs/image-upscale",
     lifecycle: "active",
-    constraints: {},
-    defaults: {},
+    constraints: {
+      references: { images: 1 },
+      requires: ["references"],
+      supports: ["scaleFactor", "outputFormat"]
+    },
+    defaults: { scaleFactor: 2, outputFormat: "png" },
     usage: { unit: "compute_seconds", modality: "IMAGE" },
     pricingKind: "flat"
   },
@@ -590,7 +606,7 @@ var TEXT_MODELS = [
   text("gpt-5.6-sol", "GPT-5.6 Sol", "gpt-5.6-sol"),
   // Library key "claude-sonnet-4.5" maps to the SDK id "claude-sonnet-4-5".
   text("claude-sonnet-4-5", "Claude Sonnet 4.5", "claude-sonnet-4-5", {
-    aliases: ["claude-sonnet-4.5"]
+    aliases: ["claude-sonnet-4.5", "claude-sonnet-4-5-20250929"]
   }),
   // Anthropic retired the dated 4.0 ids; callers that still send them get 4.6.
   text("claude-sonnet-4-6", "Claude Sonnet 4.6", "claude-sonnet-4-6", {
@@ -606,7 +622,7 @@ var TEXT_MODELS = [
     aliases: ["claude-opus-4.8", "claude-opus-4", "claude-opus-4.0", "claude-opus-4-20250514"]
   }),
   text("claude-haiku-4-5", "Claude Haiku 4.5", "claude-haiku-4-5", {
-    aliases: ["claude-haiku-4.5", "claude-haiku-4-5-20251001"]
+    aliases: ["claude-haiku-4.5", "claude-haiku-4-5-20251001", "claude-haiku-4"]
   }),
   text("claude-opus-5", "Claude Opus 5", "claude-opus-5", {
     aliases: ["claude-opus-5.0"]
@@ -1089,7 +1105,7 @@ var MODELS = [
 ];
 
 // src/resolve-options.ts
-var SIZE_ORDER = ["1K", "2K", "4K"];
+var SIZE_ORDER = ["512", "1K", "2K", "4K"];
 var RESOLUTION_ORDER = ["360p", "480p", "720p", "768p", "1080p", "2k", "4k"];
 function ratioValue(r) {
   if (r === "adaptive") return 1;
@@ -1221,7 +1237,13 @@ function resolveImageOptions(model, request, onUnsupported = "error") {
       model: model.id
     });
   }
-  dropUnsupported(merged, model, warnings, ["seed", "quality", "count", "outputFormat"]);
+  dropUnsupported(merged, model, warnings, [
+    "seed",
+    "quality",
+    "count",
+    "outputFormat",
+    "scaleFactor"
+  ]);
   return { request: merged, warnings };
 }
 function resolveVideoOptions(model, request, onUnsupported = "error") {
@@ -1995,6 +2017,7 @@ function createModelKit(config, adapters) {
       providerOptions,
       references,
       exactSize: exactSizeField,
+      scaleFactor,
       quality: _quality,
       outputFormat: _outputFormat
     } = req;
@@ -2020,6 +2043,8 @@ function createModelKit(config, adapters) {
     if (_quality !== void 0) pushIgnored(warnings, "quality", _quality, model.modelId);
     if (_outputFormat !== void 0)
       pushIgnored(warnings, "outputFormat", _outputFormat, model.modelId);
+    if (scaleFactor !== void 0)
+      pushIgnored(warnings, "scaleFactor", scaleFactor, model.modelId);
     const abortSignal = combineSignals(req.abortSignal, call.signal);
     if (abortSignal) options.abortSignal = abortSignal;
     const result = await (0, import_ai2.generateImage)(options);
@@ -4077,6 +4102,10 @@ function createGoogleImageAdapter(deps = defaultGoogleImageDeps) {
         imageQuality: "auto"
       };
       if (req.size !== void 0) usage2.imageSize = req.size;
+      if (result.usage?.inputTokens !== void 0)
+        usage2.inputTokens = result.usage.inputTokens;
+      if (result.usage?.outputTokens !== void 0)
+        usage2.outputTokens = result.usage.outputTokens;
       return { images, usage: usage2, raw: result };
     }
   };
@@ -4608,7 +4637,7 @@ function aspectRatioToSize(ratio, tier) {
   };
   const MIN_PIXELS = 655360;
   const MAX_PIXELS = 8294400;
-  const maxLong = TIER_LONG_EDGE[tier];
+  const maxLong = TIER_LONG_EDGE[tier] ?? 1024;
   const RATIO_MAP = /* @__PURE__ */ new Map([
     ["1:1", [1, 1]],
     ["16:9", [16, 9]],
@@ -5242,6 +5271,9 @@ function isUpscaler(providerModelId) {
   const id = isLower(providerModelId);
   return id.includes("upscal") || id.includes("crystal") || id.includes("topaz");
 }
+function isTopazUpscaler(providerModelId) {
+  return isLower(providerModelId).includes("topazlabs/image-upscale");
+}
 function isQwen(providerModelId) {
   return isLower(providerModelId).includes("qwen");
 }
@@ -5291,8 +5323,36 @@ function wanImageSize(aspectRatio, size) {
 }
 async function generateReplicateImage(req, ctx, deps) {
   const id = ctx.model.providerModelId;
-  const input = { prompt: req.prompt };
-  if (isUpscaler(id)) {
+  let input;
+  if (isTopazUpscaler(id)) {
+    const first = (req.references ?? [])[0];
+    if (!first) {
+      throw new ModelKitError({
+        code: "missing_input",
+        message: `${ctx.model.id} requires a reference image to upscale`,
+        provider: "replicate",
+        model: ctx.model.id,
+        retryable: false
+      });
+    }
+    let format = req.outputFormat === "jpeg" ? "jpg" : req.outputFormat ?? "png";
+    if (format !== "png" && format !== "jpg") {
+      ctx.warnings.push({
+        code: "option_ignored",
+        field: "outputFormat",
+        from: format,
+        message: "topazlabs/image-upscale supports only png and jpg; using png"
+      });
+      format = "png";
+    }
+    input = {
+      image: refToUrl3(first),
+      enhance_model: "Standard V2",
+      output_format: format,
+      upscale_factor: `${req.scaleFactor ?? 2}x`,
+      face_enhancement: true
+    };
+  } else if (isUpscaler(id)) {
     const refs = req.references ?? [];
     const first = refs[0];
     if (!first) {
@@ -5304,24 +5364,29 @@ async function generateReplicateImage(req, ctx, deps) {
         retryable: false
       });
     }
-    input.image = refToUrl3(first);
-    input.creativity = 0;
-    input.scale_factor = 2;
-    input.output_format = "png";
+    const imageInput = { prompt: req.prompt };
+    imageInput.image = refToUrl3(first);
+    imageInput.creativity = 0;
+    imageInput.scale_factor = 2;
+    imageInput.output_format = "png";
+    input = imageInput;
   } else if (isWanImage(id)) {
     const refs = (req.references ?? []).map(refToUrl3);
-    if (refs.length > 0) input.images = refs;
-    input.size = wanImageSize(req.aspectRatio, req.size);
+    const imageInput = { prompt: req.prompt };
+    if (refs.length > 0) imageInput.images = refs;
+    imageInput.size = wanImageSize(req.aspectRatio, req.size);
+    input = imageInput;
   } else if (isQwen(id)) {
     const refs = (req.references ?? []).map(refToUrl3);
     const firstUrl = refs[0];
+    const imageInput = { prompt: req.prompt };
     if (firstUrl !== void 0) {
-      input.image = firstUrl;
-      if (!isQwenEditPlus(id)) input.match_input_image = true;
+      imageInput.image = firstUrl;
+      if (!isQwenEditPlus(id)) imageInput.match_input_image = true;
     }
     const ratios = isQwenEditPlus(id) ? QWEN_EDIT_RATIOS : QWEN_IMAGE_RATIOS;
     if (req.aspectRatio !== void 0) {
-      if (ratios.has(req.aspectRatio)) input.aspect_ratio = req.aspectRatio;
+      if (ratios.has(req.aspectRatio)) imageInput.aspect_ratio = req.aspectRatio;
       else
         ctx.warnings.push({
           code: "option_ignored",
@@ -5331,18 +5396,21 @@ async function generateReplicateImage(req, ctx, deps) {
         });
     }
     if (isQwenEditPlus(id) && req.outputFormat !== void 0) {
-      input.output_format = req.outputFormat === "jpeg" ? "jpg" : req.outputFormat;
+      imageInput.output_format = req.outputFormat === "jpeg" ? "jpg" : req.outputFormat;
     }
+    input = imageInput;
   } else {
     const refs = req.references ?? [];
     const first = refs[0];
-    if (first) input.image = refToUrl3(first);
+    const imageInput = { prompt: req.prompt };
+    if (first) imageInput.image = refToUrl3(first);
+    input = imageInput;
   }
   const { url, predictTime, raw } = await runPrediction(ctx, input, deps);
   const file = await download(ctx, url);
   const usage2 = imageUsage2(ctx, req);
   usage2.quantity = predictTime;
-  return { images: [{ bytes: file.bytes, mime: file.mime }], usage: usage2, raw };
+  return { images: [{ bytes: file.bytes, mime: file.mime }], usage: usage2, raw, outputUrl: url };
 }
 function wanSize(aspectRatio) {
   if (!aspectRatio || aspectRatio === "adaptive" || aspectRatio === "1:1") return "2K";