@shop-os/modelkit 0.3.2 → 0.3.3

package/CHANGELOG.md

@@ -9,6 +9,16 @@ header in the release PR.
 
 ## [Unreleased]
 
+## [0.3.3] - Unreleased
+
+### Added
+- `inputSpec.arrays` joins several image inputs into one provider array field, for a model that takes its start frame, end frame and storyboard frames in one list. It maps a provider field to an ordered list of canonical keys: `arrays: { images: ["firstFrame", "referenceImages", "lastFrame"] }` sends the first frame, then the reference images, then the last frame. The field is omitted when none of the inputs is set. Video rows take `firstFrame`, `referenceImages` and `lastFrame`; image rows take `references`. A key is mapped once: in `fields` or in one array. An array name must not repeat a `fields` provider name or a `static` key, and `lastFrame` in an array needs `lastFrame` in `constraints.supports`.
+- `sourceVideo` is an `inputSpec.fields` key on video rows, so a Replicate video row can send a source clip (for example `sourceVideo: "start_video"`). The row also needs `capabilities.acceptsSourceVideo`, or the resolver drops the clip before the adapter runs.
+- `capabilities.sourceVideoExcludesFrames`: a source video is never sent with a first frame, a last frame or reference images. `resolveVideoOptions` refuses the mix under `"error"` and drops the images with an `option_ignored` warning for each under `"coerce"`.
+
+### Live rows to add after publish
+Add a Replicate video row that uses `inputSpec.arrays` or maps `sourceVideo` (for example `black-forest-labs/flux-3`) only after every app that will call it runs 0.3.3. An older kit reads such a spec as invalid: the row stays in the catalog and every call to it fails. A row of this shape should set `capabilities.lastFrameRequiresFirstFrame`, because a lone end frame would be sent as the first element of the array.
+
 ## [0.3.2] - Unreleased
 
 ### Added

package/README.md

@@ -218,12 +218,13 @@ instead of a kit change. It is read by the Replicate and fal adapters only. `fie
 `values` remaps canonical values per key, and `static` merges literal provider fields
 last. Video rows use `VIDEO_INPUT_SPEC_KEYS` (`prompt`, `durationSeconds`,
 `aspectRatio`, `resolution`, `firstFrame`, `lastFrame`, `seed`, `negativePrompt`,
-`generateAudio`, `cfgScale`, `promptExpansion`, `referenceImages`); image rows use
+`generateAudio`, `cfgScale`, `promptExpansion`, `referenceImages`, `sourceVideo`); image rows use
 `IMAGE_INPUT_SPEC_KEYS` (`prompt`, `references`, `aspectRatio`, `size`, `outputFormat`,
 `seed`; map `references` to the provider's array field and remap `size` and `outputFormat`
 with `values`); audio rows use
 `AUDIO_INPUT_SPEC_KEYS` (`prompt`, `durationSeconds`, `seed`, `negativePrompt`,
 `references`, `sourceVideo`, `instrumental`). `aspectRatio: "adaptive"` is omitted. A fal image row has no kind and builds its whole input from the spec; the optional `editEndpoint` (fal rows only) is the fal endpoint called instead of `providerModelId` when the request has references. fal rows without an `inputSpec` keep the Muse-shaped request and Ideogram keeps its own path; an `inputSpec` on an Ideogram row replaces that path. `editEndpoint` needs a `references` entry in `fields`. `inputSpec` on fal video rows is not supported.
+`arrays` joins several image inputs into one provider array field, in the listed order: `arrays: { images: ["firstFrame", "referenceImages", "lastFrame"] }` (video rows: `firstFrame`, `referenceImages`, `lastFrame`; image rows: `references`). A key is mapped once, in `fields` or in one array, and the field is omitted when none of its inputs is set. A row that maps `sourceVideo` also needs `capabilities.acceptsSourceVideo`; set `capabilities.sourceVideoExcludesFrames` when the provider rejects a source video next to images.
 `validateInputSpec` is the shared contract the write schema, `dataOnlyCapable`, and
 the Replicate mapper all check. `dataOnlyCapable(row)` reports whether such a row would
 be served.

package/dist/catalog.cjs

@@ -2303,7 +2303,8 @@ var VIDEO_INPUT_SPEC_KEYS = [
   "generateAudio",
   "cfgScale",
   "promptExpansion",
-  "referenceImages"
+  "referenceImages",
+  "sourceVideo"
 ];
 var IMAGE_INPUT_SPEC_KEYS = [
   "prompt",
@@ -2322,6 +2323,12 @@ var AUDIO_INPUT_SPEC_KEYS = [
   "sourceVideo",
   "instrumental"
 ];
+var ARRAY_INPUT_SPEC_KEYS = [
+  "firstFrame",
+  "referenceImages",
+  "lastFrame",
+  "references"
+];
 var INPUT_SPEC_SUPPORTS_KEYS = [
   "lastFrame",
   "seed",
@@ -2335,6 +2342,7 @@ var INPUT_SPEC_SUPPORTS_KEYS = [
 var VIDEO_KEY_SET = new Set(VIDEO_INPUT_SPEC_KEYS);
 var IMAGE_KEY_SET = new Set(IMAGE_INPUT_SPEC_KEYS);
 var AUDIO_KEY_SET = new Set(AUDIO_INPUT_SPEC_KEYS);
+var ARRAY_KEY_SET = new Set(ARRAY_INPUT_SPEC_KEYS);
 var ALL_KEY_SET = /* @__PURE__ */ new Set([
   ...VIDEO_INPUT_SPEC_KEYS,
   ...IMAGE_INPUT_SPEC_KEYS,
@@ -2379,13 +2387,30 @@ var ValuesSchema = import_zod2.z.record(import_zod2.z.string(), import_zod2.z.re
   }
 });
 var StaticSchema = import_zod2.z.record(import_zod2.z.string(), ProviderScalarSchema);
+var ArraysSchema = import_zod2.z.record(import_zod2.z.string().min(1), import_zod2.z.array(import_zod2.z.string()).min(1)).superRefine((arrays, ctx) => {
+  for (const [name, keys] of Object.entries(arrays)) {
+    for (const key of keys) {
+      if (!ARRAY_KEY_SET.has(key)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [name],
+          message: `inputSpec.arrays "${name}" has unknown image key "${key}"`
+        });
+      }
+    }
+  }
+});
 var InputSpecSchema = import_zod2.z.strictObject({
   fields: FieldsSchema,
   values: ValuesSchema.optional(),
   static: StaticSchema.optional(),
+  arrays: ArraysSchema.optional(),
   editEndpoint: import_zod2.z.string().min(1).optional()
 }).superRefine((spec, ctx) => {
-  const mappedNames = new Set(Object.values(spec.fields));
+  const mappedNames = /* @__PURE__ */ new Set([
+    ...Object.values(spec.fields),
+    ...Object.keys(spec.arrays ?? {})
+  ]);
   for (const key of Object.keys(spec.static ?? {})) {
     if (mappedNames.has(key)) {
       ctx.addIssue({
@@ -2474,14 +2499,54 @@ function validateInputSpec(raw, row) {
       });
     }
   }
+  const arrayOwner = /* @__PURE__ */ new Map();
+  for (const [name, keys] of Object.entries(spec.arrays ?? {})) {
+    const fieldKey = seenNames.get(name);
+    if (fieldKey !== void 0) {
+      issues.push({
+        path: ["arrays", name],
+        message: `inputSpec.arrays "${name}" is also the provider field of inputSpec.fields "${fieldKey}"`
+      });
+    }
+    for (const key of keys) {
+      if (allowed !== void 0 && !allowed.has(key)) {
+        issues.push({
+          path: ["arrays", name],
+          message: `inputSpec.arrays "${key}" is not supported for ${row.type} rows`
+        });
+      }
+      if (key in spec.fields) {
+        issues.push({
+          path: ["arrays", name],
+          message: `inputSpec.arrays "${key}" is already mapped in inputSpec.fields`
+        });
+      }
+      const owner = arrayOwner.get(key);
+      if (owner === void 0) arrayOwner.set(key, name);
+      else {
+        issues.push({
+          path: ["arrays", name],
+          message: owner === name ? `inputSpec.arrays "${name}" lists "${key}" twice` : `inputSpec.arrays "${owner}" and "${name}" both take "${key}"`
+        });
+      }
+    }
+  }
   const supports = row.constraints.supports ?? [];
   for (const key of INPUT_SPEC_SUPPORTS_KEYS) {
-    if (key in spec.fields && !supports.includes(key)) {
+    if (supports.includes(key)) continue;
+    if (key in spec.fields) {
       issues.push({
         path: ["fields", key],
         message: `inputSpec.fields "${key}" needs "${key}" in constraints.supports`
       });
     }
+    const arrayName = arrayOwner.get(key);
+    if (arrayName !== void 0) {
+      issues.push({
+        path: ["arrays", arrayName],
+        message: `inputSpec.arrays "${key}" needs "${key}" in constraints.supports`
+      });
+    }
   }
   if (issues.length > 0) return { ok: false, issues };
   return { ok: true, spec };
@@ -2703,6 +2768,7 @@ var CatalogCapabilitiesSchema = import_zod3.z.looseObject({
   acceptsSourceVideo: import_zod3.z.boolean().optional(),
   videoEdit: import_zod3.z.boolean().optional(),
   framesExcludeReferences: import_zod3.z.boolean().optional(),
+  sourceVideoExcludesFrames: import_zod3.z.boolean().optional(),
   lastFrameRequiresFirstFrame: import_zod3.z.boolean().optional(),
   reasoning: import_zod3.z.boolean().optional(),
   vision: import_zod3.z.boolean().optional(),
@@ -3400,6 +3466,26 @@ function resolveVideoOptions(model, request, onUnsupported = "error") {
     });
     delete merged.sourceVideo;
   }
+  const imageInputs = ["firstFrame", "lastFrame", "referenceImages"].filter(
+    (field) => field === "referenceImages" ? compact(merged.referenceImages).length > 0 : merged[field] !== void 0
+  );
+  if (merged.sourceVideo !== void 0 && imageInputs.length > 0 && model.capabilities?.sourceVideoExcludesFrames) {
+    if (onUnsupported === "error") {
+      throw new ModelKitError({
+        code: "unsupported_option",
+        message: `${model.id} takes a source video or images, not both`,
+        model: model.id
+      });
+    }
+    for (const field of imageInputs) {
+      warnings.push({
+        code: "option_ignored",
+        field,
+        message: `${model.id} takes a source video or images, not both; ${field} dropped`
+      });
+      delete merged[field];
+    }
+  }
   if (merged.lastFrame !== void 0 && merged.firstFrame === void 0 && model.capabilities?.lastFrameRequiresFirstFrame) {
     if (onUnsupported === "error") {
       throw new ModelKitError({