Skip to content

armgit / hypit

Public Imported from GitHub
0

Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.

refactor: let models declare their input ports

kashorin327d9cfa2990
diff --git a/README.md b/README.md
index 532aa1f8..961eb4c0 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,7 @@ The repository implements:
- recoverable Runtime scheduling with concurrency lanes, retries and cancellation;
- SQLite Build/Operation stores and filesystem/S3 Artifact stores;
- exact Endpoint binding and scoped credentials;
-- seven explicit image/video model families through the KIE Provider;
+- eleven exact image/video models declaring their own input ports, reached through the KIE Provider;
- local ffprobe/ffmpeg media processing;
- local pinned WhisperX service;
- Vertex Gemini display-only Caption planning;
diff --git a/docs/README.md b/docs/README.md
index ba770cf1..7c1958bb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -20,6 +20,8 @@ the working tree contains only documents that should inform current implementati
- [`graph-first-value-boundary.md`](./graph-first-value-boundary.md) — graph edges own
dependency truth; values contain only intrinsic meaning.
+- [`model-input-ports.md`](./model-input-ports.md) — models declare the inputs they accept;
+ Providers only map those ports onto their own wire.
- [`node-package-activation.md`](./node-package-activation.md) — trusted installed package
locking, contributions and Host-selected facet activation.
- [`local-developer-runtime.md`](./local-developer-runtime.md) — local SQLite/filesystem
diff --git a/examples/echo-pro-aroll/svml.packages.lock b/examples/echo-pro-aroll/svml.packages.lock
index 45fce0d4..2cbe3256 100644
--- a/examples/echo-pro-aroll/svml.packages.lock
+++ b/examples/echo-pro-aroll/svml.packages.lock
@@ -49,7 +49,7 @@
{
"name": "@narratage/generation",
"version": "0.0.0-dev",
- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"
+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"
},
{
"name": "@narratage/host",
@@ -74,7 +74,7 @@
{
"name": "@narratage/model-kit",
"version": "0.0.0-dev",
- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"
+ "digest": "sha256:71b23848a90535e0cd74b25f4ef74a9827ce1aa0abdfe4eb34cc1dc3d907ce13"
},
{
"name": "@narratage/narrative",
@@ -119,12 +119,12 @@
{
"name": "@narratage/seedance-speaker",
"version": "0.0.0-dev",
- "digest": "sha256:35c343bb6bee8cab1ac6d579231b74cf44c946ba634f9029b2c2647770f95390"
+ "digest": "sha256:3f17790a7be2768aeed20d53a9db9bec47088425d0c2303ec80f0ceeb787bc14"
},
{
"name": "@narratage/seedance",
"version": "0.0.0-dev",
- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"
+ "digest": "sha256:f550f1f9278056b349c6f4f536e8d8694ff3cc1d01395c30a1384332fc034f5d"
},
{
"name": "@narratage/semantic-map",
@@ -249,7 +249,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:c52730036a392448eb17cada1dd16b22be9ecb721ba47fb8d8a8633f74e4e039",
- "closureDigest": "sha256:ab382976a8fd6caed8cc59060774edae9a4158c8a341073d80b3bcd9c50640e1"
+ "closureDigest": "sha256:74985d499a527c256c23191b188ca3d061d25f1e5fae91136460918438090b5b"
},
{
"specifier": "@narratage/hyperframes",
@@ -338,8 +338,8 @@
"name": "@narratage/seedance",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:aca85f68a54101516b734a0aafa7e819ac2ce670f595ae1084ac493b2bdafb95",
- "closureDigest": "sha256:023e18468d9a78f1f32ea42ea087176e1c7d076a2908f2bff78397ad01ccdbd4"
+ "facetsDigest": "sha256:33c8544ab99b77c94af25a4620bf17e0b1b994cc505616933878c8ece586f666",
+ "closureDigest": "sha256:4afcf602ed33934feaaec18babbcebe016b51a310ef6c56f5a94363201cfd393"
},
{
"specifier": "@narratage/seedance-speaker",
@@ -347,8 +347,8 @@
"name": "@narratage/seedance-speaker",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:1e3d927202604abb930a2ab11faf7a7baa25842ccc36265ec76357aefdc52413",
- "closureDigest": "sha256:6a521923e295045e19cd1d4b401026a665ea8621091928fd87b6278dfaf71766"
+ "facetsDigest": "sha256:7e53dd24fcc24b2cf3aff7bb10671132251c37a38d20223e33c95f129a8213a9",
+ "closureDigest": "sha256:343324cedfb20314deee174feec7d1b7ba9c3e19595d11ab106a5b9ead391fa4"
},
{
"specifier": "@narratage/semantic-map",
@@ -432,5 +432,5 @@
"closureDigest": "sha256:777e0f036d3213461c2d441c30869e26206e1cbaea318dc213244a224444fcf3"
}
],
- "digest": "sha256:9275d7c9c622473cab556abf9806dc61e438ca607d4455517246fe173d6a61e1"
+ "digest": "sha256:497a10ed9bc11fe41f65ad78816fd352e521eaf429c52c45c336d31a60b6a2cf"
}
diff --git a/examples/echo-pro-aroll/svml.runtime-packages.lock b/examples/echo-pro-aroll/svml.runtime-packages.lock
index ad062cc8..7497ae98 100644
--- a/examples/echo-pro-aroll/svml.runtime-packages.lock
+++ b/examples/echo-pro-aroll/svml.runtime-packages.lock
@@ -66,25 +66,10 @@
"version": "0.0.0-dev",
"digest": "sha256:2f377c58c0dbec426d90adcb4794356507b3b4c55eb3d2533f54b44fcc20be03"
},
- {
- "name": "@narratage/gemini-omni",
- "version": "0.0.0-dev",
- "digest": "sha256:81a6cf3606f087085eb539a107a2d0f944a10bfd54ac6b8d0c5eae540d73b252"
- },
{
"name": "@narratage/generation",
"version": "0.0.0-dev",
- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"
- },
- {
- "name": "@narratage/gpt-image",
- "version": "0.0.0-dev",
- "digest": "sha256:03888009b4ecf8be1c31ce0b8e54a5e8ba72073828833ea60ba8975f89ce6809"
- },
- {
- "name": "@narratage/grok-imagine",
- "version": "0.0.0-dev",
- "digest": "sha256:3aa49200686fb185442e52871f1e32ec58ce733e30567cc929fe39b92e91439f"
+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"
},
{
"name": "@narratage/host",
@@ -106,21 +91,6 @@
"version": "0.0.0-dev",
"digest": "sha256:d92f53d5060df53a7a671b58b8c0d1305be99384bd34e71bda0f7f1296550f4b"
},
- {
- "name": "@narratage/minimax-h3",
- "version": "0.0.0-dev",
- "digest": "sha256:2662e852ca9d8c61cefdf33895220c7adeedfede13973513e4c9ae3e5940b4de"
- },
- {
- "name": "@narratage/model-kit",
- "version": "0.0.0-dev",
- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"
- },
- {
- "name": "@narratage/nano-banana",
- "version": "0.0.0-dev",
- "digest": "sha256:254cd027bfc5937a5d09865f574f7512bfcc2070056e842068061f1fc61cce6f"
- },
{
"name": "@narratage/narrative",
"version": "0.0.0-dev",
@@ -149,7 +119,7 @@
{
"name": "@narratage/provider-kie",
"version": "0.0.0-dev",
- "digest": "sha256:1333e4b33f80224db0052765ce0f3a9c3f47c9bc03eede4becaea53d5d15f24a"
+ "digest": "sha256:9dde6cc353d5d3af0a6c3b857b9a4ddb18c2b5a0c1b3642642b7772e74e1144c"
},
{
"name": "@narratage/provider-media-local",
@@ -181,16 +151,6 @@
"version": "0.0.0-dev",
"digest": "sha256:3d5bd79233f3f78633b427740e2efa4ce2720195a91cd50e0ced94f054471c2a"
},
- {
- "name": "@narratage/seedance",
- "version": "0.0.0-dev",
- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"
- },
- {
- "name": "@narratage/seedream",
- "version": "0.0.0-dev",
- "digest": "sha256:6ca275e237cd04b0a15d10c690abfe54d08b1cbe458c45bb564a3af1a9aebc7b"
- },
{
"name": "@narratage/semantic-map",
"version": "0.0.0-dev",
@@ -908,7 +868,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:e61ebb911a33d4c5d0e4e4ee4fb69cdb790f4ced050ef35f7472bfbd72013d9b",
- "closureDigest": "sha256:af79dec340e8f700efbe31c8925af468bab09bd5153831ba89516f8b96193eed"
+ "closureDigest": "sha256:b68e74e3a4c97b465610a137d221af97a5cf2c4b0cec535657d74922242d5bbd"
},
{
"specifier": "@narratage/provider-media-local",
@@ -929,5 +889,5 @@
"closureDigest": "sha256:723c10f0112c7b9d2dff11ba214ae3d595bfcebdf09644703401972818375de0"
}
],
- "digest": "sha256:e04400ffa7fc06fee8659853b74468b9cb300c0d07758f5c4d3b5480a53e35c1"
+ "digest": "sha256:04a5e7e90430a98090200a05e5d53e3fe7c552f6a5e790c090f8ab111db4c832"
}
diff --git a/examples/talking-film-graph-check/svml.packages.lock b/examples/talking-film-graph-check/svml.packages.lock
index 809322bc..74d69984 100644
--- a/examples/talking-film-graph-check/svml.packages.lock
+++ b/examples/talking-film-graph-check/svml.packages.lock
@@ -49,7 +49,7 @@
{
"name": "@narratage/generation",
"version": "0.0.0-dev",
- "digest": "sha256:280b7f009d0f5c93c171cbf167d21e5ee2cf415fbb0ce885f1b9fa05b1833c29"
+ "digest": "sha256:517aa8e72c832175bd09fb711a091fcab5e8d16af3fa0e6c302dc4b73afe277f"
},
{
"name": "@narratage/host",
@@ -74,7 +74,7 @@
{
"name": "@narratage/model-kit",
"version": "0.0.0-dev",
- "digest": "sha256:195208129c357c8b48dd38977557a8c9f87e3bbd3c162e2e51e17db0f56bf874"
+ "digest": "sha256:71b23848a90535e0cd74b25f4ef74a9827ce1aa0abdfe4eb34cc1dc3d907ce13"
},
{
"name": "@narratage/narrative",
@@ -114,7 +114,7 @@
{
"name": "@narratage/seedance",
"version": "0.0.0-dev",
- "digest": "sha256:872fe63f9a1d36d071aec4baa4764cc14e99e807a21a446f0a19788ef37a48ec"
+ "digest": "sha256:f550f1f9278056b349c6f4f536e8d8694ff3cc1d01395c30a1384332fc034f5d"
},
{
"name": "@narratage/semantic-map",
@@ -244,7 +244,7 @@
"version": "0.0.0-dev"
},
"facetsDigest": "sha256:c52730036a392448eb17cada1dd16b22be9ecb721ba47fb8d8a8633f74e4e039",
- "closureDigest": "sha256:ab382976a8fd6caed8cc59060774edae9a4158c8a341073d80b3bcd9c50640e1"
+ "closureDigest": "sha256:74985d499a527c256c23191b188ca3d061d25f1e5fae91136460918438090b5b"
},
{
"specifier": "@narratage/hyperframes",
@@ -324,8 +324,8 @@
"name": "@narratage/seedance",
"version": "0.0.0-dev"
},
- "facetsDigest": "sha256:aca85f68a54101516b734a0aafa7e819ac2ce670f595ae1084ac493b2bdafb95",
- "closureDigest": "sha256:023e18468d9a78f1f32ea42ea087176e1c7d076a2908f2bff78397ad01ccdbd4"
+ "facetsDigest": "sha256:33c8544ab99b77c94af25a4620bf17e0b1b994cc505616933878c8ece586f666",
+ "closureDigest": "sha256:4afcf602ed33934feaaec18babbcebe016b51a310ef6c56f5a94363201cfd393"
},
{
"specifier": "@narratage/semantic-map",
@@ -418,5 +418,5 @@
"closureDigest": "sha256:777e0f036d3213461c2d441c30869e26206e1cbaea318dc213244a224444fcf3"
}
],
- "digest": "sha256:368f3a799ac566877e1625fa1c97594a9850dfb1343bb721d3e41745c4796eb9"
+ "digest": "sha256:1a445f5c6c074683776245b048ce1ad4fec53e1e0d7b178560fff431a9e3b77b"
}
diff --git a/packages/gemini-omni/src/index.ts b/packages/gemini-omni/src/index.ts
index 75d736f4..ae61a2aa 100644
--- a/packages/gemini-omni/src/index.ts
+++ b/packages/gemini-omni/src/index.ts
@@ -1,118 +1,54 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const geminiOmniModuleRef = { name: "@narratage/gemini-omni", version: "0.0.0-dev" } as const;
-export type GeminiOmniVideoReference = {
- readonly artifact: BlobRef;
- readonly startSec: number;
- readonly endSec: number;
-};
-
-export type GeminiOmniRequestContent = {
- readonly contract: "svml.gemini-omni-request@1";
- readonly model: "gemini-omni-video";
- readonly prompt: string;
- readonly durationSec: 4 | 6 | 8 | 10;
- readonly aspectRatio: "16:9" | "9:16";
- readonly resolution: "720p" | "1080p" | "4k";
- readonly seed?: number;
- readonly images?: readonly BlobRef[];
- /** KIE Gemini Omni opaque audio assets; ordinary audio BlobRefs are deliberately not disguised as these IDs. */
- readonly audioIds?: readonly string[];
- readonly videos?: readonly GeminiOmniVideoReference[];
- readonly characterIds?: readonly string[];
-};
-export type GeminiOmniRequest = GeminiOmniRequestContent;
-
-const idSchema = { kind: "string", minLength: 1, maxLength: 255 } as const satisfies ValueSchema;
-export const geminiOmniRequestSchema = generationObjectSchema({
- contract: { schema: { kind: "literal", value: "svml.gemini-omni-request@1" } },
- model: { schema: { kind: "literal", value: "gemini-omni-video" } },
- prompt: { schema: generationPromptSchema },
- durationSec: {
- schema: {
- kind: "oneOf",
- variants: [4, 6, 8, 10].map((value) => ({ kind: "literal" as const, value })),
+export const geminiOmniVideoPorts: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "gemini-omni-video",
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },
+ { name: "duration", value: { kind: "enum", values: [4, 6, 8, 10] }, minItems: 1, maxItems: 1 },
+ { name: "aspectRatio", value: { kind: "enum", values: ["16:9", "9:16"] }, minItems: 1, maxItems: 1 },
+ { name: "resolution", value: { kind: "enum", values: ["720p", "1080p", "4k"] }, minItems: 1, maxItems: 1 },
+ {
+ name: "seed",
+ value: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 },
+ minItems: 0,
+ maxItems: 1,
},
- },
- aspectRatio: { schema: { kind: "string", enum: ["16:9", "9:16"] } },
- resolution: { schema: { kind: "string", enum: ["720p", "1080p", "4k"] } },
- seed: { schema: { kind: "number", integer: true, minimum: 0, maximum: 2_147_483_647 }, optional: true },
- images: {
- schema: { kind: "array", minItems: 1, maxItems: 7, items: generationBlobRefSchema },
- optional: true,
- },
- audioIds: { schema: { kind: "array", minItems: 1, maxItems: 1, items: idSchema }, optional: true },
- videos: {
- schema: {
- kind: "array",
- minItems: 1,
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 7 },
+ {
+ name: "excerpts",
+ value: {
+ kind: "media",
+ accepts: ["video"],
+ itemFields: [
+ { name: "startSec", value: { kind: "number", minimum: 0 } },
+ { name: "endSec", value: { kind: "number", minimum: 0 } },
+ ],
+ itemRequires: [{ kind: "strictlyIncreasing", fields: ["startSec", "endSec"] }],
+ },
+ minItems: 0,
maxItems: 1,
- items: generationObjectSchema({
- artifact: { schema: generationBlobRefSchema },
- startSec: { schema: { kind: "number", minimum: 0 } },
- endSec: { schema: { kind: "number", minimum: 0 } },
- }),
},
- optional: true,
- },
- characterIds: { schema: { kind: "array", minItems: 1, maxItems: 3, items: idSchema }, optional: true },
+ { name: "audioIds", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 3 },
+ { name: "characterIds", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 3 },
+ ],
+ /** One shared reference budget; a video excerpt costs twice an image. */
+ requires: [{
+ kind: "weightedTotal",
+ weights: { images: 1, excerpts: 2, characterIds: 1 },
+ maximum: 7,
+ }],
});
-function object(value: unknown, subject: string): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${subject} must be an object`);
- return value as Record<string, unknown>;
-}
-
-export function verifyGeminiOmniRequest(value: unknown): asserts value is GeminiOmniRequest {
- const request = object(value, "Gemini Omni request");
- if (request.contract !== "svml.gemini-omni-request@1" || request.model !== "gemini-omni-video") {
- throw new Error("Gemini Omni request identity is invalid");
- }
- if (![4, 6, 8, 10].includes(request.durationSec as number)
- || (request.aspectRatio !== "16:9" && request.aspectRatio !== "9:16")
- || (request.resolution !== "720p" && request.resolution !== "1080p" && request.resolution !== "4k")) {
- throw new Error("Gemini Omni output parameters are invalid");
- }
- if (request.seed !== undefined
- && (typeof request.seed !== "number" || !Number.isSafeInteger(request.seed)
- || request.seed < 0 || request.seed > 2_147_483_647)) {
- throw new Error("Gemini Omni seed is invalid");
- }
- const images = request.images === undefined ? [] : request.images;
- const videos = request.videos === undefined ? [] : request.videos;
- const characters = request.characterIds === undefined ? [] : request.characterIds;
- const audios = request.audioIds === undefined ? [] : request.audioIds;
- if (!Array.isArray(images) || !Array.isArray(videos) || !Array.isArray(characters) || !Array.isArray(audios)) {
- throw new Error("Gemini Omni references are invalid");
- }
- if (audios.length > 1 || audios.some((id) => typeof id !== "string" || id.length === 0)) {
- throw new Error("Gemini Omni accepts at most one opaque audio ID");
- }
- images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- videos.forEach((candidate) => {
- const video = object(candidate, "Gemini Omni video reference");
- assertGenerationBlobRef(video.artifact, "video/");
- if (typeof video.startSec !== "number" || typeof video.endSec !== "number" || video.endSec <= video.startSec) {
- throw new Error("Gemini Omni video range must have endSec > startSec");
- }
- });
- const quota = images.length + videos.length * 2 + characters.length;
- if (quota > 7) throw new Error(`Gemini Omni reference quota is ${quota}, over 7`);
-}
-
-export function sealGeminiOmniRequest(content: GeminiOmniRequestContent): GeminiOmniRequest {
- const request = sealGenerationRequest(content);
- verifyGeminiOmniRequest(request);
- return request;
+export function sealGeminiOmniRequest(
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(geminiOmniVideoPorts, ports);
}
export const geminiOmniDefinition = defineExactModelModule({
@@ -120,11 +56,8 @@ export const geminiOmniDefinition = defineExactModelModule({
endpoints: [{
key: "video",
requestTypeName: "GeminiOmniVideoRequest",
- capabilityName: "gemini-omni-video-generation",
producerName: "request-gemini-omni-video",
- result: "video",
- requestSchema: geminiOmniRequestSchema,
- verifyRequest: verifyGeminiOmniRequest,
+ ports: geminiOmniVideoPorts,
}],
});
diff --git a/packages/generation/src/index.ts b/packages/generation/src/index.ts
index e9af9c40..f6448a22 100644
--- a/packages/generation/src/index.ts
+++ b/packages/generation/src/index.ts
@@ -16,6 +16,55 @@ export {
generationTypes,
generationValidatorDigests,
} from "./manifest.js";
+export {
+ assertMappingCoversPorts,
+ compileWireRequest,
+ GENERATION_WIRE_MAPPING_V1,
+ mappingSupportsRequest,
+ selectWireModel,
+} from "./mapping.js";
+export type {
+ GenerationArtifactUrlResolver,
+ GenerationFieldMapping,
+ GenerationWireMapping,
+ GenerationWireRequest,
+ GenerationWireRoute,
+} from "./mapping.js";
+export {
+ assertGenerationPortTable,
+ GENERATION_MEDIA_ROLES,
+ GENERATION_PORTS_V1,
+ generationPort,
+ isMediaPort,
+ sealGenerationPortTable,
+} from "./ports.js";
+export type {
+ GenerationItemRequirement,
+ GenerationMediaPort,
+ GenerationMediaPortKind,
+ GenerationMediaRole,
+ GenerationMediaValue,
+ GenerationPort,
+ GenerationPortItemField,
+ GenerationPortKind,
+ GenerationPortRequirement,
+ GenerationPortScalarKind,
+ GenerationPortTable,
+ GenerationPortValue,
+ GenerationScalarPort,
+} from "./ports.js";
+export {
+ GENERATION_REQUEST_V1,
+ mediaValues,
+ portsObjectSchema,
+ portValues,
+ presentPorts,
+ requestSchemaFromPorts,
+ sealGenerationPortRequest,
+ verifyPortsAgainstTable,
+ verifyRequestAgainstPorts,
+} from "./request.js";
+export type { GenerationPortSubset, GenerationRequest } from "./request.js";
export {
generatedImageSetSchema,
generatedVideoSetSchema,
diff --git a/packages/generation/src/mapping.ts b/packages/generation/src/mapping.ts
new file mode 100644
index 00000000..7f5160d5
--- /dev/null
+++ b/packages/generation/src/mapping.ts
@@ -0,0 +1,213 @@
+import { canonicalize } from "@narratage/protocol";
+import type { BlobRef, CanonicalValue, CapabilityRef } from "@narratage/protocol";
+
+import { isMediaPort } from "./ports.js";
+import type { GenerationMediaRole, GenerationMediaValue, GenerationPortTable } from "./ports.js";
+import { presentPorts } from "./request.js";
+import type { GenerationRequest } from "./request.js";
+
+/**
+ * How one service names the fields of one model's declared input ports.
+ *
+ * A mapping is data, not code, and it references its Capability by name. A
+ * Provider package therefore never imports a model package: the model owns what
+ * it eats, the service owns what it calls that on the wire.
+ */
+export const GENERATION_WIRE_MAPPING_V1 = "svml.generation-wire-mapping@1" as const;
+
+export type GenerationArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;
+
+export type GenerationFieldMapping =
+ /** One scalar written as-is. */
+ | { readonly as: "value"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+ /** One scalar coerced to its string form, for services that type it loosely. */
+ | { readonly as: "string"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+ /** Several scalars written as one array. */
+ | { readonly as: "valueArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+ /** One media item written as a resolved URL. */
+ | { readonly as: "url"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+ /** Several media items written as one array of resolved URLs. */
+ | { readonly as: "urlArray"; readonly field: string; readonly whenAbsent?: CanonicalValue }
+ /** Media items written as objects carrying the resolved URL and their item fields. */
+ | {
+ readonly as: "itemObject";
+ readonly field: string;
+ readonly urlKey: string;
+ readonly fieldKeys: Readonly<Record<string, string>>;
+ readonly whenAbsent?: CanonicalValue;
+ };
+
+/** Selects the service-side model identifier. The first matching route wins. */
+export type GenerationWireRoute = {
+ readonly model: string;
+ readonly whenPresent?: readonly string[];
+};
+
+export type GenerationWireMapping = {
+ readonly contract: "svml.generation-wire-mapping@1";
+ /**
+ * The exact Capability implemented, named as data. Binding the module version
+ * here keeps a port change visible: a mapping written for one model version
+ * cannot silently serve another.
+ */
+ readonly capability: CapabilityRef;
+ readonly result: "image" | "video";
+ readonly routes: readonly GenerationWireRoute[];
+ readonly fields: Readonly<Record<string, GenerationFieldMapping>>;
+ readonly constants?: Readonly<Record<string, CanonicalValue>>;
+};
+
+export type GenerationWireRequest = {
+ readonly model: string;
+ readonly input: CanonicalValue;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+export function selectWireModel(mapping: GenerationWireMapping, present: ReadonlySet<string>): string {
+ for (const route of mapping.routes) {
+ if (route.whenPresent === undefined || route.whenPresent.every((name) => present.has(name))) {
+ return route.model;
+ }
+ }
+ throw new Error(`${mapping.capability.name} has no route for ports ${[...present].sort().join(", ")}`);
+}
+
+async function urlsOf(
+ values: readonly GenerationMediaValue[],
+ resolve: GenerationArtifactUrlResolver,
+): Promise<string[]> {
+ return await Promise.all(values.map((item) => resolve(item.artifact)));
+}
+
+/**
+ * Compile one port-shaped request into one service payload. The engine needs
+ * only the mapping and the request, never the model package.
+ */
+export async function compileWireRequest(
+ mapping: GenerationWireMapping,
+ request: GenerationRequest,
+ resolve: GenerationArtifactUrlResolver,
+): Promise<GenerationWireRequest> {
+ assert(mapping.contract === GENERATION_WIRE_MAPPING_V1, "Generation wire mapping contract is invalid");
+ assert(request.model === mapping.capability.name,
+ `${mapping.capability.name} mapping received a ${request.model} request`);
+ const present = presentPorts(request);
+ const input: Record<string, CanonicalValue> = { ...(mapping.constants ?? {}) };
+
+ for (const [port, field] of Object.entries(mapping.fields)) {
+ const supplied = request.ports[port];
+ if (supplied === undefined) {
+ if (field.whenAbsent !== undefined) input[field.field] = field.whenAbsent;
+ continue;
+ }
+ if (field.as === "value") {
+ input[field.field] = supplied[0] as CanonicalValue;
+ } else if (field.as === "string") {
+ input[field.field] = String(supplied[0]);
+ } else if (field.as === "valueArray") {
+ input[field.field] = supplied as readonly CanonicalValue[];
+ } else if (field.as === "url") {
+ input[field.field] = await resolve((supplied[0] as GenerationMediaValue).artifact);
+ } else if (field.as === "urlArray") {
+ input[field.field] = await urlsOf(supplied as readonly GenerationMediaValue[], resolve);
+ } else {
+ const media = supplied as readonly GenerationMediaValue[];
+ input[field.field] = await Promise.all(media.map(async (item) => ({
+ [field.urlKey]: await resolve(item.artifact),
+ ...Object.fromEntries(Object.entries(field.fieldKeys)
+ .filter(([source]) => item.fields?.[source] !== undefined)
+ .map(([source, target]) => [target, item.fields![source] as CanonicalValue])),
+ })));
+ }
+ }
+
+ return { model: selectWireModel(mapping, present), input: canonicalize(input) };
+}
+
+/** Does this request only use ports this mapping can write? Needs no model package. */
+export function mappingSupportsRequest(mapping: GenerationWireMapping, value: unknown): boolean {
+ const request = value as GenerationRequest | undefined;
+ if (request?.contract !== "svml.generation-request@1") return false;
+ if (request.model !== mapping.capability.name) return false;
+ if (request.ports === null || typeof request.ports !== "object") return false;
+ return Object.keys(request.ports).every((port) => mapping.fields[port] !== undefined);
+}
+
+/**
+ * Prove one service mapping covers every port the model declares.
+ *
+ * This is the check the old hand-written per-model translators could not have:
+ * a forgotten reference role or item field used to surface only after a paid
+ * generation returned the wrong result.
+ */
+export function assertMappingCoversPorts(
+ table: GenerationPortTable,
+ mapping: GenerationWireMapping,
+): void {
+ assert(mapping.contract === GENERATION_WIRE_MAPPING_V1,
+ `${table.model} mapping contract is invalid`);
+ assert(mapping.capability.name === table.model,
+ `mapping names Capability ${mapping.capability.name} but the port table declares ${table.model}`);
+ assert(mapping.result === table.result,
+ `${table.model} mapping result ${mapping.result} differs from the port table`);
+
+ const declared = new Map(table.ports.map((port) => [port.name, port]));
+ Object.keys(mapping.fields).forEach((name) => assert(declared.has(name),
+ `${table.model} mapping names undeclared port ${name}`));
+
+ for (const port of table.ports) {
+ const field = mapping.fields[port.name];
+ assert(field !== undefined, `${table.model} mapping does not cover port ${port.name}`);
+ const subject = `${table.model} mapping for port ${port.name}`;
+ if (isMediaPort(port)) {
+ const media = port.value;
+ const itemFields = media.itemFields ?? [];
+ if (itemFields.length > 0) {
+ assert(field.as === "itemObject", `${subject} must use itemObject because the port carries item fields`);
+ for (const item of itemFields) {
+ if (item.optional === true) continue;
+ assert(field.fieldKeys[item.name] !== undefined,
+ `${subject} does not map required item field ${item.name}`);
+ }
+ Object.keys(field.fieldKeys).forEach((name) => assert(
+ itemFields.some((item) => item.name === name),
+ `${subject} maps unknown item field ${name}`,
+ ));
+ continue;
+ }
+ assert(media.accepts.length === 1,
+ `${subject} accepts ${media.accepts.join(", ")}; declare one port per media role so each maps to one wire field`);
+ assert(field.as === "url" || field.as === "urlArray", `${subject} must resolve media to a URL`);
+ if (field.as === "url") {
+ assert(port.maxItems === 1, `${subject} uses url but the port accepts up to ${port.maxItems} items`);
+ }
+ continue;
+ }
+ if (port.maxItems > 1) {
+ assert(field.as === "valueArray", `${subject} must use valueArray because the port accepts several values`);
+ continue;
+ }
+ // A single-value port may still be written as a wire array when the service types it that way.
+ assert(field.as === "value" || field.as === "string" || field.as === "valueArray",
+ `${subject} must write a scalar or a single-element array`);
+ }
+
+ const emitted = Object.values(mapping.fields).map((field) => field.field);
+ assert(new Set(emitted).size === emitted.length,
+ `${table.model} mapping writes one wire field from two ports`);
+ Object.keys(mapping.constants ?? {}).forEach((name) => assert(!emitted.includes(name),
+ `${table.model} mapping constant ${name} collides with a mapped port`));
+
+ assert(mapping.routes.length > 0, `${table.model} mapping declares no route`);
+ mapping.routes.forEach((route, index) => {
+ assert(route.model.trim().length > 0, `${table.model} route ${index} has an empty service model`);
+ (route.whenPresent ?? []).forEach((name) => assert(declared.has(name),
+ `${table.model} route ${index} names undeclared port ${name}`));
+ const unconditional = route.whenPresent === undefined || route.whenPresent.length === 0;
+ assert(unconditional === (index === mapping.routes.length - 1),
+ `${table.model} must end with exactly one unconditional route`);
+ });
+}
diff --git a/packages/generation/src/ports.ts b/packages/generation/src/ports.ts
new file mode 100644
index 00000000..e5961ab6
--- /dev/null
+++ b/packages/generation/src/ports.ts
@@ -0,0 +1,223 @@
+import type { BlobRef } from "@narratage/protocol";
+
+/**
+ * The closed vocabulary describing what one exact generation model accepts.
+ *
+ * A model's input ports are decided when the model is trained: which reference
+ * images, audio, video or text it can consume is a property of the model, not
+ * of the service reselling it. A Provider therefore never redeclares this
+ * shape; it only maps each declared port onto its own wire fields.
+ *
+ * Adding a port kind is a `svml.generation-ports@2` decision, not a field patch.
+ */
+export const GENERATION_PORTS_V1 = "svml.generation-ports@1" as const;
+
+export type GenerationMediaRole = "image" | "video" | "audio";
+
+export const GENERATION_MEDIA_ROLES: readonly GenerationMediaRole[] = ["image", "video", "audio"];
+
+export type GenerationPortScalarKind =
+ | { readonly kind: "text"; readonly maxChars: number }
+ | { readonly kind: "token"; readonly minLength: number; readonly maxLength: number }
+ | { readonly kind: "enum"; readonly values: readonly (string | number)[] }
+ | {
+ readonly kind: "number";
+ readonly integer?: boolean;
+ readonly minimum?: number;
+ readonly maximum?: number;
+ }
+ | { readonly kind: "boolean" };
+
+/** A scalar carried alongside one media item, such as a trimmed excerpt boundary. */
+export type GenerationPortItemField = {
+ readonly name: string;
+ readonly value: GenerationPortScalarKind;
+ readonly optional?: boolean;
+};
+
+/** Relation between two item fields of the same media item, such as a trim window. */
+export type GenerationItemRequirement = {
+ readonly kind: "strictlyIncreasing";
+ readonly fields: readonly string[];
+};
+
+export type GenerationMediaPortKind = {
+ readonly kind: "media";
+ readonly accepts: readonly GenerationMediaRole[];
+ readonly itemFields?: readonly GenerationPortItemField[];
+ readonly itemRequires?: readonly GenerationItemRequirement[];
+};
+
+export type GenerationPortKind = GenerationPortScalarKind | GenerationMediaPortKind;
+
+type GenerationPortBase = {
+ readonly name: string;
+ readonly minItems: number;
+ readonly maxItems: number;
+};
+
+export type GenerationScalarPort = GenerationPortBase & { readonly value: GenerationPortScalarKind };
+export type GenerationMediaPort = GenerationPortBase & { readonly value: GenerationMediaPortKind };
+
+/**
+ * One named input port. `minItems: 0` means the model works without it;
+ * `maxItems: 1` means the port carries a single value rather than a list.
+ */
+export type GenerationPort = GenerationScalarPort | GenerationMediaPort;
+
+export type GenerationPortRequirement =
+ | { readonly kind: "atMostOneOf"; readonly ports: readonly string[] }
+ | { readonly kind: "requiresPresent"; readonly port: string; readonly needs: readonly string[] }
+ /** This port needs company, but any one of several will do — reference audio needs a visual. */
+ | { readonly kind: "requiresAnyOf"; readonly port: string; readonly anyOf: readonly string[] }
+ /** A shared budget several ports draw from, such as a total reference quota. */
+ | {
+ readonly kind: "weightedTotal";
+ readonly weights: Readonly<Record<string, number>>;
+ readonly maximum: number;
+ };
+
+export type GenerationPortTable = {
+ readonly contract: "svml.generation-ports@1";
+ /** Exact model identity; this is also the Capability name. */
+ readonly model: string;
+ readonly result: "image" | "video";
+ readonly ports: readonly GenerationPort[];
+ readonly requires: readonly GenerationPortRequirement[];
+};
+
+export type GenerationMediaValue = {
+ readonly role: GenerationMediaRole;
+ readonly artifact: BlobRef;
+ readonly fields?: Readonly<Record<string, string | number | boolean>>;
+};
+
+export type GenerationPortValue = string | number | boolean | GenerationMediaValue;
+
+const PORT_NAME = /^[a-z][A-Za-z0-9]*$/u;
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+export function isMediaPort(port: GenerationPort): port is GenerationMediaPort {
+ return port.value.kind === "media";
+}
+
+function assertScalarKind(value: GenerationPortScalarKind, subject: string): void {
+ if (value.kind === "text") {
+ assert(Number.isSafeInteger(value.maxChars) && value.maxChars > 0, `${subject} maxChars is invalid`);
+ return;
+ }
+ if (value.kind === "token") {
+ assert(Number.isSafeInteger(value.minLength) && value.minLength >= 1, `${subject} minLength is invalid`);
+ assert(Number.isSafeInteger(value.maxLength) && value.maxLength >= value.minLength, `${subject} maxLength is invalid`);
+ return;
+ }
+ if (value.kind === "enum") {
+ assert(value.values.length > 0, `${subject} enum is empty`);
+ assert(new Set(value.values).size === value.values.length, `${subject} enum repeats a value`);
+ value.values.forEach((item) => assert(
+ typeof item === "string" ? item.length > 0 : Number.isFinite(item),
+ `${subject} enum contains an invalid value`,
+ ));
+ return;
+ }
+ if (value.kind === "number") {
+ if (value.minimum !== undefined) assert(Number.isFinite(value.minimum), `${subject} minimum is invalid`);
+ if (value.maximum !== undefined) assert(Number.isFinite(value.maximum), `${subject} maximum is invalid`);
+ if (value.minimum !== undefined && value.maximum !== undefined) {
+ assert(value.maximum >= value.minimum, `${subject} numeric bounds are inverted`);
+ }
+ return;
+ }
+ assert(value.kind === "boolean", `${subject} port kind is outside ${GENERATION_PORTS_V1}`);
+}
+
+export function assertGenerationPortTable(value: GenerationPortTable): void {
+ assert(value.contract === GENERATION_PORTS_V1, "Generation port table contract is invalid");
+ assert(typeof value.model === "string" && value.model.trim().length > 0, "Generation port table model is empty");
+ assert(value.result === "image" || value.result === "video", `${value.model} port table result is invalid`);
+ assert(value.ports.length > 0, `${value.model} declares no input port`);
+
+ const names = new Set<string>();
+ for (const port of value.ports) {
+ const subject = `${value.model} port ${port.name}`;
+ assert(PORT_NAME.test(port.name), `${subject} name is invalid`);
+ assert(!names.has(port.name), `${subject} is declared twice`);
+ names.add(port.name);
+ assert(Number.isSafeInteger(port.minItems) && port.minItems >= 0, `${subject} minItems is invalid`);
+ assert(Number.isSafeInteger(port.maxItems) && port.maxItems >= Math.max(1, port.minItems),
+ `${subject} maxItems is invalid`);
+ if (isMediaPort(port)) {
+ const media = port.value;
+ assert(media.accepts.length > 0, `${subject} accepts no media role`);
+ assert(new Set(media.accepts).size === media.accepts.length, `${subject} repeats a media role`);
+ media.accepts.forEach((role) => assert(GENERATION_MEDIA_ROLES.includes(role), `${subject} media role ${role} is invalid`));
+ const fields = new Set<string>();
+ for (const field of media.itemFields ?? []) {
+ assert(PORT_NAME.test(field.name), `${subject} item field name is invalid`);
+ assert(!fields.has(field.name), `${subject} item field ${field.name} is declared twice`);
+ fields.add(field.name);
+ assertScalarKind(field.value, `${subject} item field ${field.name}`);
+ }
+ for (const rule of media.itemRequires ?? []) {
+ assert(rule.kind === "strictlyIncreasing", `${subject} declares an unsupported item requirement`);
+ assert(rule.fields.length >= 2, `${subject} strictlyIncreasing needs at least two item fields`);
+ rule.fields.forEach((name) => assert(fields.has(name),
+ `${subject} strictlyIncreasing names unknown item field ${name}`));
+ }
+ } else {
+ assertScalarKind(port.value, subject);
+ }
+ }
+
+ for (const requirement of value.requires) {
+ if (requirement.kind === "atMostOneOf") {
+ assert(requirement.ports.length >= 2, `${value.model} atMostOneOf needs at least two ports`);
+ requirement.ports.forEach((name) => assert(names.has(name),
+ `${value.model} atMostOneOf names unknown port ${name}`));
+ assert(new Set(requirement.ports).size === requirement.ports.length,
+ `${value.model} atMostOneOf repeats a port`);
+ continue;
+ }
+ if (requirement.kind === "requiresAnyOf") {
+ assert(names.has(requirement.port), `${value.model} requiresAnyOf names unknown port ${requirement.port}`);
+ assert(requirement.anyOf.length >= 1, `${value.model} requiresAnyOf lists no companion port`);
+ requirement.anyOf.forEach((name) => {
+ assert(names.has(name), `${value.model} requiresAnyOf names unknown port ${name}`);
+ assert(name !== requirement.port, `${value.model} requiresAnyOf ${name} depends on itself`);
+ });
+ continue;
+ }
+ if (requirement.kind === "weightedTotal") {
+ const entries = Object.entries(requirement.weights);
+ assert(entries.length >= 1, `${value.model} weightedTotal lists no port`);
+ entries.forEach(([name, weight]) => {
+ assert(names.has(name), `${value.model} weightedTotal names unknown port ${name}`);
+ assert(Number.isFinite(weight) && weight > 0, `${value.model} weightedTotal weight for ${name} is invalid`);
+ });
+ assert(Number.isFinite(requirement.maximum) && requirement.maximum > 0,
+ `${value.model} weightedTotal maximum is invalid`);
+ continue;
+ }
+ assert(requirement.kind === "requiresPresent", `${value.model} declares an unsupported requirement`);
+ assert(names.has(requirement.port), `${value.model} requiresPresent names unknown port ${requirement.port}`);
+ assert(requirement.needs.length > 0, `${value.model} requiresPresent lists no prerequisite`);
+ requirement.needs.forEach((name) => {
+ assert(names.has(name), `${value.model} requiresPresent names unknown port ${name}`);
+ assert(name !== requirement.port, `${value.model} requiresPresent ${name} depends on itself`);
+ });
+ }
+}
+
+export function sealGenerationPortTable(value: GenerationPortTable): GenerationPortTable {
+ assertGenerationPortTable(value);
+ return value;
+}
+
+export function generationPort(table: GenerationPortTable, name: string): GenerationPort {
+ const port = table.ports.find((item) => item.name === name);
+ if (port === undefined) throw new Error(`${table.model} declares no port ${name}`);
+ return port;
+}
diff --git a/packages/generation/src/request.ts b/packages/generation/src/request.ts
new file mode 100644
index 00000000..26fc9a7c
--- /dev/null
+++ b/packages/generation/src/request.ts
@@ -0,0 +1,290 @@
+import type { ObjectFieldSchema, ValueSchema } from "@narratage/protocol";
+
+import { assertGenerationBlobRef, sealGenerationRequest } from "./identity.js";
+import { generationBlobRefSchema, generationObjectSchema } from "./schema.js";
+import { assertGenerationPortTable, isMediaPort } from "./ports.js";
+import type {
+ GenerationMediaPort,
+ GenerationMediaRole,
+ GenerationMediaValue,
+ GenerationPort,
+ GenerationPortItemField,
+ GenerationPortScalarKind,
+ GenerationPortTable,
+ GenerationPortValue,
+} from "./ports.js";
+
+/**
+ * The one request envelope every exact model uses. A Provider reads ports by
+ * name and never learns a model-specific field layout, so the same wire mapping
+ * mechanism serves every model and every service reselling it.
+ */
+export const GENERATION_REQUEST_V1 = "svml.generation-request@1" as const;
+
+export type GenerationRequest = {
+ readonly contract: "svml.generation-request@1";
+ readonly model: string;
+ /** An absent port is an omitted key. A present port always carries at least one value. */
+ readonly ports: Readonly<Record<string, readonly GenerationPortValue[]>>;
+};
+
+function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+
+function plainObject(value: unknown, subject: string): Record<string, unknown> {
+ assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+ return value as Record<string, unknown>;
+}
+
+function mediaPrefix(role: GenerationMediaRole): "image/" | "video/" | "audio/" {
+ return `${role}/` as "image/" | "video/" | "audio/";
+}
+
+function scalarSchema(value: GenerationPortScalarKind): ValueSchema {
+ if (value.kind === "text") return { kind: "string", minLength: 1, maxLength: value.maxChars };
+ if (value.kind === "token") return { kind: "string", minLength: value.minLength, maxLength: value.maxLength };
+ if (value.kind === "boolean") return { kind: "boolean" };
+ if (value.kind === "number") {
+ return {
+ kind: "number",
+ ...(value.integer === undefined ? {} : { integer: value.integer }),
+ ...(value.minimum === undefined ? {} : { minimum: value.minimum }),
+ ...(value.maximum === undefined ? {} : { maximum: value.maximum }),
+ };
+ }
+ const strings = value.values.every((item): item is string => typeof item === "string");
+ if (strings) return { kind: "string", enum: [...value.values] };
+ return { kind: "oneOf", variants: value.values.map((item) => ({ kind: "literal" as const, value: item })) };
+}
+
+function itemFieldsSchema(fields: readonly GenerationPortItemField[]): ValueSchema {
+ return generationObjectSchema(Object.fromEntries(fields.map((field) => [field.name, {
+ schema: scalarSchema(field.value),
+ ...(field.optional === true ? { optional: true } : {}),
+ } satisfies ObjectFieldSchema])));
+}
+
+function portItemSchema(port: GenerationPort): ValueSchema {
+ if (!isMediaPort(port)) return scalarSchema(port.value);
+ const media = port.value;
+ return generationObjectSchema({
+ role: { schema: { kind: "string", enum: [...media.accepts] } },
+ artifact: { schema: generationBlobRefSchema },
+ ...(media.itemFields === undefined || media.itemFields.length === 0
+ ? {}
+ : { fields: { schema: itemFieldsSchema(media.itemFields) } }),
+ });
+}
+
+export type GenerationPortSubset = {
+ /**
+ * Ports supplied later rather than by this value. A duration-dependent
+ * compilation authors everything else first and completes the request when
+ * the missing fact exists.
+ */
+ readonly omit?: readonly string[];
+};
+
+/** Derive the Schema of the port map alone, optionally leaving some ports for later. */
+export function portsObjectSchema(
+ table: GenerationPortTable,
+ options: GenerationPortSubset = {},
+): ValueSchema {
+ assertGenerationPortTable(table);
+ const omit = new Set(options.omit ?? []);
+ omit.forEach((name) => assert(table.ports.some((port) => port.name === name),
+ `${table.model} cannot omit undeclared port ${name}`));
+ return generationObjectSchema(Object.fromEntries(table.ports
+ .filter((port) => !omit.has(port.name))
+ .map((port) => [port.name, {
+ schema: {
+ kind: "array",
+ items: portItemSchema(port),
+ minItems: Math.max(1, port.minItems),
+ maxItems: port.maxItems,
+ },
+ ...(port.minItems === 0 ? { optional: true } : {}),
+ } satisfies ObjectFieldSchema])));
+}
+
+/** Derive the structural Schema of one model's request from its port table. */
+export function requestSchemaFromPorts(table: GenerationPortTable): ValueSchema {
+ return generationObjectSchema({
+ contract: { schema: { kind: "literal", value: GENERATION_REQUEST_V1 } },
+ model: { schema: { kind: "literal", value: table.model } },
+ ports: { schema: portsObjectSchema(table) },
+ });
+}
+
+function verifyScalar(value: unknown, kind: GenerationPortScalarKind, subject: string): void {
+ if (kind.kind === "text") {
+ assert(typeof value === "string" && value.length > 0 && value.length <= kind.maxChars,
+ `${subject} must be text of 1 to ${kind.maxChars} characters`);
+ return;
+ }
+ if (kind.kind === "token") {
+ assert(typeof value === "string" && value.length >= kind.minLength && value.length <= kind.maxLength,
+ `${subject} must be a token of ${kind.minLength} to ${kind.maxLength} characters`);
+ return;
+ }
+ if (kind.kind === "boolean") {
+ assert(typeof value === "boolean", `${subject} must be a boolean`);
+ return;
+ }
+ if (kind.kind === "number") {
+ assert(typeof value === "number" && Number.isFinite(value), `${subject} must be a finite number`);
+ if (kind.integer === true) assert(Number.isSafeInteger(value), `${subject} must be an integer`);
+ if (kind.minimum !== undefined) assert(value >= kind.minimum, `${subject} must be at least ${kind.minimum}`);
+ if (kind.maximum !== undefined) assert(value <= kind.maximum, `${subject} must be at most ${kind.maximum}`);
+ return;
+ }
+ assert(
+ (typeof value === "string" || typeof value === "number") && kind.values.includes(value),
+ `${subject} must be one of ${kind.values.join(", ")}`,
+ );
+}
+
+function verifyMediaValue(value: unknown, port: GenerationMediaPort, subject: string): void {
+ const media = port.value;
+ const item = plainObject(value, subject);
+ const role = item.role;
+ assert(typeof role === "string" && media.accepts.includes(role as GenerationMediaRole),
+ `${subject} role must be one of ${media.accepts.join(", ")}`);
+ assertGenerationBlobRef(item.artifact, mediaPrefix(role as GenerationMediaRole));
+ const declared = media.itemFields ?? [];
+ if (declared.length === 0) {
+ assert(item.fields === undefined, `${subject} declares no item fields`);
+ return;
+ }
+ const fields = plainObject(item.fields ?? {}, `${subject} fields`);
+ const known = new Set(declared.map((field) => field.name));
+ Object.keys(fields).forEach((name) => assert(known.has(name), `${subject} has unknown item field ${name}`));
+ for (const field of declared) {
+ const present = Object.prototype.hasOwnProperty.call(fields, field.name);
+ if (!present) {
+ assert(field.optional === true, `${subject} is missing item field ${field.name}`);
+ continue;
+ }
+ verifyScalar(fields[field.name], field.value, `${subject} item field ${field.name}`);
+ }
+ for (const rule of media.itemRequires ?? []) {
+ const values = rule.fields.map((name) => fields[name]).filter((item) => item !== undefined);
+ if (values.length < rule.fields.length) continue;
+ for (let index = 1; index < values.length; index += 1) {
+ assert((values[index] as number) > (values[index - 1] as number),
+ `${subject} requires ${rule.fields.join(" < ")}`);
+ }
+ }
+}
+
+/**
+ * Full standalone verification against the port table. Core's generic schema
+ * admission runs first; this adds the facts a Schema cannot state, such as the
+ * media type each role demands and the model's port combination rules.
+ */
+export function verifyPortsAgainstTable(
+ table: GenerationPortTable,
+ value: unknown,
+ options: GenerationPortSubset = {},
+): void {
+ assertGenerationPortTable(table);
+ const omit = new Set(options.omit ?? []);
+ const ports = plainObject(value, `${table.model} ports`);
+ const declared = new Map(table.ports.map((port) => [port.name, port]));
+ Object.keys(ports).forEach((name) => {
+ assert(declared.has(name), `${table.model} names undeclared port ${name}`);
+ assert(!omit.has(name), `${table.model} port ${name} is supplied later and must be absent here`);
+ });
+
+ const present = new Set<string>();
+ for (const port of table.ports) {
+ if (omit.has(port.name)) continue;
+ const subject = `${table.model} port ${port.name}`;
+ const supplied = ports[port.name];
+ if (supplied === undefined) {
+ assert(port.minItems === 0, `${subject} is required`);
+ continue;
+ }
+ assert(Array.isArray(supplied), `${subject} must be an array`);
+ assert(supplied.length >= Math.max(1, port.minItems),
+ `${subject} needs at least ${Math.max(1, port.minItems)} value(s)`);
+ assert(supplied.length <= port.maxItems, `${subject} accepts at most ${port.maxItems} value(s)`);
+ present.add(port.name);
+ supplied.forEach((item, index) => {
+ const label = port.maxItems === 1 ? subject : `${subject}[${index}]`;
+ if (isMediaPort(port)) verifyMediaValue(item, port, label);
+ else verifyScalar(item, port.value, label);
+ });
+ }
+
+ for (const requirement of table.requires) {
+ if (requirement.kind === "atMostOneOf") {
+ const used = requirement.ports.filter((name) => present.has(name));
+ assert(used.length <= 1,
+ `${table.model} accepts at most one of ${requirement.ports.join(", ")} but received ${used.join(", ")}`);
+ continue;
+ }
+ if (requirement.kind === "requiresAnyOf") {
+ if (!present.has(requirement.port)) continue;
+ const satisfied = requirement.anyOf.some((name) => present.has(name) || omit.has(name));
+ assert(satisfied,
+ `${table.model} port ${requirement.port} needs at least one of ${requirement.anyOf.join(", ")}`);
+ continue;
+ }
+ if (requirement.kind === "weightedTotal") {
+ const total = Object.entries(requirement.weights).reduce((sum, [name, weight]) => {
+ const supplied = ports[name];
+ return sum + (Array.isArray(supplied) ? supplied.length : 0) * weight;
+ }, 0);
+ assert(total <= requirement.maximum,
+ `${table.model} uses ${total} of its ${requirement.maximum} shared ${Object.keys(requirement.weights).sort().join("/")} budget`);
+ continue;
+ }
+ if (!present.has(requirement.port)) continue;
+ const missing = requirement.needs.filter((name) => !present.has(name) && !omit.has(name));
+ assert(missing.length === 0,
+ `${table.model} port ${requirement.port} also requires ${missing.join(", ")}`);
+ }
+}
+
+export function verifyRequestAgainstPorts(
+ table: GenerationPortTable,
+ value: unknown,
+): asserts value is GenerationRequest {
+ assertGenerationPortTable(table);
+ const request = plainObject(value, `${table.model} request`);
+ assert(request.contract === GENERATION_REQUEST_V1, `${table.model} request contract is invalid`);
+ assert(request.model === table.model, `${table.model} request model is invalid`);
+ verifyPortsAgainstTable(table, request.ports);
+}
+
+/** Build one canonical request for a model from its declared ports. */
+export function sealGenerationPortRequest(
+ table: GenerationPortTable,
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ const content: GenerationRequest = {
+ contract: GENERATION_REQUEST_V1,
+ model: table.model,
+ ports: Object.fromEntries(
+ Object.entries(ports).filter(([, values]) => values !== undefined && values.length > 0),
+ ),
+ };
+ const request = sealGenerationRequest(content);
+ verifyRequestAgainstPorts(table, request);
+ return request;
+}
+
+/** Which ports this request actually populates; drives Provider routing and coverage. */
+export function presentPorts(request: GenerationRequest): ReadonlySet<string> {
+ return new Set(Object.keys(request.ports));
+}
+
+export function portValues(request: GenerationRequest, name: string): readonly GenerationPortValue[] {
+ return request.ports[name] ?? [];
+}
+
+export function mediaValues(request: GenerationRequest, name: string): readonly GenerationMediaValue[] {
+ return portValues(request, name) as readonly GenerationMediaValue[];
+}
diff --git a/packages/generation/test/ports.test.ts b/packages/generation/test/ports.test.ts
new file mode 100644
index 00000000..91833a32
--- /dev/null
+++ b/packages/generation/test/ports.test.ts
@@ -0,0 +1,204 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MemoryArtifactStore } from "@narratage/driver-node";
+import {
+ assertMappingCoversPorts,
+ compileWireRequest,
+ requestSchemaFromPorts,
+ sealGenerationPortRequest,
+ sealGenerationPortTable,
+ selectWireModel,
+ verifyRequestAgainstPorts,
+} from "@narratage/generation";
+import type { GenerationPortTable, GenerationWireMapping } from "@narratage/generation";
+
+const table: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "demo-video",
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 200 }, minItems: 1, maxItems: 1 },
+ { name: "duration", value: { kind: "number", integer: true, minimum: 4, maximum: 15 }, minItems: 1, maxItems: 1 },
+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p"] }, minItems: 1, maxItems: 1 },
+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },
+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ { name: "voiceId", value: { kind: "token", minLength: 1, maxLength: 64 }, minItems: 0, maxItems: 4 },
+ {
+ name: "excerpt",
+ value: {
+ kind: "media",
+ accepts: ["video"],
+ itemFields: [
+ { name: "startSec", value: { kind: "number", minimum: 0 } },
+ { name: "endSec", value: { kind: "number", minimum: 0 } },
+ ],
+ },
+ minItems: 0,
+ maxItems: 3,
+ },
+ ],
+ requires: [
+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+ { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage"] },
+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceAudio: 1 }, maximum: 10 },
+ ],
+});
+
+const mapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: { name: "@narratage/demo", version: "0.0.0-dev" }, name: "demo-video" },
+ result: "video",
+ routes: [
+ { model: "demo/image-to-video", whenPresent: ["firstFrame"] },
+ { model: "demo/reference-to-video", whenPresent: ["referenceImage"] },
+ { model: "demo/text-to-video" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "string", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ referenceImage: { as: "urlArray", field: "reference_image_urls" },
+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+ firstFrame: { as: "url", field: "first_frame_url" },
+ lastFrame: { as: "url", field: "last_frame_url" },
+ voiceId: { as: "valueArray", field: "voice_ids" },
+ excerpt: {
+ as: "itemObject",
+ field: "video_list",
+ urlKey: "url",
+ fieldKeys: { startSec: "start", endSec: "ends" },
+ },
+ },
+ constants: { return_last_frame: false },
+};
+
+async function artifacts() {
+ const store = new MemoryArtifactStore();
+ return {
+ image: await store.put(new Uint8Array([1]), "image/png"),
+ video: await store.put(new Uint8Array([2]), "video/mp4"),
+ audio: await store.put(new Uint8Array([3]), "audio/wav"),
+ };
+}
+
+const resolve = async (artifact: { readonly digest: string }) => `https://cdn.test/${artifact.digest}`;
+
+test("a port table derives the request Schema and rejects undeclared ports", () => {
+ const schema = requestSchemaFromPorts(table);
+ assert.equal(schema.kind, "object");
+ const fields = (schema as { fields: Record<string, { schema: { kind: string } }> }).fields;
+ assert.equal(fields.model!.schema.kind, "literal");
+ const ports = fields.ports!.schema as { kind: string; fields: Record<string, { optional?: boolean }> };
+ assert.equal(ports.kind, "object");
+ assert.equal(ports.fields.prompt!.optional, undefined);
+ assert.equal(ports.fields.referenceImage!.optional, true);
+ assert.throws(
+ () => verifyRequestAgainstPorts(table, {
+ contract: "svml.generation-request@1",
+ model: "demo-video",
+ ports: { prompt: ["hi"], duration: [8], resolution: ["720p"], unknownPort: ["x"] },
+ }),
+ /undeclared port unknownPort/u,
+ );
+});
+
+test("a media port enforces the media type its role demands", async () => {
+ const { image, audio } = await artifacts();
+ assert.throws(
+ () => sealGenerationPortRequest(table, {
+ prompt: ["hi"],
+ duration: [8],
+ resolution: ["720p"],
+ firstFrame: [{ role: "image", artifact: audio }],
+ }),
+ /image\//u,
+ );
+ const ok = sealGenerationPortRequest(table, {
+ prompt: ["hi"],
+ duration: [8],
+ resolution: ["720p"],
+ firstFrame: [{ role: "image", artifact: image }],
+ });
+ assert.equal(ok.model, "demo-video");
+});
+
+test("port combination rules replace the old mode union", async () => {
+ const { image } = await artifacts();
+ const base = { prompt: ["hi"], duration: [8], resolution: ["720p"] } as const;
+ assert.throws(
+ () => sealGenerationPortRequest(table, {
+ ...base,
+ referenceImage: [{ role: "image", artifact: image }],
+ firstFrame: [{ role: "image", artifact: image }],
+ }),
+ /at most one of referenceImage, firstFrame/u,
+ );
+ assert.throws(
+ () => sealGenerationPortRequest(table, { ...base, lastFrame: [{ role: "image", artifact: image }] }),
+ /lastFrame also requires firstFrame/u,
+ );
+ assert.throws(
+ () => sealGenerationPortRequest(table, { ...base, resolution: ["1080p"] }),
+ /must be one of 480p, 720p/u,
+ );
+});
+
+test("one mapping compiles every port shape and routes by port presence", async () => {
+ const { image, video, audio } = await artifacts();
+ const request = sealGenerationPortRequest(table, {
+ prompt: ["hello"],
+ duration: [8],
+ resolution: ["720p"],
+ referenceImage: [{ role: "image", artifact: image }],
+ referenceAudio: [{ role: "audio", artifact: audio }],
+ voiceId: ["alpha", "beta"],
+ excerpt: [{ role: "video", artifact: video, fields: { startSec: 1, endSec: 4 } }],
+ });
+ const wire = await compileWireRequest(mapping, request, resolve);
+ assert.equal(wire.model, "demo/reference-to-video");
+ assert.deepEqual(wire.input, {
+ duration: "8",
+ prompt: "hello",
+ reference_audio_urls: [`https://cdn.test/${audio.digest}`],
+ reference_image_urls: [`https://cdn.test/${image.digest}`],
+ resolution: "720p",
+ return_last_frame: false,
+ video_list: [{ ends: 4, start: 1, url: `https://cdn.test/${video.digest}` }],
+ voice_ids: ["alpha", "beta"],
+ });
+
+ const textOnly = sealGenerationPortRequest(table, { prompt: ["hi"], duration: [8], resolution: ["720p"] });
+ assert.equal(selectWireModel(mapping, new Set(Object.keys(textOnly.ports))), "demo/text-to-video");
+ const framed = sealGenerationPortRequest(table, {
+ prompt: ["hi"],
+ duration: [8],
+ resolution: ["720p"],
+ firstFrame: [{ role: "image", artifact: image }],
+ });
+ assert.equal((await compileWireRequest(mapping, framed, resolve)).model, "demo/image-to-video");
+});
+
+test("coverage rejects a mapping that forgets a port the model declares", () => {
+ assertMappingCoversPorts(table, mapping);
+ const { referenceAudio: _audio, ...withoutAudio } = mapping.fields;
+ assert.throws(
+ () => assertMappingCoversPorts(table, { ...mapping, fields: withoutAudio }),
+ /does not cover port referenceAudio/u,
+ );
+
+ const { excerpt: _excerpt, ...missingPort } = mapping.fields;
+ assert.throws(
+ () => assertMappingCoversPorts(table, { ...mapping, fields: missingPort }),
+ /does not cover port excerpt/u,
+ );
+
+ const wrongShape: GenerationWireMapping = {
+ ...mapping,
+ fields: { ...mapping.fields, voiceId: { as: "value", field: "voice_ids" } },
+ };
+ assert.throws(() => assertMappingCoversPorts(table, wrongShape), /must use valueArray/u);
+});
diff --git a/packages/gpt-image/src/index.ts b/packages/gpt-image/src/index.ts
index f249ad01..1cf6dc4f 100644
--- a/packages/gpt-image/src/index.ts
+++ b/packages/gpt-image/src/index.ts
@@ -1,85 +1,45 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const gptImageModuleRef = { name: "@narratage/gpt-image", version: "0.0.0-dev" } as const;
-export type GptImage2Mode = "text" | "image";
-type Common = {
- readonly contract: "svml.gpt-image-2-request@1";
- readonly model: "gpt-image-2";
- readonly prompt: string;
- readonly aspectRatio: string;
-};
-export type GptImage2TextRequestContent = Common & { readonly mode: "text" };
-export type GptImage2ImageRequestContent = Common & {
- readonly mode: "image";
- readonly images: readonly BlobRef[];
-};
-export type GptImage2RequestContent = GptImage2TextRequestContent | GptImage2ImageRequestContent;
-export type GptImage2Request = GptImage2RequestContent;
-const commonFields = {
- contract: { schema: { kind: "literal", value: "svml.gpt-image-2-request@1" } },
- model: { schema: { kind: "literal", value: "gpt-image-2" } },
- prompt: { schema: generationPromptSchema },
- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },
-} as const;
-const schemas: Record<GptImage2Mode, ValueSchema> = {
- text: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "text" } },
- }),
- image: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "image" } },
- images: { schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema } },
- }),
-};
-
-function object(value: unknown): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("GPT Image 2 request must be an object");
- return value as Record<string, unknown>;
-}
-
-export function verifyGptImage2Request(value: unknown, expectedMode?: GptImage2Mode): asserts value is GptImage2Request {
- const request = object(value);
- if (request.contract !== "svml.gpt-image-2-request@1" || request.model !== "gpt-image-2") {
- throw new Error("GPT Image 2 request identity is invalid");
- }
- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected GPT Image 2 ${expectedMode}`);
- if (request.mode === "image") {
- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("GPT Image 2 input images are empty");
- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- } else if (request.mode !== "text") {
- throw new Error("GPT Image 2 mode is invalid");
- }
-}
+export const gptImage2Ports: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "gpt-image-2",
+ result: "image",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },
+ {
+ name: "aspectRatio",
+ value: {
+ kind: "enum",
+ values: ["auto", "1:1", "3:2", "2:3", "4:3", "3:4", "5:4", "4:5",
+ "16:9", "9:16", "2:1", "1:2", "3:1", "1:3", "21:9", "9:21"],
+ },
+ minItems: 1,
+ maxItems: 1,
+ },
+ { name: "resolution", value: { kind: "enum", values: ["1K", "2K", "4K"] }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 16 },
+ ],
+ requires: [],
+});
-export function sealGptImage2Request<T extends GptImage2RequestContent>(
- content: T,
-): T {
- const request = sealGenerationRequest(content);
- verifyGptImage2Request(request, content.mode);
- return request;
+export function sealGptImage2Request(
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(gptImage2Ports, ports);
}
export const gptImageDefinition = defineExactModelModule({
module: gptImageModuleRef,
- endpoints: (["text", "image"] as const).map((mode) => ({
- key: mode,
- requestTypeName: mode === "text" ? "GptImage2TextRequest" : "GptImage2ImageRequest",
- capabilityName: `gpt-image-2-${mode}-generation`,
- producerName: `request-gpt-image-2-${mode}`,
- result: "image" as const,
- requestSchema: schemas[mode],
- verifyRequest: (value: unknown) => verifyGptImage2Request(value, mode),
- })),
+ endpoints: [{
+ key: "image",
+ requestTypeName: "GptImage2Request",
+ producerName: "request-gpt-image-2",
+ ports: gptImage2Ports,
+ }],
});
export const gptImageManifest = gptImageDefinition.manifest;
diff --git a/packages/grok-imagine/src/index.ts b/packages/grok-imagine/src/index.ts
index 35e139b6..01f884a6 100644
--- a/packages/grok-imagine/src/index.ts
+++ b/packages/grok-imagine/src/index.ts
@@ -1,124 +1,79 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const grokImagineModuleRef = { name: "@narratage/grok-imagine", version: "0.0.0-dev" } as const;
-export type GrokImagineMode = "text" | "image" | "preview-1.5";
+export const grokImagineModels = ["grok-imagine-video", "grok-imagine-video-1.5-preview"] as const;
+export type GrokImagineModel = typeof grokImagineModels[number];
-type Common = {
- readonly contract: "svml.grok-imagine-video-request@1";
- readonly prompt: string;
- readonly aspectRatio: string;
- readonly resolution: "480p" | "720p";
- readonly durationSec: number;
-};
-export type GrokImagineTextRequestContent = Common & {
- readonly model: "grok-imagine-video";
- readonly mode: "text";
-};
-export type GrokImagineImageRequestContent = Common & {
- readonly model: "grok-imagine-video";
- readonly mode: "image";
- readonly images: readonly BlobRef[];
- /** Optional KIE continuation identity; omitted for ordinary image-to-video. */
- readonly sourceTaskId?: string;
-};
-export type GrokImaginePreviewRequestContent = Common & {
- readonly model: "grok-imagine-video-1.5-preview";
- readonly mode: "preview-1.5";
- readonly images?: readonly BlobRef[];
-};
-export type GrokImagineRequestContent =
- | GrokImagineTextRequestContent
- | GrokImagineImageRequestContent
- | GrokImaginePreviewRequestContent;
-export type GrokImagineRequest = GrokImagineRequestContent;
-
-const aspectSchema = { kind: "string", minLength: 3, maxLength: 16 } as const satisfies ValueSchema;
-const commonFields = {
- contract: { schema: { kind: "literal", value: "svml.grok-imagine-video-request@1" } },
- prompt: { schema: generationPromptSchema },
- aspectRatio: { schema: aspectSchema },
- resolution: { schema: { kind: "string", enum: ["480p", "720p"] } },
- durationSec: { schema: { kind: "number", integer: true, minimum: 1, maximum: 15 } },
-} as const;
-const schemas: Record<GrokImagineMode, ValueSchema> = {
- text: generationObjectSchema({
- ...commonFields,
- model: { schema: { kind: "literal", value: "grok-imagine-video" } },
- mode: { schema: { kind: "literal", value: "text" } },
- }),
- image: generationObjectSchema({
- ...commonFields,
- model: { schema: { kind: "literal", value: "grok-imagine-video" } },
- mode: { schema: { kind: "literal", value: "image" } },
- images: { schema: { kind: "array", minItems: 1, maxItems: 4, items: generationBlobRefSchema } },
- sourceTaskId: { schema: { kind: "string", minLength: 1, maxLength: 255 }, optional: true },
- }),
- "preview-1.5": generationObjectSchema({
- ...commonFields,
- model: { schema: { kind: "literal", value: "grok-imagine-video-1.5-preview" } },
- mode: { schema: { kind: "literal", value: "preview-1.5" } },
- images: {
- schema: { kind: "array", minItems: 1, maxItems: 4, items: generationBlobRefSchema },
- optional: true,
+export const grokImagineVideoPorts: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "grok-imagine-video",
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+ {
+ name: "aspectRatio",
+ value: { kind: "enum", values: ["2:3", "3:2", "1:1", "16:9", "9:16"] },
+ minItems: 1,
+ maxItems: 1,
},
- }),
-};
+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },
+ { name: "duration", value: { kind: "number", integer: true, minimum: 6, maximum: 30 }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 4 },
+ /** Continues an earlier generation; only meaningful beside its source images. */
+ { name: "sourceTaskId", value: { kind: "token", minLength: 1, maxLength: 255 }, minItems: 0, maxItems: 1 },
+ ],
+ requires: [{ kind: "requiresPresent", port: "sourceTaskId", needs: ["images"] }],
+});
-function object(value: unknown): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Grok Imagine request must be an object");
- return value as Record<string, unknown>;
-}
+export const grokImagine15PreviewPorts: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "grok-imagine-video-1.5-preview",
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 5_000 }, minItems: 1, maxItems: 1 },
+ {
+ name: "aspectRatio",
+ value: { kind: "enum", values: ["2:3", "3:2", "1:1", "16:9", "9:16"] },
+ minItems: 1,
+ maxItems: 1,
+ },
+ { name: "resolution", value: { kind: "enum", values: ["480p", "720p", "1080p"] }, minItems: 1, maxItems: 1 },
+ { name: "duration", value: { kind: "number", integer: true, minimum: 6, maximum: 30 }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 4 },
+ ],
+ requires: [],
+});
-export function verifyGrokImagineRequest(value: unknown, expectedMode?: GrokImagineMode): asserts value is GrokImagineRequest {
- const request = object(value);
- if (request.contract !== "svml.grok-imagine-video-request@1") throw new Error("Grok Imagine request contract is invalid");
- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected Grok Imagine ${expectedMode}`);
- if (request.mode === "image") {
- if (request.model !== "grok-imagine-video" || !Array.isArray(request.images) || request.images.length === 0) {
- throw new Error("Grok Imagine image request is invalid");
- }
- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- } else if (request.mode === "preview-1.5") {
- if (request.model !== "grok-imagine-video-1.5-preview") throw new Error("Grok Imagine preview model is invalid");
- if (request.images !== undefined) {
- if (!Array.isArray(request.images)) throw new Error("Grok Imagine preview images are invalid");
- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- }
- } else if (request.mode === "text") {
- if (request.model !== "grok-imagine-video") throw new Error("Grok Imagine text model is invalid");
- } else {
- throw new Error("Grok Imagine mode is invalid");
- }
-}
+export const grokImaginePorts: Readonly<Record<GrokImagineModel, GenerationPortTable>> = {
+ "grok-imagine-video": grokImagineVideoPorts,
+ "grok-imagine-video-1.5-preview": grokImagine15PreviewPorts,
+};
-export function sealGrokImagineRequest<T extends GrokImagineRequestContent>(
- content: T,
-): T {
- const request = sealGenerationRequest(content);
- verifyGrokImagineRequest(request, content.mode);
- return request;
+export function sealGrokImagineRequest(
+ model: GrokImagineModel,
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(grokImaginePorts[model], ports);
}
export const grokImagineDefinition = defineExactModelModule({
module: grokImagineModuleRef,
- endpoints: (["text", "image", "preview-1.5"] as const).map((mode) => ({
- key: mode,
- requestTypeName: mode === "text" ? "GrokImagineTextVideoRequest"
- : mode === "image" ? "GrokImagineImageVideoRequest" : "GrokImagine15PreviewRequest",
- capabilityName: `grok-imagine-${mode}-video-generation`,
- producerName: `request-grok-imagine-${mode}`,
- result: "video" as const,
- requestSchema: schemas[mode],
- verifyRequest: (value: unknown) => verifyGrokImagineRequest(value, mode),
- })),
+ endpoints: [
+ {
+ key: "video",
+ requestTypeName: "GrokImagineVideoRequest",
+ producerName: "request-grok-imagine-video",
+ ports: grokImagineVideoPorts,
+ },
+ {
+ key: "preview-1.5",
+ requestTypeName: "GrokImagine15PreviewRequest",
+ producerName: "request-grok-imagine-preview-1-5",
+ ports: grokImagine15PreviewPorts,
+ },
+ ],
});
export const grokImagineManifest = grokImagineDefinition.manifest;
diff --git a/packages/minimax-h3/src/index.ts b/packages/minimax-h3/src/index.ts
index 2ba4e09a..a4604dfc 100644
--- a/packages/minimax-h3/src/index.ts
+++ b/packages/minimax-h3/src/index.ts
@@ -1,129 +1,69 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const minimaxH3ModuleRef = { name: "@narratage/minimax-h3", version: "0.0.0-dev" } as const;
-export type MinimaxH3Mode = "text" | "frames" | "reference";
-export type MinimaxH3Reference =
- | { readonly kind: "image"; readonly artifact: BlobRef }
- | { readonly kind: "video"; readonly artifact: BlobRef }
- | { readonly kind: "audio"; readonly artifact: BlobRef };
-type Common = {
- readonly contract: "svml.minimax-h3-request@1";
- readonly model: "minimax-h3";
- readonly prompt: string;
- readonly durationSec: number;
-};
-
-export type MinimaxH3TextRequestContent = Common & {
- readonly mode: "text";
- readonly aspectRatio: string;
-};
-export type MinimaxH3FramesRequestContent = Common & {
- readonly mode: "frames";
- readonly firstFrame: BlobRef;
- readonly lastFrame?: BlobRef;
-};
-export type MinimaxH3ReferenceRequestContent = Common & {
- readonly mode: "reference";
- readonly references: readonly MinimaxH3Reference[];
- readonly aspectRatio: string;
-};
-export type MinimaxH3RequestContent =
- | MinimaxH3TextRequestContent
- | MinimaxH3FramesRequestContent
- | MinimaxH3ReferenceRequestContent;
-export type MinimaxH3Request = MinimaxH3RequestContent;
-
-const commonFields = {
- contract: { schema: { kind: "literal", value: "svml.minimax-h3-request@1" } },
- model: { schema: { kind: "literal", value: "minimax-h3" } },
- prompt: { schema: generationPromptSchema },
- durationSec: { schema: { kind: "number", integer: true, minimum: 1, maximum: 60 } },
-} as const;
-const aspect = { kind: "string", minLength: 3, maxLength: 16 } as const satisfies ValueSchema;
-const referenceSchema: ValueSchema = {
- kind: "oneOf",
- variants: (["image", "video", "audio"] as const).map((kind) => generationObjectSchema({
- kind: { schema: { kind: "literal", value: kind } },
- artifact: { schema: generationBlobRefSchema },
- })),
-};
-
-const schemas: Record<MinimaxH3Mode, ValueSchema> = {
- text: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "text" } },
- aspectRatio: { schema: aspect },
- }),
- frames: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "frames" } },
- firstFrame: { schema: generationBlobRefSchema },
- lastFrame: { schema: generationBlobRefSchema, optional: true },
- }),
- reference: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "reference" } },
- references: { schema: { kind: "array", minItems: 1, maxItems: 12, items: referenceSchema } },
- aspectRatio: { schema: aspect },
- }),
-};
-
-function object(value: unknown, subject: string): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error(`${subject} must be an object`);
- return value as Record<string, unknown>;
-}
-
-export function verifyMinimaxH3Request(value: unknown, expectedMode?: MinimaxH3Mode): asserts value is MinimaxH3Request {
- const request = object(value, "MiniMax H3 request");
- if (request.contract !== "svml.minimax-h3-request@1" || request.model !== "minimax-h3") {
- throw new Error("MiniMax H3 request identity is invalid");
- }
- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected MiniMax H3 ${expectedMode}`);
- if (request.mode === "frames") {
- assertGenerationBlobRef(request.firstFrame, "image/");
- if (request.lastFrame !== undefined) assertGenerationBlobRef(request.lastFrame, "image/");
- } else if (request.mode === "reference") {
- if (!Array.isArray(request.references) || request.references.length === 0) throw new Error("MiniMax H3 references are empty");
- request.references.forEach((candidate) => {
- const item = object(candidate, "MiniMax H3 reference");
- if (item.kind !== "image" && item.kind !== "video" && item.kind !== "audio") {
- throw new Error("MiniMax H3 reference kind is invalid");
- }
- assertGenerationBlobRef(item.artifact, `${item.kind}/` as "image/" | "video/" | "audio/");
- });
- } else if (request.mode !== "text") {
- throw new Error("MiniMax H3 mode is invalid");
- }
-}
+/**
+ * What MiniMax H3 accepts is a property of the trained model, not of whichever
+ * service resells it. A service that splits these ports across several of its
+ * own endpoints expresses that in its wire mapping.
+ *
+ * `768P` and `2K` are the model's own two output tiers — H3-Base renders at
+ * 768p and H3-Regenerate-2K re-renders from the original context — so the
+ * spelling is MiniMax's, not any gateway's.
+ */
+export const minimaxH3Ports: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "minimax-h3",
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 7_000 }, minItems: 1, maxItems: 1 },
+ {
+ name: "duration",
+ value: { kind: "number", integer: true, minimum: 4, maximum: 15 },
+ minItems: 1,
+ maxItems: 1,
+ },
+ { name: "resolution", value: { kind: "enum", values: ["768P", "2K"] }, minItems: 0, maxItems: 1 },
+ {
+ name: "aspectRatio",
+ value: { kind: "enum", values: ["21:9", "16:9", "4:3", "1:1", "3:4", "9:16"] },
+ minItems: 0,
+ maxItems: 1,
+ },
+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+ { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 3 },
+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },
+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ ],
+ requires: [
+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+ { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },
+ { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },
+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },
+ // A first/last frame run inherits its framing from the uploaded image, so the
+ // model takes no aspect ratio in that mode.
+ { kind: "atMostOneOf", ports: ["aspectRatio", "firstFrame"] },
+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },
+ ],
+});
-export function sealMinimaxH3Request<T extends MinimaxH3RequestContent>(
- content: T,
-): T {
- const request = sealGenerationRequest(content);
- verifyMinimaxH3Request(request, content.mode);
- return request;
+export function sealMinimaxH3Request(
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(minimaxH3Ports, ports);
}
export const minimaxH3Definition = defineExactModelModule({
module: minimaxH3ModuleRef,
- endpoints: (["text", "frames", "reference"] as const).map((mode) => ({
- key: mode,
- requestTypeName: `MinimaxH3${mode[0]!.toUpperCase()}${mode.slice(1)}Request`,
- capabilityName: `minimax-h3-${mode}-generation`,
- producerName: `request-minimax-h3-${mode}`,
- result: "video" as const,
- requestSchema: schemas[mode],
- verifyRequest: (value: unknown) => verifyMinimaxH3Request(value, mode),
- })),
+ endpoints: [{
+ key: "video",
+ requestTypeName: "MinimaxH3Request",
+ producerName: "request-minimax-h3",
+ ports: minimaxH3Ports,
+ }],
});
export const minimaxH3Manifest = minimaxH3Definition.manifest;
diff --git a/packages/model-kit/src/index.ts b/packages/model-kit/src/index.ts
index 16498e7c..1d9bee2e 100644
--- a/packages/model-kit/src/index.ts
+++ b/packages/model-kit/src/index.ts
@@ -8,7 +8,10 @@ import {
generationManifestDigest,
generationModuleRef,
generationTypes,
+ requestSchemaFromPorts,
+ verifyRequestAgainstPorts,
} from "@narratage/generation";
+import type { GenerationPortTable } from "@narratage/generation";
import {
canonicalize,
digestOf,
@@ -21,18 +24,19 @@ import type {
ModuleRef,
ProducerRef,
TypeRef,
- ValueSchema,
} from "@narratage/protocol";
+/**
+ * One exact model endpoint. The model declares which input ports it accepts;
+ * its request Schema and semantic validator are derived from that declaration,
+ * so the Capability name, the accepted media roles and the port cardinalities
+ * have exactly one source of truth.
+ */
export type ExactModelEndpointSpec = {
readonly key: string;
readonly requestTypeName: string;
- readonly capabilityName: string;
readonly producerName: string;
- readonly result: "image" | "video";
- readonly requestSchema: ValueSchema;
- /** Checks digest identity and model-specific constraints after structural validation. */
- readonly verifyRequest: (value: unknown) => void;
+ readonly ports: GenerationPortTable;
};
export type ExactModelEndpoint = {
@@ -43,23 +47,25 @@ export type ExactModelEndpoint = {
readonly returns: TypeRef;
readonly implementationDigest: Digest;
readonly validatorDigest: Digest;
+ readonly ports: GenerationPortTable;
readonly fragment: ReturnType<typeof sealGraphFragment>;
};
-export type ExactModelModule = {
+export type ExactModelModule<Key extends string = string> = {
readonly module: ModuleRef;
readonly manifest: ModuleManifest;
readonly manifestDigest: Digest;
- readonly endpoints: Readonly<Record<string, ExactModelEndpoint>>;
+ /** Keyed by the exact endpoint keys the module declared, so a stale key fails to compile. */
+ readonly endpoints: Readonly<Record<Key, ExactModelEndpoint>>;
readonly component: ComponentPackage & {
readonly validators: readonly TypeValidatorFacet[];
readonly producers: readonly ProducerFacet[];
};
};
-export type DefineExactModelModuleOptions = {
+export type DefineExactModelModuleOptions<Key extends string = string> = {
readonly module: ModuleRef;
- readonly endpoints: readonly ExactModelEndpointSpec[];
+ readonly endpoints: readonly (Omit<ExactModelEndpointSpec, "key"> & { readonly key: Key })[];
};
function assert(condition: unknown, message: string): asserts condition {
@@ -68,9 +74,9 @@ function assert(condition: unknown, message: string): asserts condition {
function endpointRef(module: ModuleRef, spec: ExactModelEndpointSpec) {
const requestType = { module, name: spec.requestTypeName };
- const capability = { module, name: spec.capabilityName };
+ const capability = { module, name: spec.ports.model };
const producer = { module, name: spec.producerName };
- const returns = spec.result === "image" ? generationTypes.imageSet : generationTypes.videoSet;
+ const returns = spec.ports.result === "image" ? generationTypes.imageSet : generationTypes.videoSet;
const implementationDigest = digestOf(`${module.name}/${spec.producerName}@1`);
const validatorDigest = digestOf(`${module.name}/validate-${spec.requestTypeName}@1`);
return { requestType, capability, producer, returns, implementationDigest, validatorDigest };
@@ -88,12 +94,16 @@ function inlineRequest(
* Builds the repetitive nominal shell around an exact model request. The model package still owns
* every field, constraint and model name; this helper only wires Type -> Producer -> Need -> Fragment.
*/
-export function defineExactModelModule(options: DefineExactModelModuleOptions): ExactModelModule {
+export function defineExactModelModule<const Key extends string>(
+ options: DefineExactModelModuleOptions<Key>,
+): ExactModelModule<Key> {
assert(options.module.name.trim().length > 0 && options.module.version.trim().length > 0,
"Exact model module identity is invalid");
assert(options.endpoints.length > 0, `${options.module.name} declares no exact model endpoint`);
const keys = options.endpoints.map((item) => item.key);
assert(new Set(keys).size === keys.length, `${options.module.name} repeats an endpoint key`);
+ const models = options.endpoints.map((item) => item.ports.model);
+ assert(new Set(models).size === models.length, `${options.module.name} repeats an exact model`);
const endpointData = options.endpoints.map((spec) => ({ spec, ...endpointRef(options.module, spec) }));
const manifest: ModuleManifest = {
@@ -103,7 +113,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):
dependencies: [{ module: generationModuleRef, digest: generationManifestDigest }],
types: endpointData.map((item) => ({
name: item.requestType.name,
- schema: item.spec.requestSchema,
+ schema: requestSchemaFromPorts(item.spec.ports),
validator: {
abi: "svml.type-validator@1",
implementation: {
@@ -135,7 +145,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):
})),
};
- const endpoints = Object.fromEntries(endpointData.map((item) => {
+ const endpoints = Object.fromEntries(endpointData.map((item): [Key, ExactModelEndpoint] => {
const fragment = sealGraphFragment({
name: `${options.module.name}/${item.spec.key}@1`,
inputs: [{ name: "request", type: item.requestType }],
@@ -161,6 +171,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):
returns: item.returns,
implementationDigest: item.implementationDigest,
validatorDigest: item.validatorDigest,
+ ports: item.spec.ports,
fragment,
} satisfies ExactModelEndpoint];
}));
@@ -169,14 +180,14 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):
module: { ...options.module },
manifest,
manifestDigest: digestOf(manifest),
- endpoints,
+ endpoints: endpoints as Readonly<Record<Key, ExactModelEndpoint>>,
component: {
name: options.module.name,
validators: endpointData.map((item) => ({
type: item.requestType,
implementationDigest: item.validatorDigest,
handler({ value }) {
- item.spec.verifyRequest(inlineRequest(value, item.spec.key));
+ verifyRequestAgainstPorts(item.spec.ports, inlineRequest(value, item.spec.key));
},
})),
producers: endpointData.map((item) => ({
@@ -186,7 +197,7 @@ export function defineExactModelModule(options: DefineExactModelModuleOptions):
const requestRecord = inputs.request;
assert(requestRecord !== undefined, `${item.spec.key} request input is missing`);
const request = inlineRequest(requestRecord.value, item.spec.key);
- item.spec.verifyRequest(request);
+ verifyRequestAgainstPorts(item.spec.ports, request);
return { outputs: {}, needs: { generation: request } };
},
})),
diff --git a/packages/nano-banana/src/index.ts b/packages/nano-banana/src/index.ts
index 65636e8e..3a484180 100644
--- a/packages/nano-banana/src/index.ts
+++ b/packages/nano-banana/src/index.ts
@@ -1,78 +1,55 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const nanoBananaModuleRef = { name: "@narratage/nano-banana", version: "0.0.0-dev" } as const;
export const nanoBananaModels = ["nano-banana-2", "nano-banana-pro"] as const;
export type NanoBananaModel = typeof nanoBananaModels[number];
-export type NanoBananaRequestContent<M extends NanoBananaModel = NanoBananaModel> = {
- readonly contract: "svml.nano-banana-request@1";
- readonly model: M;
- readonly prompt: string;
- readonly images?: readonly BlobRef[];
- readonly aspectRatio: string;
- readonly resolution: "1K" | "2K" | "4K";
- readonly outputFormat: "png" | "jpg";
-};
-export type NanoBananaRequest<M extends NanoBananaModel = NanoBananaModel> = NanoBananaRequestContent<M>;
-function requestSchema(model: NanoBananaModel): ValueSchema {
- return generationObjectSchema({
- contract: { schema: { kind: "literal", value: "svml.nano-banana-request@1" } },
- model: { schema: { kind: "literal", value: model } },
- prompt: { schema: generationPromptSchema },
- images: {
- schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema },
- optional: true,
- },
- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },
- resolution: { schema: { kind: "string", enum: ["1K", "2K", "4K"] } },
- outputFormat: { schema: { kind: "string", enum: ["png", "jpg"] } },
+function nanoBananaPortTable(model: NanoBananaModel): GenerationPortTable {
+ return sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model,
+ result: "image",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 14 },
+ {
+ name: "aspectRatio",
+ value: {
+ kind: "enum",
+ values: ["auto", "1:1", "2:3", "3:2", "1:4", "4:1", "3:4", "4:3", "4:5",
+ "5:4", "1:8", "8:1", "9:16", "16:9", "21:9"],
+ },
+ minItems: 1,
+ maxItems: 1,
+ },
+ { name: "resolution", value: { kind: "enum", values: ["1K", "2K", "4K"] }, minItems: 1, maxItems: 1 },
+ { name: "outputFormat", value: { kind: "enum", values: ["png", "jpg"] }, minItems: 1, maxItems: 1 },
+ ],
+ requires: [],
});
}
-function object(value: unknown): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Nano Banana request must be an object");
- return value as Record<string, unknown>;
-}
-
-export function verifyNanoBananaRequest(value: unknown, expectedModel?: NanoBananaModel): asserts value is NanoBananaRequest {
- const request = object(value);
- if (request.contract !== "svml.nano-banana-request@1"
- || !nanoBananaModels.includes(request.model as NanoBananaModel)) {
- throw new Error("Nano Banana request identity is invalid");
- }
- if (expectedModel !== undefined && request.model !== expectedModel) throw new Error(`Expected ${expectedModel}`);
- if (request.images !== undefined) {
- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("Nano Banana images are invalid");
- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- }
-}
+export const nanoBananaPorts: Readonly<Record<NanoBananaModel, GenerationPortTable>> = {
+ "nano-banana-2": nanoBananaPortTable("nano-banana-2"),
+ "nano-banana-pro": nanoBananaPortTable("nano-banana-pro"),
+};
-export function sealNanoBananaRequest<M extends NanoBananaModel>(
- content: NanoBananaRequestContent<M>,
-): NanoBananaRequest<M> {
- const request = sealGenerationRequest(content);
- verifyNanoBananaRequest(request, content.model);
- return request;
+export function sealNanoBananaRequest(
+ model: NanoBananaModel,
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(nanoBananaPorts[model], ports);
}
export const nanoBananaDefinition = defineExactModelModule({
module: nanoBananaModuleRef,
- endpoints: (["nano-banana-2", "nano-banana-pro"] as const).map((model) => ({
+ endpoints: nanoBananaModels.map((model) => ({
key: model === "nano-banana-2" ? "v2" : "pro",
requestTypeName: model === "nano-banana-2" ? "NanoBanana2Request" : "NanoBananaProRequest",
- capabilityName: `${model}-generation`,
producerName: `request-${model}`,
- result: "image" as const,
- requestSchema: requestSchema(model),
- verifyRequest: (value: unknown) => verifyNanoBananaRequest(value, model),
+ ports: nanoBananaPorts[model],
})),
});
diff --git a/packages/provider-kie/package.json b/packages/provider-kie/package.json
index 08ec30a8..0324b3bc 100644
--- a/packages/provider-kie/package.json
+++ b/packages/provider-kie/package.json
@@ -11,18 +11,11 @@
},
"dependencies": {
"@narratage/endpoint-kit": "workspace:*",
- "@narratage/gemini-omni": "workspace:*",
"@narratage/generation": "workspace:*",
- "@narratage/gpt-image": "workspace:*",
- "@narratage/grok-imagine": "workspace:*",
- "@narratage/minimax-h3": "workspace:*",
- "@narratage/nano-banana": "workspace:*",
"@narratage/protocol": "workspace:*",
"@narratage/runtime": "workspace:*",
"@narratage/runtime-adapter": "workspace:*",
- "@narratage/runtime-adapter-node": "workspace:*",
- "@narratage/seedance": "workspace:*",
- "@narratage/seedream": "workspace:*"
+ "@narratage/runtime-adapter-node": "workspace:*"
},
"devDependencies": {
"@narratage/artifact-store-fs": "workspace:*",
@@ -30,10 +23,17 @@
"@narratage/core": "workspace:*",
"@narratage/driver-node": "workspace:*",
"@narratage/elaborator": "workspace:*",
+ "@narratage/gemini-omni": "workspace:*",
+ "@narratage/gpt-image": "workspace:*",
+ "@narratage/grok-imagine": "workspace:*",
"@narratage/local": "workspace:*",
"@narratage/media": "workspace:*",
+ "@narratage/minimax-h3": "workspace:*",
"@narratage/model-kit": "workspace:*",
+ "@narratage/nano-banana": "workspace:*",
"@narratage/narrative": "workspace:*",
+ "@narratage/seedance": "workspace:*",
+ "@narratage/seedream": "workspace:*",
"@narratage/validation": "workspace:*"
}
}
diff --git a/packages/provider-kie/src/catalog.ts b/packages/provider-kie/src/catalog.ts
deleted file mode 100644
index 0111dffa..00000000
--- a/packages/provider-kie/src/catalog.ts
+++ /dev/null
@@ -1,313 +0,0 @@
-import {
- geminiOmniEndpoints,
- verifyGeminiOmniRequest,
-} from "@narratage/gemini-omni";
-import type { GeminiOmniRequest } from "@narratage/gemini-omni";
-import {
- gptImageEndpoints,
- verifyGptImage2Request,
-} from "@narratage/gpt-image";
-import type { GptImage2Request } from "@narratage/gpt-image";
-import {
- grokImagineEndpoints,
- verifyGrokImagineRequest,
-} from "@narratage/grok-imagine";
-import type { GrokImagineRequest } from "@narratage/grok-imagine";
-import {
- minimaxH3Endpoints,
- verifyMinimaxH3Request,
-} from "@narratage/minimax-h3";
-import type { MinimaxH3Request } from "@narratage/minimax-h3";
-import {
- nanoBananaEndpoints,
- verifyNanoBananaRequest,
-} from "@narratage/nano-banana";
-import type { NanoBananaRequest } from "@narratage/nano-banana";
-import { canonicalize } from "@narratage/protocol";
-import type {
- BlobRef,
- CanonicalValue,
- CapabilityRef,
- TypeRef,
-} from "@narratage/protocol";
-import {
- seedanceEndpoints,
- verifySeedanceRequest,
-} from "@narratage/seedance";
-import type { SeedanceRequest } from "@narratage/seedance";
-import {
- seedreamEndpoints,
- verifySeedreamRequest,
-} from "@narratage/seedream";
-import type { SeedreamRequest } from "@narratage/seedream";
-
-export type KieArtifactUrlResolver = (artifact: BlobRef) => Promise<string>;
-
-export type KieTask = {
- readonly model: string;
- readonly input: CanonicalValue;
- readonly result: "image" | "video";
-};
-
-export type KieModelAdapter = {
- readonly key: string;
- readonly capability: CapabilityRef;
- readonly returns: TypeRef;
- readonly result: "image" | "video";
- verify(value: unknown): void;
- task(value: unknown, resolve: KieArtifactUrlResolver): Promise<KieTask>;
-};
-
-function capabilityKey(ref: CapabilityRef): string {
- return `${ref.module.name}@${ref.module.version}#${ref.name}`;
-}
-
-async function urls(values: readonly BlobRef[] | undefined, resolve: KieArtifactUrlResolver): Promise<string[]> {
- return values === undefined ? [] : await Promise.all(values.map(resolve));
-}
-
-function adapter(
- key: string,
- endpoint: { readonly capability: CapabilityRef; readonly returns: TypeRef },
- result: "image" | "video",
- verify: (value: unknown) => void,
- task: (value: unknown, resolve: KieArtifactUrlResolver) => Promise<KieTask>,
-): KieModelAdapter {
- return { key, capability: endpoint.capability, returns: endpoint.returns, result, verify, task };
-}
-
-const seedanceAdapters = ([
- ["standard", "bytedance/seedance-2", "seedance-2"],
- ["fast", "bytedance/seedance-2-fast", "seedance-2-fast"],
- ["mini", "bytedance/seedance-2-mini", "seedance-2-mini"],
-] as const).map(([key, kieModel, authorModel]) => adapter(
- `seedance.${key}`,
- seedanceEndpoints[key]!,
- "video",
- (value) => verifySeedanceRequest(value, authorModel),
- async (value, resolve) => {
- verifySeedanceRequest(value, authorModel);
- const request = value as SeedanceRequest;
- const modeInput: Record<string, CanonicalValue> = {};
- if (request.mode.kind === "frames") {
- modeInput.first_frame_url = await resolve(request.mode.firstFrame);
- if (request.mode.lastFrame !== undefined) modeInput.last_frame_url = await resolve(request.mode.lastFrame);
- } else if (request.mode.kind === "reference") {
- const groups = {
- image: request.mode.items.filter((item) => item.kind === "image").map((item) => item.artifact),
- video: request.mode.items.filter((item) => item.kind === "video").map((item) => item.artifact),
- audio: request.mode.items.filter((item) => item.kind === "audio").map((item) => item.artifact),
- };
- if (groups.image.length > 0) modeInput.reference_image_urls = await urls(groups.image, resolve);
- if (groups.video.length > 0) modeInput.reference_video_urls = await urls(groups.video, resolve);
- if (groups.audio.length > 0) modeInput.reference_audio_urls = await urls(groups.audio, resolve);
- }
- return {
- model: kieModel,
- result: "video",
- input: canonicalize({
- prompt: request.prompt,
- ...modeInput,
- return_last_frame: false,
- generate_audio: request.generateAudio,
- resolution: request.resolution,
- aspect_ratio: request.aspectRatio,
- duration: request.durationSec,
- web_search: request.webSearch,
- }),
- };
- },
-));
-
-const minimaxAdapters = ([
- ["text", "minimax-h3/text-to-video"],
- ["frames", "minimax-h3/image-to-video"],
- ["reference", "minimax-h3/reference-to-video"],
-] as const).map(([mode, kieModel]) => adapter(
- `minimax-h3.${mode}`,
- minimaxH3Endpoints[mode]!,
- "video",
- (value) => verifyMinimaxH3Request(value, mode),
- async (value, resolve) => {
- verifyMinimaxH3Request(value, mode);
- const request = value as MinimaxH3Request;
- const input: Record<string, CanonicalValue> = {
- prompt: request.prompt,
- duration: request.durationSec,
- };
- if (request.mode === "text") input.aspect_ratio = request.aspectRatio;
- if (request.mode === "frames") {
- input.first_frame_url = await resolve(request.firstFrame);
- if (request.lastFrame !== undefined) input.last_frame_url = await resolve(request.lastFrame);
- }
- if (request.mode === "reference") {
- input.aspect_ratio = request.aspectRatio;
- const images = request.references.filter((item) => item.kind === "image").map((item) => item.artifact);
- const videos = request.references.filter((item) => item.kind === "video").map((item) => item.artifact);
- const audios = request.references.filter((item) => item.kind === "audio").map((item) => item.artifact);
- if (images.length > 0) input.reference_image_urls = await urls(images, resolve);
- if (videos.length > 0) input.reference_video_urls = await urls(videos, resolve);
- if (audios.length > 0) input.reference_audio_urls = await urls(audios, resolve);
- }
- return {
- model: kieModel,
- input: canonicalize(input),
- result: "video",
- };
- },
-));
-
-const geminiAdapter = adapter(
- "gemini-omni.video",
- geminiOmniEndpoints.video!,
- "video",
- verifyGeminiOmniRequest,
- async (value, resolve) => {
- verifyGeminiOmniRequest(value);
- const request = value as GeminiOmniRequest;
- const input: Record<string, CanonicalValue> = {
- prompt: request.prompt,
- duration: String(request.durationSec),
- aspect_ratio: request.aspectRatio,
- resolution: request.resolution,
- };
- if (request.seed !== undefined) input.seed = request.seed;
- if (request.images !== undefined) input.image_urls = await urls(request.images, resolve);
- if (request.audioIds !== undefined) input.audio_ids = [...request.audioIds];
- if (request.characterIds !== undefined) input.character_ids = [...request.characterIds];
- if (request.videos !== undefined) {
- input.video_list = await Promise.all(request.videos.map(async (video) => ({
- url: await resolve(video.artifact),
- start: video.startSec,
- ends: video.endSec,
- })));
- }
- return {
- model: "gemini-omni-video",
- input: canonicalize(input),
- result: "video",
- };
- },
-);
-
-const grokAdapters = (["text", "image", "preview-1.5"] as const).map((mode) => adapter(
- `grok-imagine.${mode}`,
- grokImagineEndpoints[mode]!,
- "video",
- (value) => verifyGrokImagineRequest(value, mode),
- async (value, resolve) => {
- verifyGrokImagineRequest(value, mode);
- const request = value as GrokImagineRequest;
- const preview = request.mode === "preview-1.5";
- const input: Record<string, CanonicalValue> = {
- prompt: request.prompt,
- aspect_ratio: request.aspectRatio,
- resolution: request.resolution,
- duration: preview ? request.durationSec : String(request.durationSec),
- };
- if (!preview) input.mode = "normal";
- if (request.mode === "image") {
- input.image_urls = await urls(request.images, resolve);
- if (request.sourceTaskId !== undefined) input.task_id = request.sourceTaskId;
- } else if (request.mode === "preview-1.5" && request.images !== undefined) {
- input.image_urls = await urls(request.images, resolve);
- }
- return {
- model: request.mode === "text" ? "grok-imagine/text-to-video"
- : request.mode === "image" ? "grok-imagine/image-to-video" : "grok-imagine-video-1-5-preview",
- input: canonicalize(input),
- result: "video",
- };
- },
-));
-
-const gptImageAdapters = (["text", "image"] as const).map((mode) => adapter(
- `gpt-image-2.${mode}`,
- gptImageEndpoints[mode]!,
- "image",
- (value) => verifyGptImage2Request(value, mode),
- async (value, resolve) => {
- verifyGptImage2Request(value, mode);
- const request = value as GptImage2Request;
- const input: Record<string, CanonicalValue> = {
- prompt: request.prompt,
- aspect_ratio: request.aspectRatio,
- };
- if (request.mode === "image") input.input_urls = await urls(request.images, resolve);
- return {
- model: request.mode === "text" ? "gpt-image-2-text-to-image" : "gpt-image-2-image-to-image",
- input: canonicalize(input),
- result: "image",
- };
- },
-));
-
-const nanoAdapters = (["v2", "pro"] as const).map((key) => adapter(
- `nano-banana.${key}`,
- nanoBananaEndpoints[key]!,
- "image",
- (value) => verifyNanoBananaRequest(value, key === "v2" ? "nano-banana-2" : "nano-banana-pro"),
- async (value, resolve) => {
- const model = key === "v2" ? "nano-banana-2" : "nano-banana-pro";
- verifyNanoBananaRequest(value, model);
- const request = value as NanoBananaRequest;
- return {
- model,
- result: "image",
- input: canonicalize({
- prompt: request.prompt,
- image_input: await urls(request.images, resolve),
- aspect_ratio: request.aspectRatio,
- resolution: request.resolution,
- output_format: request.outputFormat,
- }),
- };
- },
-));
-
-const seedreamAdapters = (["text", "image"] as const).map((mode) => adapter(
- `seedream.${mode}`,
- seedreamEndpoints[mode]!,
- "image",
- (value) => verifySeedreamRequest(value, mode),
- async (value, resolve) => {
- verifySeedreamRequest(value, mode);
- const request = value as SeedreamRequest;
- const input: Record<string, CanonicalValue> = {
- prompt: request.prompt,
- aspect_ratio: request.aspectRatio,
- quality: request.quality,
- output_format: request.outputFormat,
- nsfw_checker: request.nsfwCheck,
- };
- if (request.mode === "image") input.image_urls = await urls(request.images, resolve);
- return {
- model: request.mode === "text" ? "seedream/5-lite-text-to-image" : "seedream/5-lite-image-to-image",
- input: canonicalize(input),
- result: "image",
- };
- },
-));
-
-export const kieModelCatalog: readonly KieModelAdapter[] = [
- ...seedanceAdapters,
- ...minimaxAdapters,
- geminiAdapter,
- ...grokAdapters,
- ...gptImageAdapters,
- ...nanoAdapters,
- ...seedreamAdapters,
-];
-
-const catalogByCapability = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));
-
-export function kieAdapterForCapability(capability: CapabilityRef): KieModelAdapter | undefined {
- return catalogByCapability.get(capabilityKey(capability));
-}
-
-export function verifyKieModelCatalog(): void {
- if (catalogByCapability.size !== kieModelCatalog.length) throw new Error("KIE model catalog repeats a capability");
- kieModelCatalog.forEach((item) => {
- if (item.key.trim().length === 0) throw new Error("KIE model catalog contains an empty key");
- });
-}
diff --git a/packages/provider-kie/src/index.ts b/packages/provider-kie/src/index.ts
index f90ce7c9..0dae990a 100644
--- a/packages/provider-kie/src/index.ts
+++ b/packages/provider-kie/src/index.ts
@@ -1,13 +1,8 @@
export {
- kieAdapterForCapability,
+ kieMappingForCapability,
kieModelCatalog,
verifyKieModelCatalog,
-} from "./catalog.js";
-export type {
- KieArtifactUrlResolver,
- KieModelAdapter,
- KieTask,
-} from "./catalog.js";
+} from "./mapping.js";
export {
createKieProvider,
kieProviderImplementationDigest,
diff --git a/packages/provider-kie/src/mapping.ts b/packages/provider-kie/src/mapping.ts
new file mode 100644
index 00000000..8e2610fe
--- /dev/null
+++ b/packages/provider-kie/src/mapping.ts
@@ -0,0 +1,210 @@
+import type { CapabilityRef, ModuleRef } from "@narratage/protocol";
+import type { GenerationWireMapping } from "@narratage/generation";
+
+/**
+ * How KIE names each model's declared input ports.
+ *
+ * This file contains data only. It references Capabilities by module and model
+ * name, so this Provider package imports no model package: a model owns what it
+ * accepts, and KIE owns what it calls that on its wire. Splitting one model
+ * across several KIE endpoints is a KIE fact and lives in `routes`.
+ */
+
+/** Model packages this KIE release is written against. A version bump is a mapping review. */
+const MODEL_VERSION = "0.0.0-dev";
+
+const SEEDANCE: ModuleRef = { name: "@narratage/seedance", version: MODEL_VERSION };
+const MINIMAX: ModuleRef = { name: "@narratage/minimax-h3", version: MODEL_VERSION };
+const GEMINI: ModuleRef = { name: "@narratage/gemini-omni", version: MODEL_VERSION };
+const GROK: ModuleRef = { name: "@narratage/grok-imagine", version: MODEL_VERSION };
+const GPT_IMAGE: ModuleRef = { name: "@narratage/gpt-image", version: MODEL_VERSION };
+const NANO_BANANA: ModuleRef = { name: "@narratage/nano-banana", version: MODEL_VERSION };
+const SEEDREAM: ModuleRef = { name: "@narratage/seedream", version: MODEL_VERSION };
+
+/** KIE keeps each reference modality in its own array, as its schema documents. */
+const referenceFields = {
+ referenceImage: { as: "urlArray", field: "reference_image_urls" },
+ referenceVideo: { as: "urlArray", field: "reference_video_urls" },
+ referenceAudio: { as: "urlArray", field: "reference_audio_urls" },
+} as const;
+
+function seedanceMapping(model: string, kieModel: string): GenerationWireMapping {
+ return {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: SEEDANCE, name: model },
+ result: "video",
+ routes: [{ model: kieModel }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ ...referenceFields,
+ firstFrame: { as: "url", field: "first_frame_url" },
+ lastFrame: { as: "url", field: "last_frame_url" },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ duration: { as: "value", field: "duration" },
+ generateAudio: { as: "value", field: "generate_audio" },
+ webSearch: { as: "value", field: "web_search" },
+ },
+ };
+}
+
+const minimaxMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: MINIMAX, name: "minimax-h3" },
+ result: "video",
+ routes: [
+ { model: "minimax-h3/image-to-video", whenPresent: ["firstFrame"] },
+ { model: "minimax-h3/reference-to-video", whenPresent: ["referenceImage"] },
+ { model: "minimax-h3/reference-to-video", whenPresent: ["referenceVideo"] },
+ { model: "minimax-h3/text-to-video" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "value", field: "duration" },
+ resolution: { as: "value", field: "resolution" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ ...referenceFields,
+ firstFrame: { as: "url", field: "first_frame_url" },
+ lastFrame: { as: "url", field: "last_frame_url" },
+ },
+};
+
+const geminiMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: GEMINI, name: "gemini-omni-video" },
+ result: "video",
+ routes: [{ model: "gemini-omni-video" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ duration: { as: "string", field: "duration" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ seed: { as: "value", field: "seed" },
+ images: { as: "urlArray", field: "image_urls" },
+ audioIds: { as: "valueArray", field: "audio_ids" },
+ characterIds: { as: "valueArray", field: "character_ids" },
+ excerpts: {
+ as: "itemObject",
+ field: "video_list",
+ urlKey: "url",
+ fieldKeys: { startSec: "start", endSec: "ends" },
+ },
+ },
+};
+
+const grokVideoMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: GROK, name: "grok-imagine-video" },
+ result: "video",
+ routes: [
+ { model: "grok-imagine/image-to-video", whenPresent: ["images"] },
+ { model: "grok-imagine/text-to-video" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ duration: { as: "string", field: "duration" },
+ images: { as: "urlArray", field: "image_urls" },
+ sourceTaskId: { as: "value", field: "task_id" },
+ },
+ constants: { mode: "normal" },
+};
+
+const grokPreviewMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: GROK, name: "grok-imagine-video-1.5-preview" },
+ result: "video",
+ routes: [{ model: "grok-imagine-video-1-5-preview" }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ duration: { as: "value", field: "duration" },
+ images: { as: "urlArray", field: "image_urls" },
+ },
+};
+
+const gptImageMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: GPT_IMAGE, name: "gpt-image-2" },
+ result: "image",
+ routes: [
+ { model: "gpt-image-2-image-to-image", whenPresent: ["images"] },
+ { model: "gpt-image-2-text-to-image" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ images: { as: "urlArray", field: "input_urls" },
+ },
+};
+
+function nanoBananaMapping(model: string): GenerationWireMapping {
+ return {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: NANO_BANANA, name: model },
+ result: "image",
+ routes: [{ model }],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ /** KIE expects the key even with no input image. */
+ images: { as: "urlArray", field: "image_input", whenAbsent: [] },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ resolution: { as: "value", field: "resolution" },
+ outputFormat: { as: "value", field: "output_format" },
+ },
+ };
+}
+
+const seedreamMapping: GenerationWireMapping = {
+ contract: "svml.generation-wire-mapping@1",
+ capability: { module: SEEDREAM, name: "seedream-5-lite" },
+ result: "image",
+ routes: [
+ { model: "seedream/5-lite-image-to-image", whenPresent: ["images"] },
+ { model: "seedream/5-lite-text-to-image" },
+ ],
+ fields: {
+ prompt: { as: "value", field: "prompt" },
+ aspectRatio: { as: "value", field: "aspect_ratio" },
+ quality: { as: "value", field: "quality" },
+ outputFormat: { as: "value", field: "output_format" },
+ nsfwCheck: { as: "value", field: "nsfw_checker" },
+ images: { as: "urlArray", field: "image_urls" },
+ },
+};
+
+export const kieModelCatalog: readonly GenerationWireMapping[] = [
+ seedanceMapping("seedance-2", "bytedance/seedance-2"),
+ seedanceMapping("seedance-2-fast", "bytedance/seedance-2-fast"),
+ seedanceMapping("seedance-2-mini", "bytedance/seedance-2-mini"),
+ minimaxMapping,
+ geminiMapping,
+ grokVideoMapping,
+ grokPreviewMapping,
+ gptImageMapping,
+ nanoBananaMapping("nano-banana-2"),
+ nanoBananaMapping("nano-banana-pro"),
+ seedreamMapping,
+];
+
+function capabilityKey(ref: CapabilityRef): string {
+ return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+const catalogByCapability = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));
+
+export function kieMappingForCapability(capability: CapabilityRef): GenerationWireMapping | undefined {
+ return catalogByCapability.get(capabilityKey(capability));
+}
+
+export function verifyKieModelCatalog(): void {
+ if (catalogByCapability.size !== kieModelCatalog.length) {
+ throw new Error("KIE model catalog repeats a capability");
+ }
+ kieModelCatalog.forEach((item) => {
+ if (item.capability.name.trim().length === 0) throw new Error("KIE model catalog contains an empty model");
+ });
+}
diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.ts
index 29575662..41ea2e4b 100644
--- a/packages/provider-kie/src/provider.ts
+++ b/packages/provider-kie/src/provider.ts
@@ -5,9 +5,17 @@ import type {
EndpointOutcome,
} from "@narratage/endpoint-kit";
import {
+ compileWireRequest,
+ generationTypes,
+ mappingSupportsRequest,
sealGeneratedImageSet,
sealGeneratedVideoSet,
} from "@narratage/generation";
+import type {
+ GenerationArtifactUrlResolver,
+ GenerationRequest,
+ GenerationWireRequest,
+} from "@narratage/generation";
import {
canonicalize,
digestOf,
@@ -26,15 +34,10 @@ import { credentialRef } from "@narratage/runtime";
import type { ArtifactStore, CredentialRef } from "@narratage/runtime";
import {
- kieAdapterForCapability,
+ kieMappingForCapability,
kieModelCatalog,
verifyKieModelCatalog,
-} from "./catalog.js";
-import type {
- KieArtifactUrlResolver,
- KieModelAdapter,
- KieTask,
-} from "./catalog.js";
+} from "./mapping.js";
export const kieProviderModuleRef = { name: "@narratage/provider-kie", version: "0.0.0-dev" } as const;
export const kieProviderImplementationDigest = digestOf("@narratage/provider-kie/market-endpoint@1");
@@ -245,7 +248,7 @@ class KieClient {
return url;
}
- async createTask(task: KieTask, apiKey: string): Promise<string> {
+ async createTask(task: GenerationWireRequest, apiKey: string): Promise<string> {
let response: Record<string, unknown>;
try {
response = await this.#json(`${this.#options.apiBaseUrl}/api/v1/jobs/createTask`, {
@@ -374,11 +377,11 @@ function verifyCheckpoint(value: CanonicalValue | undefined, context: EndpointRe
);
}
const checkpoint = object(value, "KIE checkpoint") as unknown as KieCheckpoint;
- const adapter = kieAdapterForCapability(context.need.capability);
+ const mapping = kieMappingForCapability(context.need.capability);
if (checkpoint.contract !== "svml.kie-operation@1"
|| typeof checkpoint.taskId !== "string"
- || adapter === undefined
- || checkpoint.catalogKey !== adapter.key
+ || mapping === undefined
+ || checkpoint.catalogKey !== mapping.capability.name
|| checkpoint.requestDigest !== context.need.requestDigest
|| !isDigest(checkpoint.contentRequestDigest)
|| !Number.isSafeInteger(checkpoint.startedAt)
@@ -419,27 +422,30 @@ function endpoint(options: {
return {
async start(context) {
try {
- const adapter = kieAdapterForCapability(context.need.capability);
- if (adapter === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");
- adapter.verify(context.need.constraints);
+ const mapping = kieMappingForCapability(context.need.capability);
+ if (mapping === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");
const key = secret(context);
const uploaded = new Map<Digest, Promise<string>>();
- const resolve: KieArtifactUrlResolver = (artifact) => {
+ const resolve: GenerationArtifactUrlResolver = (artifact) => {
const existing = uploaded.get(artifact.digest);
if (existing !== undefined) return existing;
const promise = options.client.upload(artifact, context.artifacts, key);
uploaded.set(artifact.digest, promise);
return promise;
};
- const task = await adapter.task(context.need.constraints, resolve);
+ const task = await compileWireRequest(
+ mapping,
+ context.need.constraints as unknown as GenerationRequest,
+ resolve,
+ );
await options.gate.enter();
const taskId = await options.client.createTask(task, key);
const checkpoint: KieCheckpoint = {
contract: "svml.kie-operation@1",
taskId,
- catalogKey: adapter.key,
+ catalogKey: mapping.capability.name,
model: task.model,
- result: task.result,
+ result: mapping.result,
requestDigest: context.need.requestDigest,
contentRequestDigest: contentRequestDigest(context.need.constraints),
startedAt: options.now(),
@@ -459,11 +465,10 @@ function endpoint(options: {
return failure(error);
}
try {
- const adapter = kieAdapterForCapability(context.need.capability);
- if (adapter === undefined || adapter.key !== checkpoint.catalogKey) {
+ const mapping = kieMappingForCapability(context.need.capability);
+ if (mapping === undefined || mapping.capability.name !== checkpoint.catalogKey) {
throw new KieError("KIE_CHECKPOINT_INVALID", "KIE checkpoint capability differs");
}
- adapter.verify(context.need.constraints);
if (contentRequestDigest(context.need.constraints) !== checkpoint.contentRequestDigest) {
throw new KieError("KIE_CHECKPOINT_INVALID", "KIE checkpoint request content differs");
}
@@ -604,18 +609,12 @@ export function createKieProvider(config: CreateKieProviderOptions = {}) {
defaultConcurrency: config.defaultConcurrency ?? 2,
capabilities: kieModelCatalog.map((item) => ({
capability: item.capability,
- returns: item.returns,
+ returns: item.result === "image" ? generationTypes.imageSet : generationTypes.videoSet,
lifecycle: "recoverable" as const,
endpoint: providerEndpoint,
retry: { maxAttempts: 3 },
- supports: (need) => {
- try {
- item.verify(need.constraints);
- return true;
- } catch {
- return false;
- }
- },
+ /** Model semantics were already admitted by Core; KIE only checks it can write every port. */
+ supports: (need) => mappingSupportsRequest(item, need.constraints),
})),
});
}
diff --git a/packages/provider-kie/test/live-smoke.ts b/packages/provider-kie/test/live-smoke.ts
index d9937bb1..7a8e8631 100644
--- a/packages/provider-kie/test/live-smoke.ts
+++ b/packages/provider-kie/test/live-smoke.ts
@@ -194,15 +194,12 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
{
key: "gpt-image-2",
media: "image",
- endpoint: endpoint(gptImageEndpoints.text, "GPT Image 2 text"),
+ endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2"),
manifest: gptImageManifest,
component: gptImageComponent,
request: sealGptImage2Request({
- contract: "svml.gpt-image-2-request@1",
- model: "gpt-image-2",
- mode: "text",
- prompt: productPrompt,
- aspectRatio: "1:1",
+ prompt: [productPrompt],
+ aspectRatio: ["1:1"],
}) as unknown as CanonicalValue,
},
{
@@ -211,30 +208,25 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
endpoint: endpoint(nanoBananaEndpoints.v2, "Nano Banana 2"),
manifest: nanoBananaManifest,
component: nanoBananaComponent,
- request: sealNanoBananaRequest({
- contract: "svml.nano-banana-request@1",
- model: "nano-banana-2",
- prompt: productPrompt,
- aspectRatio: "1:1",
- resolution: "1K",
- outputFormat: "png",
+ request: sealNanoBananaRequest("nano-banana-2", {
+ prompt: [productPrompt],
+ aspectRatio: ["1:1"],
+ resolution: ["1K"],
+ outputFormat: ["png"],
}) as unknown as CanonicalValue,
},
{
key: "seedream-5-lite",
media: "image",
- endpoint: endpoint(seedreamEndpoints.text, "Seedream 5 Lite text"),
+ endpoint: endpoint(seedreamEndpoints.image, "Seedream 5 Lite"),
manifest: seedreamManifest,
component: seedreamComponent,
request: sealSeedreamRequest({
- contract: "svml.seedream-5-lite-request@1",
- model: "seedream-5-lite",
- mode: "text",
- prompt: productPrompt,
- aspectRatio: "1:1",
- quality: "basic",
- outputFormat: "png",
- nsfwCheck: true,
+ prompt: [productPrompt],
+ aspectRatio: ["1:1"],
+ quality: ["basic"],
+ outputFormat: ["png"],
+ nsfwCheck: [true],
}) as unknown as CanonicalValue,
},
{
@@ -243,31 +235,25 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
endpoint: endpoint(seedanceEndpoints.mini, "Seedance 2 Mini"),
manifest: seedanceManifest,
component: seedanceComponent,
- request: sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: "seedance-2-mini",
- mode: { kind: "text" },
- prompt: motionPrompt,
- resolution: "480p",
- aspectRatio: "1:1",
- durationSec: 4,
- generateAudio: false,
- webSearch: false,
+ request: sealSeedanceRequest("seedance-2-mini", {
+ prompt: [motionPrompt],
+ resolution: ["480p"],
+ aspectRatio: ["1:1"],
+ duration: [4],
+ generateAudio: [false],
+ webSearch: [false],
}) as unknown as CanonicalValue,
},
{
key: "minimax-h3",
media: "video",
- endpoint: endpoint(minimaxH3Endpoints.text, "MiniMax H3 text"),
+ endpoint: endpoint(minimaxH3Endpoints.video, "MiniMax H3"),
manifest: minimaxH3Manifest,
component: minimaxH3Component,
request: sealMinimaxH3Request({
- contract: "svml.minimax-h3-request@1",
- model: "minimax-h3",
- mode: "text",
- prompt: motionPrompt,
- durationSec: 6,
- aspectRatio: "16:9",
+ prompt: [motionPrompt],
+ duration: [6],
+ aspectRatio: ["16:9"],
}) as unknown as CanonicalValue,
},
{
@@ -277,28 +263,23 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
manifest: geminiOmniManifest,
component: geminiOmniComponent,
request: sealGeminiOmniRequest({
- contract: "svml.gemini-omni-request@1",
- model: "gemini-omni-video",
- prompt: motionPrompt,
- durationSec: 4,
- aspectRatio: "16:9",
- resolution: "720p",
+ prompt: [motionPrompt],
+ duration: [4],
+ aspectRatio: ["16:9"],
+ resolution: ["720p"],
}) as unknown as CanonicalValue,
},
{
key: "grok-imagine",
media: "video",
- endpoint: endpoint(grokImagineEndpoints.text, "Grok Imagine text"),
+ endpoint: endpoint(grokImagineEndpoints.video, "Grok Imagine"),
manifest: grokImagineManifest,
component: grokImagineComponent,
- request: sealGrokImagineRequest({
- contract: "svml.grok-imagine-video-request@1",
- model: "grok-imagine-video",
- mode: "text",
- prompt: motionPrompt,
- aspectRatio: "2:3",
- resolution: "480p",
- durationSec: 6,
+ request: sealGrokImagineRequest("grok-imagine-video", {
+ prompt: [motionPrompt],
+ aspectRatio: ["2:3"],
+ resolution: ["480p"],
+ duration: [6],
}) as unknown as CanonicalValue,
},
];
@@ -310,16 +291,13 @@ async function smokeCases(root: string): Promise<readonly SmokeCase[]> {
cases.push({
key: "gpt-image-2-edit",
media: "image",
- endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2 image"),
+ endpoint: endpoint(gptImageEndpoints.image, "GPT Image 2 edit"),
manifest: gptImageManifest,
component: gptImageComponent,
request: sealGptImage2Request({
- contract: "svml.gpt-image-2-request@1",
- model: "gpt-image-2",
- mode: "image",
- prompt: "Keep the glass sphere unchanged and replace the blue background with a matte warm orange studio background, no text.",
- aspectRatio: "1:1",
- images: [reference],
+ prompt: ["Keep the glass sphere unchanged and replace the blue background with a matte warm orange studio background, no text."],
+ aspectRatio: ["1:1"],
+ images: [{ role: "image", artifact: reference }],
}) as unknown as CanonicalValue,
});
}
diff --git a/packages/provider-kie/test/models.test.ts b/packages/provider-kie/test/models.test.ts
index 50498e36..4469aa1f 100644
--- a/packages/provider-kie/test/models.test.ts
+++ b/packages/provider-kie/test/models.test.ts
@@ -11,22 +11,101 @@ import {
sealGeminiOmniRequest,
} from "@narratage/gemini-omni";
import { MemoryArtifactStore } from "@narratage/driver-node";
-import { generationManifest } from "@narratage/generation";
-import { gptImageDefinition, gptImageManifest, sealGptImage2Request } from "@narratage/gpt-image";
-import { grokImagineDefinition, grokImagineManifest, sealGrokImagineRequest } from "@narratage/grok-imagine";
-import { minimaxH3Definition, minimaxH3Manifest, sealMinimaxH3Request } from "@narratage/minimax-h3";
-import { nanoBananaDefinition, nanoBananaManifest, sealNanoBananaRequest } from "@narratage/nano-banana";
+import {
+ assertMappingCoversPorts,
+ compileWireRequest,
+ generationManifest,
+} from "@narratage/generation";
+import type { GenerationPortTable } from "@narratage/generation";
+import {
+ gptImageDefinition,
+ gptImageManifest,
+ sealGptImage2Request,
+} from "@narratage/gpt-image";
+import {
+ grokImagineDefinition,
+ grokImagineManifest,
+ sealGrokImagineRequest,
+} from "@narratage/grok-imagine";
+import {
+ minimaxH3Definition,
+ minimaxH3Manifest,
+ sealMinimaxH3Request,
+} from "@narratage/minimax-h3";
+import {
+ nanoBananaDefinition,
+ nanoBananaManifest,
+ sealNanoBananaRequest,
+} from "@narratage/nano-banana";
import { kieModelCatalog } from "@narratage/provider-kie";
-import { seedanceDefinition, seedanceManifest, sealSeedanceRequest } from "@narratage/seedance";
-import { seedreamDefinition, seedreamManifest, sealSeedreamRequest } from "@narratage/seedream";
-import type { LinkedProgram } from "@narratage/protocol";
+import { seedanceDefinition, seedanceManifest, seedancePorts, sealSeedanceRequest } from "@narratage/seedance";
+import {
+ seedreamDefinition,
+ seedreamManifest,
+ sealSeedreamRequest,
+} from "@narratage/seedream";
+import type { CapabilityRef, LinkedProgram } from "@narratage/protocol";
+
+/**
+ * Every exact model this repository ships, paired with the Capability it publishes.
+ * The Capability carries the module version, so a mapping written for an older model
+ * version fails here rather than at submission time.
+ */
+const modelCapabilities: readonly { readonly ports: GenerationPortTable; readonly capability: CapabilityRef }[] = [
+ seedanceDefinition, minimaxH3Definition, geminiOmniDefinition, grokImagineDefinition,
+ gptImageDefinition, nanoBananaDefinition, seedreamDefinition,
+].flatMap((definition) => Object.values(definition.endpoints)
+ .map((endpoint) => ({ ports: endpoint.ports, capability: endpoint.capability })));
+
+function capabilityKey(ref: CapabilityRef): string {
+ return `${ref.module.name}@${ref.module.version}#${ref.name}`;
+}
+
+const upload = async (artifact: { readonly digest: string }) => `https://upload.test/${artifact.digest}`;
test("the selected KIE release is seven exact model families and no Grok image capability", () => {
- assert.equal(kieModelCatalog.length, 16);
- assert.equal(kieModelCatalog.some((item) => item.key.startsWith("grok-imagine.") && item.result === "image"), false);
+ assert.equal(kieModelCatalog.length, 11);
+ assert.equal(
+ kieModelCatalog.some((item) => item.capability.name.startsWith("grok-") && item.result === "image"),
+ false,
+ );
assert.deepEqual(
- [...new Set(kieModelCatalog.map((item) => item.key.split(".", 1)[0]))].sort(),
- ["gemini-omni", "gpt-image-2", "grok-imagine", "minimax-h3", "nano-banana", "seedance", "seedream"],
+ [...new Set(kieModelCatalog.map((item) => item.capability.module.name))].sort(),
+ [
+ "@narratage/gemini-omni",
+ "@narratage/gpt-image",
+ "@narratage/grok-imagine",
+ "@narratage/minimax-h3",
+ "@narratage/nano-banana",
+ "@narratage/seedance",
+ "@narratage/seedream",
+ ],
+ );
+});
+
+/**
+ * The check the old hand-written translators could not perform. Forgetting a
+ * reference role or an item field used to surface only after paid generation
+ * returned the wrong result; it now fails here.
+ */
+test("the KIE mapping covers every port every exact model declares", () => {
+ assert.equal(modelCapabilities.length, kieModelCatalog.length);
+ const mappings = new Map(kieModelCatalog.map((item) => [capabilityKey(item.capability), item]));
+ for (const { ports, capability } of modelCapabilities) {
+ // Matched on the full Capability, version included: a stale mapping cannot pass by name alone.
+ const mapping = mappings.get(capabilityKey(capability));
+ assert.ok(mapping, `KIE declares no mapping for ${capabilityKey(capability)}`);
+ assertMappingCoversPorts(ports, mapping);
+ }
+});
+
+test("dropping one reference modality from a mapping fails coverage before any spend", () => {
+ const seedance = kieModelCatalog.find((item) => item.capability.name === "seedance-2-mini");
+ assert.ok(seedance);
+ const { referenceAudio: _dropped, ...withoutAudio } = seedance.fields;
+ assert.throws(
+ () => assertMappingCoversPorts(seedancePorts["seedance-2-mini"], { ...seedance, fields: withoutAudio }),
+ /does not cover port referenceAudio/u,
);
});
@@ -67,33 +146,33 @@ test("Gemini Omni enforces the weighted seven-unit reference quota", async () =>
const image = await artifacts.put(new Uint8Array([1]), "image/png");
const video = await artifacts.put(new Uint8Array([2]), "video/mp4");
assert.throws(() => sealGeminiOmniRequest({
- contract: "svml.gemini-omni-request@1",
- model: "gemini-omni-video",
- prompt: "Use every reference.",
- durationSec: 4,
- aspectRatio: "16:9",
- resolution: "720p",
- images: [image, image, image],
- videos: [{ artifact: video, startSec: 0, endSec: 1 }],
+ prompt: ["Use every reference."],
+ duration: [4],
+ aspectRatio: ["16:9"],
+ resolution: ["720p"],
+ images: [
+ { role: "image", artifact: image },
+ { role: "image", artifact: image },
+ { role: "image", artifact: image },
+ ],
+ excerpts: [{ role: "video", artifact: video, fields: { startSec: 0, endSec: 1 } }],
characterIds: ["a", "b", "c"],
- }), /quota is 8/u);
+ }), /uses 8 of its 7 shared/u);
});
test("Gemini Omni binds its documented output controls into the KIE request", async () => {
const request = sealGeminiOmniRequest({
- contract: "svml.gemini-omni-request@1",
- model: "gemini-omni-video",
- prompt: "A glass sphere rolls across a blue floor.",
- durationSec: 4,
- aspectRatio: "16:9",
- resolution: "720p",
- seed: 42,
+ prompt: ["A glass sphere rolls across a blue floor."],
+ duration: [4],
+ aspectRatio: ["16:9"],
+ resolution: ["720p"],
+ seed: [42],
});
- const adapter = kieModelCatalog.find((item) => item.key === "gemini-omni.video");
- assert.ok(adapter);
- const task = await adapter.task(request, async () => "https://upload.test/reference");
+ const mapping = kieModelCatalog.find((item) => item.capability.name === "gemini-omni-video");
+ assert.ok(mapping);
+ const task = await compileWireRequest(mapping, request, upload);
assert.deepEqual(task.input, {
- prompt: request.prompt,
+ prompt: "A glass sphere rolls across a blue floor.",
duration: "4",
aspect_ratio: "16:9",
resolution: "720p",
@@ -102,137 +181,143 @@ test("Gemini Omni binds its documented output controls into the KIE request", as
});
test("Seedream safety policy is explicit author content and contributes to request identity", () => {
- const unchecked = sealSeedreamRequest({
- contract: "svml.seedream-5-lite-request@1",
- model: "seedream-5-lite",
- mode: "text",
- prompt: "A fashion editorial.",
- aspectRatio: "3:4",
- quality: "basic",
- outputFormat: "png",
- nsfwCheck: false,
- });
- const checked = sealSeedreamRequest({
- contract: "svml.seedream-5-lite-request@1",
- model: "seedream-5-lite",
- mode: "text",
- prompt: "A fashion editorial.",
- aspectRatio: "3:4",
- quality: "basic",
- outputFormat: "png",
- nsfwCheck: true,
- });
- assert.equal(unchecked.nsfwCheck, false);
+ const base = {
+ prompt: ["A fashion editorial."],
+ aspectRatio: ["3:4"],
+ quality: ["basic"],
+ outputFormat: ["png"],
+ };
+ const unchecked = sealSeedreamRequest({ ...base, nsfwCheck: [false] });
+ const checked = sealSeedreamRequest({ ...base, nsfwCheck: [true] });
+ assert.deepEqual(unchecked.ports.nsfwCheck, [false]);
assert.notEqual(digestOf(unchecked), digestOf(checked));
});
-test("all sixteen exact capabilities translate to their documented KIE model slug", async () => {
+test("all eleven exact capabilities route to their documented KIE model slug", async () => {
const store = new MemoryArtifactStore();
const image = await store.put(new Uint8Array([1]), "image/png");
const video = await store.put(new Uint8Array([2]), "video/mp4");
const audio = await store.put(new Uint8Array([3]), "audio/wav");
- const seedance = (model: "seedance-2" | "seedance-2-fast" | "seedance-2-mini") => sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model,
- prompt: "A studio shot.",
- mode: { kind: "text" },
- resolution: model === "seedance-2" ? "1080p" : "720p",
- aspectRatio: "16:9",
- durationSec: 5,
- generateAudio: false,
- webSearch: false,
+ const seedance = (model: "seedance-2" | "seedance-2-fast" | "seedance-2-mini") => sealSeedanceRequest(model, {
+ prompt: ["A studio shot."],
+ resolution: [model === "seedance-2" ? "1080p" : "720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
});
- const commonH3 = {
- contract: "svml.minimax-h3-request@1" as const,
- model: "minimax-h3" as const,
- prompt: "A studio shot.",
- durationSec: 6,
- };
const commonGrok = {
- contract: "svml.grok-imagine-video-request@1" as const,
- prompt: "A studio shot.",
- aspectRatio: "16:9",
- resolution: "480p" as const,
- durationSec: 6,
- };
- const commonGpt = {
- contract: "svml.gpt-image-2-request@1" as const,
- model: "gpt-image-2" as const,
- prompt: "A studio portrait.",
- aspectRatio: "auto",
- };
+ prompt: ["A studio shot."],
+ aspectRatio: ["16:9"],
+ resolution: ["480p"],
+ duration: [6],
+ } as const;
const commonSeedream = {
- contract: "svml.seedream-5-lite-request@1" as const,
- model: "seedream-5-lite" as const,
- prompt: "A studio portrait.",
- aspectRatio: "1:1",
- quality: "basic" as const,
- outputFormat: "png" as const,
- nsfwCheck: true,
+ prompt: ["A studio portrait."],
+ aspectRatio: ["1:1"],
+ quality: ["basic"],
+ outputFormat: ["png"],
+ nsfwCheck: [true],
};
const cases = [
- ["seedance.standard", seedance("seedance-2"), "bytedance/seedance-2"],
- ["seedance.fast", seedance("seedance-2-fast"), "bytedance/seedance-2-fast"],
- ["seedance.mini", seedance("seedance-2-mini"), "bytedance/seedance-2-mini"],
- ["minimax-h3.text", sealMinimaxH3Request({ ...commonH3, mode: "text", aspectRatio: "16:9" }), "minimax-h3/text-to-video"],
- ["minimax-h3.frames", sealMinimaxH3Request({ ...commonH3, mode: "frames", firstFrame: image }), "minimax-h3/image-to-video"],
- ["minimax-h3.reference", sealMinimaxH3Request({
- ...commonH3,
- mode: "reference",
- aspectRatio: "adaptive",
- references: [
- { kind: "image", artifact: image },
- { kind: "video", artifact: video },
- { kind: "audio", artifact: audio },
- ],
+ ["seedance-2", seedance("seedance-2"), "bytedance/seedance-2"],
+ ["seedance-2-fast", seedance("seedance-2-fast"), "bytedance/seedance-2-fast"],
+ ["seedance-2-mini", seedance("seedance-2-mini"), "bytedance/seedance-2-mini"],
+ ["minimax-h3", sealMinimaxH3Request({
+ prompt: ["A studio shot."],
+ duration: [6],
+ aspectRatio: ["16:9"],
+ }), "minimax-h3/text-to-video"],
+ ["minimax-h3", sealMinimaxH3Request({
+ prompt: ["A studio shot."],
+ duration: [6],
+ firstFrame: [{ role: "image", artifact: image }],
+ }), "minimax-h3/image-to-video"],
+ ["minimax-h3", sealMinimaxH3Request({
+ prompt: ["A studio shot."],
+ duration: [6],
+ referenceImage: [{ role: "image", artifact: image }],
+ referenceVideo: [{ role: "video", artifact: video }],
+ referenceAudio: [{ role: "audio", artifact: audio }],
}), "minimax-h3/reference-to-video"],
- ["gemini-omni.video", sealGeminiOmniRequest({
- contract: "svml.gemini-omni-request@1",
- model: "gemini-omni-video",
- prompt: "A studio shot.",
- durationSec: 4,
- aspectRatio: "16:9",
- resolution: "720p",
- images: [image],
+ ["gemini-omni-video", sealGeminiOmniRequest({
+ prompt: ["A studio shot."],
+ duration: [4],
+ aspectRatio: ["16:9"],
+ resolution: ["720p"],
+ images: [{ role: "image", artifact: image }],
}), "gemini-omni-video"],
- ["grok-imagine.text", sealGrokImagineRequest({ ...commonGrok, model: "grok-imagine-video", mode: "text" }), "grok-imagine/text-to-video"],
- ["grok-imagine.image", sealGrokImagineRequest({
+ ["grok-imagine-video", sealGrokImagineRequest("grok-imagine-video", commonGrok), "grok-imagine/text-to-video"],
+ ["grok-imagine-video", sealGrokImagineRequest("grok-imagine-video", {
...commonGrok,
- model: "grok-imagine-video",
- mode: "image",
- images: [image],
+ images: [{ role: "image", artifact: image }],
}), "grok-imagine/image-to-video"],
- ["grok-imagine.preview-1.5", sealGrokImagineRequest({
- ...commonGrok,
- model: "grok-imagine-video-1.5-preview",
- mode: "preview-1.5",
- }), "grok-imagine-video-1-5-preview"],
- ["gpt-image-2.text", sealGptImage2Request({ ...commonGpt, mode: "text" }), "gpt-image-2-text-to-image"],
- ["gpt-image-2.image", sealGptImage2Request({ ...commonGpt, mode: "image", images: [image] }), "gpt-image-2-image-to-image"],
- ["nano-banana.v2", sealNanoBananaRequest({
- contract: "svml.nano-banana-request@1",
- model: "nano-banana-2",
- prompt: "A studio portrait.",
- aspectRatio: "auto",
- resolution: "2K",
- outputFormat: "jpg",
+ ["grok-imagine-video-1.5-preview",
+ sealGrokImagineRequest("grok-imagine-video-1.5-preview", commonGrok),
+ "grok-imagine-video-1-5-preview"],
+ ["gpt-image-2", sealGptImage2Request({
+ prompt: ["A studio portrait."],
+ aspectRatio: ["auto"],
+ resolution: ["1K"],
+ }), "gpt-image-2-text-to-image"],
+ ["gpt-image-2", sealGptImage2Request({
+ prompt: ["A studio portrait."],
+ aspectRatio: ["auto"],
+ resolution: ["1K"],
+ images: [{ role: "image", artifact: image }],
+ }), "gpt-image-2-image-to-image"],
+ ["nano-banana-2", sealNanoBananaRequest("nano-banana-2", {
+ prompt: ["A studio portrait."],
+ aspectRatio: ["auto"],
+ resolution: ["2K"],
+ outputFormat: ["jpg"],
}), "nano-banana-2"],
- ["nano-banana.pro", sealNanoBananaRequest({
- contract: "svml.nano-banana-request@1",
- model: "nano-banana-pro",
- prompt: "A studio portrait.",
- images: [image],
- aspectRatio: "1:1",
- resolution: "1K",
- outputFormat: "png",
+ ["nano-banana-pro", sealNanoBananaRequest("nano-banana-pro", {
+ prompt: ["A studio portrait."],
+ images: [{ role: "image", artifact: image }],
+ aspectRatio: ["1:1"],
+ resolution: ["1K"],
+ outputFormat: ["png"],
}), "nano-banana-pro"],
- ["seedream.text", sealSeedreamRequest({ ...commonSeedream, mode: "text" }), "seedream/5-lite-text-to-image"],
- ["seedream.image", sealSeedreamRequest({ ...commonSeedream, mode: "image", images: [image] }), "seedream/5-lite-image-to-image"],
+ ["seedream-5-lite", sealSeedreamRequest(commonSeedream), "seedream/5-lite-text-to-image"],
+ ["seedream-5-lite", sealSeedreamRequest({
+ ...commonSeedream,
+ images: [{ role: "image", artifact: image }],
+ }), "seedream/5-lite-image-to-image"],
] as const;
- for (const [key, request, expectedModel] of cases) {
- const item = kieModelCatalog.find((candidate) => candidate.key === key);
- assert.ok(item, key);
- const task = await item.task(request, async (artifact) => `https://upload.test/${artifact.digest}`);
- assert.equal(task.model, expectedModel, key);
+ for (const [model, request, expectedModel] of cases) {
+ const mapping = kieModelCatalog.find((candidate) => candidate.capability.name === model);
+ assert.ok(mapping, model);
+ const task = await compileWireRequest(mapping, request, upload);
+ assert.equal(task.model, expectedModel, `${model} -> ${expectedModel}`);
}
});
+
+test("one model reaching a service that splits it keeps the reference roles intact", async () => {
+ const store = new MemoryArtifactStore();
+ const image = await store.put(new Uint8Array([1]), "image/png");
+ const audio = await store.put(new Uint8Array([3]), "audio/wav");
+ const request = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A presenter speaks."],
+ referenceImage: [{ role: "image", artifact: image }],
+ referenceAudio: [{ role: "audio", artifact: audio }],
+ resolution: ["720p"],
+ aspectRatio: ["9:16"],
+ duration: [5],
+ generateAudio: [true],
+ webSearch: [false],
+ });
+ const mapping = kieModelCatalog.find((item) => item.capability.name === "seedance-2-mini");
+ assert.ok(mapping);
+ const task = await compileWireRequest(mapping, request, upload);
+ assert.deepEqual(task.input, {
+ prompt: "A presenter speaks.",
+ reference_image_urls: [`https://upload.test/${image.digest}`],
+ reference_audio_urls: [`https://upload.test/${audio.digest}`],
+ resolution: "720p",
+ aspect_ratio: "9:16",
+ duration: 5,
+ generate_audio: true,
+ web_search: false,
+ });
+});
diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.ts
index 022012ea..8f2f300f 100644
--- a/packages/provider-kie/test/provider.test.ts
+++ b/packages/provider-kie/test/provider.test.ts
@@ -67,16 +67,14 @@ function operation(request: Need) {
test("KIE uploads content-addressed references, resumes one task, and persists generated bytes", async () => {
const artifacts = new MemoryArtifactStore();
const firstFrame = await artifacts.put(new Uint8Array([1, 2, 3]), "image/png");
- const requestValue = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: "seedance-2-mini",
- prompt: "A presenter turns toward camera.",
- mode: { kind: "frames", firstFrame },
- resolution: "720p",
- aspectRatio: "16:9",
- durationSec: 6,
- generateAudio: false,
- webSearch: false,
+ const requestValue = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A presenter turns toward camera."],
+ firstFrame: [{ role: "image", artifact: firstFrame }],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [6],
+ generateAudio: [false],
+ webSearch: [false],
});
const request = need(requestValue as unknown as CanonicalValue);
const calls: string[] = [];
@@ -98,7 +96,6 @@ test("KIE uploads content-addressed references, resumes one task, and persists g
assert.equal(body.model, "bytedance/seedance-2-mini");
const modelInput = body.input as Record<string, unknown>;
assert.equal(modelInput.first_frame_url, "https://tempfile.redpandaai.co/reference.png");
- assert.equal(modelInput.return_last_frame, false);
return Response.json({ code: 200, msg: "success", data: { taskId: "task_seedance_test" } });
}
if (url.includes("/api/v1/jobs/recordInfo")) {
@@ -154,16 +151,13 @@ test("KIE uploads content-addressed references, resumes one task, and persists g
});
test("KIE never retries an ambiguous paid submission", async () => {
- const requestValue = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: "seedance-2-mini",
- prompt: "A clean studio shot.",
- mode: { kind: "text" },
- resolution: "720p",
- aspectRatio: "16:9",
- durationSec: 5,
- generateAudio: false,
- webSearch: false,
+ const requestValue = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A clean studio shot."],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
});
const request = need(requestValue as unknown as CanonicalValue);
let calls = 0;
@@ -186,16 +180,13 @@ test("KIE never retries an ambiguous paid submission", async () => {
});
test("KIE preserves an HTTP-200 business rejection without calling it an ambiguous submission", async () => {
- const requestValue = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: "seedance-2-mini",
- prompt: "A clean studio shot.",
- mode: { kind: "text" },
- resolution: "720p",
- aspectRatio: "16:9",
- durationSec: 5,
- generateAudio: false,
- webSearch: false,
+ const requestValue = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A clean studio shot."],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
});
const request = need(requestValue as unknown as CanonicalValue);
let calls = 0;
@@ -219,16 +210,13 @@ test("KIE preserves an HTTP-200 business rejection without calling it an ambiguo
});
test("KIE refuses to resubmit when a recovered Operation has no task checkpoint", async () => {
- const requestValue = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: "seedance-2-mini",
- prompt: "A clean studio shot.",
- mode: { kind: "text" },
- resolution: "720p",
- aspectRatio: "16:9",
- durationSec: 5,
- generateAudio: false,
- webSearch: false,
+ const requestValue = sealSeedanceRequest("seedance-2-mini", {
+ prompt: ["A clean studio shot."],
+ resolution: ["720p"],
+ aspectRatio: ["16:9"],
+ duration: [5],
+ generateAudio: [false],
+ webSearch: [false],
});
const request = need(requestValue as unknown as CanonicalValue);
let calls = 0;
diff --git a/packages/seedance-speaker/src/kit.ts b/packages/seedance-speaker/src/kit.ts
index 92bb067c..38f65672 100644
--- a/packages/seedance-speaker/src/kit.ts
+++ b/packages/seedance-speaker/src/kit.ts
@@ -11,6 +11,8 @@ import {
} from "@narratage/seedance";
import type { SeedanceSpeechProgram } from "@narratage/seedance";
+import type { BlobRef } from "@narratage/protocol";
+
import type { SpeakerTakeIntent } from "./types.js";
export const speakerMethodDefaults = {
@@ -102,6 +104,18 @@ export function bindSpeakerPromptKit(intent: SpeakerTakeIntent): PromptKitInvoca
return invocation;
}
+/** The model keeps one port per reference modality; the Speaker groups its takes accordingly. */
+function referencePortsOf(
+ references: SpeakerTakeIntent["references"],
+): Record<string, readonly { readonly role: "image" | "video" | "audio"; readonly artifact: BlobRef }[]> {
+ const ports: Record<string, { readonly role: "image" | "video" | "audio"; readonly artifact: BlobRef }[]> = {};
+ const names = { image: "referenceImage", video: "referenceVideo", audio: "referenceAudio" } as const;
+ for (const item of references) {
+ (ports[names[item.kind]] ??= []).push({ role: item.kind, artifact: item.artifact });
+ }
+ return ports;
+}
+
export function renderSpeakerSpeechProgram(
program: PromptProgram,
intent: SpeakerTakeIntent,
@@ -111,14 +125,13 @@ export function renderSpeakerSpeechProgram(
return sealSeedanceSpeechProgram({
contract: "svml.seedance-speech-spine@1",
model: intent.model,
- prompt: program.blocks.map((item) => item.text).join(program.separator),
- mode: {
- kind: "reference",
- items: intent.references.map((item) => ({ kind: item.kind, artifact: item.artifact })),
+ ports: {
+ prompt: [program.blocks.map((item) => item.text).join(program.separator)],
+ ...referencePortsOf(intent.references),
+ resolution: [intent.resolution],
+ aspectRatio: [intent.aspectRatio],
+ generateAudio: [true],
+ webSearch: [intent.webSearch],
},
- resolution: intent.resolution,
- aspectRatio: intent.aspectRatio,
- generateAudio: true,
- webSearch: intent.webSearch,
});
}
diff --git a/packages/seedance-speaker/test/kit.test.ts b/packages/seedance-speaker/test/kit.test.ts
index 3a834f41..bdd57e2c 100644
--- a/packages/seedance-speaker/test/kit.test.ts
+++ b/packages/seedance-speaker/test/kit.test.ts
@@ -92,12 +92,18 @@ test("rendering the generic Prompt Program preserves exact Seedance method and r
const prompt = compilePromptKit(officialUgcV1KitSpec, bindSpeakerPromptKit(take));
const program = renderSpeakerSpeechProgram(prompt, take);
assert.equal(program.model, "seedance-2-mini");
- assert.equal(program.resolution, "720p");
- assert.equal(program.aspectRatio, "9:16");
- assert.equal(program.mode.kind, "reference");
- if (program.mode.kind !== "reference") assert.fail("expected reference mode");
- assert.deepEqual(program.mode.items.map((item) => item.kind), ["image", "audio"]);
- assert.equal(program.prompt, prompt.blocks.map((item) => item.text).join("\n\n"));
+ assert.deepEqual(program.ports.resolution, ["720p"]);
+ assert.deepEqual(program.ports.aspectRatio, ["9:16"]);
+ assert.deepEqual(
+ (program.ports.referenceImage ?? []).map((item) => (item as { readonly role: string }).role),
+ ["image"],
+ );
+ assert.deepEqual(
+ (program.ports.referenceAudio ?? []).map((item) => (item as { readonly role: string }).role),
+ ["audio"],
+ );
+ assert.deepEqual(program.ports.prompt, [prompt.blocks.map((item) => item.text).join("\n\n")]);
+ assert.equal(program.ports.duration, undefined, "duration arrives from speech estimation");
});
test("Speaker rejects invalid media while Prompt Kit rejects unknown parameters", () => {
diff --git a/packages/seedance/src/index.ts b/packages/seedance/src/index.ts
index 018e0d10..f32f78e8 100644
--- a/packages/seedance/src/index.ts
+++ b/packages/seedance/src/index.ts
@@ -1,60 +1,102 @@
import { artifactDependency } from "@narratage/artifact";
import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
generationObjectSchema,
generationPromptSchema,
- sealGenerationRequest,
+ portsObjectSchema,
+ sealGenerationPortRequest,
+ sealGenerationPortTable,
+ verifyPortsAgainstTable,
+} from "@narratage/generation";
+import type {
+ GenerationPortTable,
+ GenerationPortValue,
+ GenerationRequest,
} from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
import { narrativeDependency } from "@narratage/narrative";
import { assertSpeechDurationIdentity, speechDependency, speechTypes } from "@narratage/speech";
import type { SpeechDuration } from "@narratage/speech";
import { canonicalize, digestOf } from "@narratage/protocol";
-import type { BlobRef, Digest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
+import type { Digest, ProducerRef, TypeRef, ValueSchema } from "@narratage/protocol";
export const seedanceModuleRef = { name: "@narratage/seedance", version: "0.0.0-dev" } as const;
export const seedanceModels = ["seedance-2", "seedance-2-fast", "seedance-2-mini"] as const;
export type SeedanceModel = typeof seedanceModels[number];
-export type SeedanceReference =
- | { readonly kind: "image"; readonly artifact: BlobRef }
- | { readonly kind: "video"; readonly artifact: BlobRef }
- | { readonly kind: "audio"; readonly artifact: BlobRef };
+const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
-export type SeedanceMode =
- | { readonly kind: "text" }
- | { readonly kind: "frames"; readonly firstFrame: BlobRef; readonly lastFrame?: BlobRef }
- | { readonly kind: "reference"; readonly items: readonly SeedanceReference[] };
+/**
+ * What Seedance 2 accepts is fixed when the model is trained; no service
+ * reselling it can widen or narrow this. Every limit below is stated identically
+ * by ByteDance's own launch material, KIE and fal — only the wire field names
+ * differ between services, and those live in each Provider's wire mapping.
+ *
+ * Reference modalities are separate ports because the model gives each its own
+ * capacity: 9 images, 3 videos, 3 audio clips, and no more than 12 files in
+ * total. Only the resolution ceiling differs between the variants.
+ */
+function seedancePortTable(model: SeedanceModel): GenerationPortTable {
+ return sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model,
+ result: "video",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 20_000 }, minItems: 1, maxItems: 1 },
+ { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 9 },
+ { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: 3 },
+ { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: 3 },
+ { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+ {
+ name: "resolution",
+ value: {
+ kind: "enum",
+ values: model === "seedance-2" ? ["480p", "720p", "1080p", "4k"] : ["480p", "720p"],
+ },
+ minItems: 1,
+ maxItems: 1,
+ },
+ { name: "aspectRatio", value: { kind: "enum", values: [...ASPECT_RATIOS] }, minItems: 1, maxItems: 1 },
+ { name: "duration", value: { kind: "number", integer: true, minimum: 4, maximum: 15 }, minItems: 1, maxItems: 1 },
+ { name: "generateAudio", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+ { name: "webSearch", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+ ],
+ requires: [
+ // First-frame, first-and-last-frame and multimodal reference are three
+ // scenarios the model cannot combine.
+ { kind: "atMostOneOf", ports: ["referenceImage", "firstFrame"] },
+ { kind: "atMostOneOf", ports: ["referenceVideo", "firstFrame"] },
+ { kind: "atMostOneOf", ports: ["referenceAudio", "firstFrame"] },
+ { kind: "requiresPresent", port: "lastFrame", needs: ["firstFrame"] },
+ // Reference audio cannot travel alone; it needs at least one visual reference.
+ { kind: "requiresAnyOf", port: "referenceAudio", anyOf: ["referenceImage", "referenceVideo"] },
+ { kind: "weightedTotal", weights: { referenceImage: 1, referenceVideo: 1, referenceAudio: 1 }, maximum: 12 },
+ ],
+ });
+}
-export type SeedanceRequestContent<M extends SeedanceModel = SeedanceModel> = {
- readonly contract: "svml.seedance-request@1";
- readonly model: M;
- readonly prompt: string;
- readonly mode: SeedanceMode;
- readonly resolution: "480p" | "720p" | "1080p";
- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";
- readonly durationSec: number;
- readonly generateAudio: boolean;
- readonly webSearch: boolean;
+export const seedancePorts: Readonly<Record<SeedanceModel, GenerationPortTable>> = {
+ "seedance-2": seedancePortTable("seedance-2"),
+ "seedance-2-fast": seedancePortTable("seedance-2-fast"),
+ "seedance-2-mini": seedancePortTable("seedance-2-mini"),
};
-export type SeedanceRequest<M extends SeedanceModel = SeedanceModel> = SeedanceRequestContent<M>;
+export type SeedancePortMap = Readonly<Record<string, readonly GenerationPortValue[]>>;
+
+export function sealSeedanceRequest(model: SeedanceModel, ports: SeedancePortMap): GenerationRequest {
+ return sealGenerationPortRequest(seedancePorts[model], ports);
+}
export type SeedancePrompt = {
readonly contract: "svml.seedance-prompt@1";
readonly text: string;
};
+/** One authored generation minus the duration only speech estimation can supply. */
export type SeedanceSpeechProgram = {
readonly contract: "svml.seedance-speech-spine@1";
readonly model: SeedanceModel;
- readonly prompt: string;
- readonly mode: SeedanceMode;
- readonly resolution: "480p" | "720p" | "1080p";
- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";
- readonly generateAudio: true;
- readonly webSearch: boolean;
+ readonly ports: SeedancePortMap;
};
export const seedanceTypes = {
@@ -75,17 +117,22 @@ export const seedanceSpeechCompileImplementationDigests = Object.fromEntries(
export const seedanceSurfaceImplementationDigests = {
prompt: digestOf("@narratage/seedance/prompt-surface@1"),
- speech: digestOf("@narratage/seedance/speech-surface@3"),
- video: digestOf("@narratage/seedance/video-surface@1"),
+ speech: digestOf("@narratage/seedance/speech-surface@4"),
+ video: digestOf("@narratage/seedance/video-surface@2"),
} as const;
+function assertObject(value: unknown): asserts value is Record<string, unknown> {
+ if (value === null || typeof value !== "object" || Array.isArray(value)) {
+ throw new Error("Seedance value must be an object");
+ }
+}
+
export function sealSeedancePrompt(text: string): SeedancePrompt {
const normalized = text.trim();
if (normalized.length === 0 || normalized.length > 20_000) {
throw new Error("Seedance Prompt must contain 1 to 20,000 characters");
}
- const content = { contract: "svml.seedance-prompt@1" as const, text: normalized };
- return content;
+ return { contract: "svml.seedance-prompt@1" as const, text: normalized };
}
export function verifySeedancePrompt(value: unknown): asserts value is SeedancePrompt {
@@ -95,173 +142,50 @@ export function verifySeedancePrompt(value: unknown): asserts value is SeedanceP
}
}
-export function sealSeedanceSpeechProgram(value: SeedanceSpeechProgram): SeedanceSpeechProgram {
- const result = structuredClone(value);
- verifySeedanceSpeechProgram(result);
- return result;
-}
-
export function verifySeedanceSpeechProgram(value: unknown): asserts value is SeedanceSpeechProgram {
assertObject(value);
- if (
- value.contract !== "svml.seedance-speech-spine@1"
- || !seedanceModels.includes(value.model as SeedanceModel)
- || typeof value.prompt !== "string"
- || value.prompt.trim().length === 0
- || value.generateAudio !== true
- || typeof value.webSearch !== "boolean"
- || !["480p", "720p", "1080p"].includes(value.resolution as string)
- || !["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"].includes(value.aspectRatio as string)
- ) {
- throw new Error("Seedance SpeechProgram is invalid");
+ if (value.contract !== "svml.seedance-speech-spine@1"
+ || !seedanceModels.includes(value.model as SeedanceModel)) {
+ throw new Error("Seedance SpeechProgram identity is invalid");
}
- const program = value as unknown as SeedanceSpeechProgram;
- sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: program.model,
- prompt: program.prompt,
- mode: program.mode,
- resolution: program.resolution,
- aspectRatio: program.aspectRatio,
- durationSec: 4,
- generateAudio: true,
- webSearch: program.webSearch,
- });
+ const table = seedancePorts[value.model as SeedanceModel];
+ verifyPortsAgainstTable(table, value.ports, { omit: ["duration"] });
+ const generateAudio = (value.ports as SeedancePortMap).generateAudio;
+ if (generateAudio?.[0] !== true) throw new Error("Seedance SpeechProgram must generate audio");
+}
+
+export function sealSeedanceSpeechProgram(value: SeedanceSpeechProgram): SeedanceSpeechProgram {
+ const result = canonicalize(value) as unknown as SeedanceSpeechProgram;
+ verifySeedanceSpeechProgram(result);
+ return result;
}
export function compileSeedanceSpeechRequest(
program: SeedanceSpeechProgram,
duration: SpeechDuration,
-): SeedanceRequest {
+): GenerationRequest {
verifySeedanceSpeechProgram(program);
assertSpeechDurationIdentity(duration);
- if (!Number.isSafeInteger(duration.durationSec) || duration.durationSec < 4 || duration.durationSec > 15) {
- throw new Error("Seedance Speech duration must be an integer between 4 and 15 seconds");
- }
- return sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: program.model,
- prompt: program.prompt,
- mode: program.mode,
- resolution: program.resolution,
- aspectRatio: program.aspectRatio,
- durationSec: duration.durationSec,
- generateAudio: true,
- webSearch: program.webSearch,
- });
+ return sealSeedanceRequest(program.model, { ...program.ports, duration: [duration.durationSec] });
}
-const referenceSchema: ValueSchema = {
- kind: "oneOf",
- variants: (["image", "video", "audio"] as const).map((kind) => generationObjectSchema({
- kind: { schema: { kind: "literal", value: kind } },
- artifact: { schema: generationBlobRefSchema },
- })),
-};
-
-const modeSchema: ValueSchema = {
- kind: "oneOf",
- variants: [
- generationObjectSchema({ kind: { schema: { kind: "literal", value: "text" } } }),
- generationObjectSchema({
- kind: { schema: { kind: "literal", value: "frames" } },
- firstFrame: { schema: generationBlobRefSchema },
- lastFrame: { schema: generationBlobRefSchema, optional: true },
- }),
- generationObjectSchema({
- kind: { schema: { kind: "literal", value: "reference" } },
- items: { schema: { kind: "array", minItems: 1, maxItems: 12, items: referenceSchema } },
- }),
- ],
-};
-
-const aspectRatioSchema = {
- kind: "string",
- enum: ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"],
-} as const satisfies ValueSchema;
-
-const speechSpineSchema: ValueSchema = generationObjectSchema({
+const speechSpineSchema = (model: SeedanceModel): ValueSchema => generationObjectSchema({
contract: { schema: { kind: "literal", value: "svml.seedance-speech-spine@1" } },
- model: { schema: { kind: "string", enum: [...seedanceModels] } },
- prompt: { schema: generationPromptSchema },
- mode: { schema: modeSchema },
- resolution: { schema: { kind: "string", enum: ["480p", "720p", "1080p"] } },
- aspectRatio: { schema: aspectRatioSchema },
- generateAudio: { schema: { kind: "literal", value: true } },
- webSearch: { schema: { kind: "boolean" } },
+ model: { schema: { kind: "literal", value: model } },
+ ports: { schema: portsObjectSchema(seedancePorts[model], { omit: ["duration"] }) },
});
-function requestSchema(model: SeedanceModel): ValueSchema {
- return generationObjectSchema({
- contract: { schema: { kind: "literal", value: "svml.seedance-request@1" } },
- model: { schema: { kind: "literal", value: model } },
- prompt: { schema: generationPromptSchema },
- mode: { schema: modeSchema },
- resolution: {
- schema: {
- kind: "string",
- enum: model === "seedance-2" ? ["480p", "720p", "1080p"] : ["480p", "720p"],
- },
- },
- aspectRatio: { schema: aspectRatioSchema },
- durationSec: { schema: { kind: "number", integer: true, minimum: 4, maximum: 15 } },
- generateAudio: { schema: { kind: "boolean" } },
- webSearch: { schema: { kind: "boolean" } },
- });
-}
-
-function assertObject(value: unknown): asserts value is Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) {
- throw new Error("Seedance request must be an object");
- }
-}
-
-export function verifySeedanceRequest(value: unknown, expectedModel?: SeedanceModel): asserts value is SeedanceRequest {
- assertObject(value);
- if (value.contract !== "svml.seedance-request@1") throw new Error("Seedance request contract is invalid");
- if (!seedanceModels.includes(value.model as SeedanceModel)) throw new Error("Seedance model is invalid");
- if (expectedModel !== undefined && value.model !== expectedModel) throw new Error(`Expected ${expectedModel}`);
- const mode = value.mode;
- assertObject(mode);
- if (mode.kind === "frames") {
- assertGenerationBlobRef(mode.firstFrame, "image/");
- if (mode.lastFrame !== undefined) assertGenerationBlobRef(mode.lastFrame, "image/");
- } else if (mode.kind === "reference") {
- if (!Array.isArray(mode.items) || mode.items.length === 0) throw new Error("Seedance references are empty");
- for (const item of mode.items) {
- assertObject(item);
- if (item.kind !== "image" && item.kind !== "video" && item.kind !== "audio") {
- throw new Error("Seedance reference kind is invalid");
- }
- assertGenerationBlobRef(item.artifact, `${item.kind}/` as "image/" | "video/" | "audio/");
- }
- } else if (mode.kind !== "text") {
- throw new Error("Seedance mode is invalid");
- }
-}
-
-export function sealSeedanceRequest<M extends SeedanceModel>(
- content: SeedanceRequestContent<M>,
-): SeedanceRequest<M> {
- const request = sealGenerationRequest(content);
- verifySeedanceRequest(request, content.model);
- return request;
-}
-
const seedanceBaseDefinition = defineExactModelModule({
module: seedanceModuleRef,
- endpoints: [
+ endpoints: ([
["standard", "seedance-2"],
["fast", "seedance-2-fast"],
["mini", "seedance-2-mini"],
- ].map(([key, model]) => ({
- key: key!,
- requestTypeName: `${model!.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
- capabilityName: `${model}-generation`,
+ ] as const).map(([key, model]) => ({
+ key,
+ requestTypeName: `${model.split("-").map((part) => part[0]!.toUpperCase() + part.slice(1)).join("")}Request`,
producerName: `request-${model}`,
- result: "video" as const,
- requestSchema: requestSchema(model as SeedanceModel),
- verifyRequest: (value: unknown) => verifySeedanceRequest(value, model as SeedanceModel),
+ ports: seedancePorts[model],
})),
});
@@ -282,7 +206,10 @@ export const seedanceManifest = {
],
types: [
...seedanceBaseDefinition.manifest.types,
- { name: seedanceTypes.speechSpine.name, schema: speechSpineSchema },
+ {
+ name: seedanceTypes.speechSpine.name,
+ schema: { kind: "oneOf", variants: seedanceModels.map(speechSpineSchema) } satisfies ValueSchema,
+ },
{
name: seedanceTypes.prompt.name,
schema: generationObjectSchema({
diff --git a/packages/seedance/src/surface.ts b/packages/seedance/src/surface.ts
index 6e393e8d..93a2bf42 100644
--- a/packages/seedance/src/surface.ts
+++ b/packages/seedance/src/surface.ts
@@ -15,22 +15,31 @@ import {
createSeedanceGenerationFragment,
createSeedanceSpeechGenerationFragment,
} from "./fragment.js";
+import { generationPort } from "@narratage/generation";
+import type { GenerationMediaRole, GenerationPortTable } from "@narratage/generation";
+
import {
sealSeedancePrompt,
sealSeedanceRequest,
sealSeedanceSpeechProgram,
seedanceEndpoints,
+ seedancePorts,
seedanceSpeechCompileProducers,
seedanceTypes,
verifySeedancePrompt,
} from "./index.js";
import type {
SeedanceModel,
+ SeedancePortMap,
SeedancePrompt,
- SeedanceReference,
} from "./index.js";
-type ReferenceInput = SeedanceReference & { readonly role?: string };
+/** `role` is the media kind the port accepts; `label` is the author's own note about it. */
+type ReferenceInput = {
+ readonly role: GenerationMediaRole;
+ readonly artifact: BlobRef;
+ readonly label?: string;
+};
function localName(value: string): string {
return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
@@ -154,43 +163,57 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
throw new Error(`${element.name}.${name} must be true or false`);
}
+/** The model's own port table is the only source of truth for these bounds. */
+function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
+ const port = generationPort(table, name);
+ if (port.value.kind !== "enum") throw new Error(`${table.model} port ${name} is not enumerated`);
+ return port.value.values;
+}
+
function generationSettings(
element: StructuredElement,
model: SeedanceModel,
suppliedDurationSec?: number,
-): {
- readonly durationSec: number;
- readonly resolution: "480p" | "720p" | "1080p";
- readonly aspectRatio: "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive";
- readonly webSearch: boolean;
-} {
+): SeedancePortMap {
+ const table = seedancePorts[model];
+ const duration = generationPort(table, "duration");
+ if (duration.value.kind !== "number") throw new Error("Seedance duration port is not numeric");
const durationSec = suppliedDurationSec ?? integerAttribute(element, "duration");
- if (durationSec < 4 || durationSec > 15) {
- throw new Error(`${element.name}.duration must be between 4 and 15 seconds`);
+ const { minimum = 0, maximum = Number.MAX_SAFE_INTEGER } = duration.value;
+ if (durationSec < minimum || durationSec > maximum) {
+ throw new Error(`${element.name}.duration must be between ${minimum} and ${maximum} seconds`);
}
+ const resolutions = enumeratedPort(table, "resolution");
const resolution = optionalStringAttribute(element, "resolution") ?? "720p";
- if (resolution !== "480p" && resolution !== "720p" && resolution !== "1080p") {
- throw new Error(`${element.name}.resolution must be 480p, 720p or 1080p`);
- }
- if (resolution === "1080p" && model !== "seedance-2") {
- throw new Error(`${element.name}.resolution 1080p is available only for the standard model`);
+ if (!resolutions.includes(resolution)) {
+ throw new Error(`${element.name}.resolution must be ${resolutions.join(", ")} for ${model}`);
}
+ const aspectRatios = enumeratedPort(table, "aspectRatio");
const aspectRatio = optionalStringAttribute(element, "aspect-ratio") ?? "9:16";
- if (!["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"].includes(aspectRatio)) {
+ if (!aspectRatios.includes(aspectRatio)) {
throw new Error(`${element.name}.aspect-ratio is not supported by Seedance`);
}
return {
- durationSec,
- resolution,
- aspectRatio: aspectRatio as "1:1" | "4:3" | "3:4" | "16:9" | "9:16" | "21:9" | "adaptive",
- webSearch: booleanAttribute(element, "web-search", false),
+ duration: [durationSec],
+ resolution: [resolution],
+ aspectRatio: [aspectRatio],
+ webSearch: [booleanAttribute(element, "web-search", false)],
};
}
+const REFERENCE_PORTS = {
+ image: "referenceImage",
+ video: "referenceVideo",
+ audio: "referenceAudio",
+} as const satisfies Record<GenerationMediaRole, string>;
+
function references(
element: StructuredElement,
+ model: SeedanceModel,
resolveReference: (path: string) => SurfaceResolvedReference | undefined,
): ReferenceInput[] {
+ const table = seedancePorts[model];
+ const accepted = Object.keys(REFERENCE_PORTS) as readonly GenerationMediaRole[];
const result: ReferenceInput[] = [];
for (const child of element.children) {
if (child.kind === "text") {
@@ -198,29 +221,45 @@ function references(
continue;
}
if (localName(child.name) !== "Reference") throw new Error(`${element.name} accepts only Reference children`);
- attributes(child, [], ["image", "video", "audio", "role"]);
- const kinds = (["image", "video", "audio"] as const).filter((kind) => child.attributes[kind] !== undefined);
- if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of image, video or audio`);
- const kind = kinds[0]!;
- const source = resolved(child, kind, resolveReference);
- const artifact = blob(source, `${child.name}.${kind}`);
- if (!artifact.mediaType.startsWith(`${kind}/`)) {
- throw new Error(`${child.name}.${kind} must reference ${kind} media`);
+ attributes(child, [], [...accepted, "role"]);
+ const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
+ if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
+ const role = kinds[0]!;
+ const source = resolved(child, role, resolveReference);
+ const artifact = blob(source, `${child.name}.${role}`);
+ if (!artifact.mediaType.startsWith(`${role}/`)) {
+ throw new Error(`${child.name}.${role} must reference ${role} media`);
+ }
+ const label = optionalStringAttribute(child, "role");
+ result.push({ role, artifact, ...(label === undefined ? {} : { label }) });
+ }
+ // Every bound below is read from the model's own port table, never repeated here.
+ for (const role of accepted) {
+ const port = generationPort(table, REFERENCE_PORTS[role]);
+ const used = result.filter((item) => item.role === role).length;
+ if (used > port.maxItems) {
+ throw new Error(`${element.name} accepts at most ${port.maxItems} ${role} references`);
}
- const role = optionalStringAttribute(child, "role");
- result.push({ kind, artifact, ...(role === undefined ? {} : { role }) });
}
- if (result.length > 12) throw new Error(`${element.name} accepts at most 12 references`);
return result;
}
function referencePrompt(values: readonly ReferenceInput[]): string {
- const roles = values.flatMap((item, index) => item.role === undefined
+ const roles = values.flatMap((item, index) => item.label === undefined
? []
- : [`Reference ${item.kind} ${index + 1} is the ${item.role}.`]);
+ : [`Reference ${item.role} ${index + 1} is the ${item.label}.`]);
return roles.length === 0 ? "" : `\n\nReference roles:\n${roles.join("\n")}`;
}
+/** Authored references split into the model's per-modality ports; labels never reach the wire. */
+function referencePorts(values: readonly ReferenceInput[]): SeedancePortMap {
+ return Object.fromEntries((Object.keys(REFERENCE_PORTS) as readonly GenerationMediaRole[])
+ .map((role) => [REFERENCE_PORTS[role], values
+ .filter((item) => item.role === role)
+ .map(({ artifact }) => ({ role, artifact }))])
+ .filter(([, items]) => (items as readonly unknown[]).length > 0));
+}
+
function dialogueExcerpt(reference: SurfaceResolvedReference, subject: string): { readonly dialogue: string } {
if (!sameType(reference.type, narrativeTypes.dialogueExcerpt)) {
throw new Error(`${subject} must reference a NarrativeDialogueExcerpt such as script.segment.opening.dialogue`);
@@ -304,16 +343,12 @@ export const decodeSeedanceVideoSurface: StructuredSurfaceHandler = ({ element,
]);
const selected = modelSelection(element);
const declaredPrompt = prompt(resolved(element, "prompt", resolveReference), `${element.name}.prompt`);
- const refs = references(element, resolveReference);
- const request = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: selected.model,
- prompt: declaredPrompt.text + referencePrompt(refs),
- mode: refs.length === 0
- ? { kind: "text" }
- : { kind: "reference", items: refs.map(({ role: _role, ...item }) => item) },
+ const refs = references(element, selected.model, resolveReference);
+ const request = sealSeedanceRequest(selected.model, {
+ prompt: [declaredPrompt.text + referencePrompt(refs)],
+ ...referencePorts(refs),
...generationSettings(element, selected.model),
- generateAudio: booleanAttribute(element, "generate-audio", false),
+ generateAudio: [booleanAttribute(element, "generate-audio", false)],
});
return generationOutput(element, request, `${stringAttribute(element, "id")}.video`);
};
@@ -325,23 +360,20 @@ export const decodeSeedanceSpeechSurface: StructuredSurfaceHandler = ({ element,
const selected = modelSelection(element);
const declaredPrompt = prompt(resolved(element, "prompt", resolveReference), `${element.name}.prompt`);
const spoken = dialogueExcerpt(resolved(element, "dialogue", resolveReference), `${element.name}.dialogue`);
- const refs = references(element, resolveReference);
+ const refs = references(element, selected.model, resolveReference);
const duration = speechDurationReference(element, resolveReference);
const promptText = `${declaredPrompt.text}${referencePrompt(refs)}\n\nSpoken dialogue — say exactly:\n${spoken.dialogue}`;
- const mode = refs.length === 0
- ? { kind: "text" as const }
- : { kind: "reference" as const, items: refs.map(({ role: _role, ...item }) => item) };
if (duration !== undefined) {
- const settings = generationSettings(element, selected.model, 4);
+ const { duration: _later, ...settings } = generationSettings(element, selected.model, 4);
const program = sealSeedanceSpeechProgram({
contract: "svml.seedance-speech-spine@1",
model: selected.model,
- prompt: promptText,
- mode,
- resolution: settings.resolution,
- aspectRatio: settings.aspectRatio,
- generateAudio: true,
- webSearch: settings.webSearch,
+ ports: {
+ prompt: [promptText],
+ ...referencePorts(refs),
+ ...settings,
+ generateAudio: [true],
+ },
});
const id = stringAttribute(element, "id");
const programId = `${id}.program`;
@@ -369,13 +401,11 @@ export const decodeSeedanceSpeechSurface: StructuredSurfaceHandler = ({ element,
fragments: [fragment],
};
}
- const request = sealSeedanceRequest({
- contract: "svml.seedance-request@1",
- model: selected.model as SeedanceModel,
- prompt: promptText,
- mode,
+ const request = sealSeedanceRequest(selected.model, {
+ prompt: [promptText],
+ ...referencePorts(refs),
...generationSettings(element, selected.model),
- generateAudio: true,
+ generateAudio: [true],
});
return generationOutput(element, request, stringAttribute(element, "id"));
};
diff --git a/packages/seedream/src/index.ts b/packages/seedream/src/index.ts
index fbb624eb..d6668eb0 100644
--- a/packages/seedream/src/index.ts
+++ b/packages/seedream/src/index.ts
@@ -1,92 +1,45 @@
-import {
- assertGenerationBlobRef,
- generationBlobRefSchema,
- generationObjectSchema,
- generationPromptSchema,
- sealGenerationRequest,
-} from "@narratage/generation";
+import { sealGenerationPortRequest, sealGenerationPortTable } from "@narratage/generation";
+import type { GenerationPortTable, GenerationPortValue, GenerationRequest } from "@narratage/generation";
import { defineExactModelModule } from "@narratage/model-kit";
-import type { BlobRef, ValueSchema } from "@narratage/protocol";
export const seedreamModuleRef = { name: "@narratage/seedream", version: "0.0.0-dev" } as const;
-export type SeedreamMode = "text" | "image";
-type Common = {
- readonly contract: "svml.seedream-5-lite-request@1";
- readonly model: "seedream-5-lite";
- readonly prompt: string;
- readonly aspectRatio: string;
- readonly quality: "basic";
- readonly outputFormat: "png" | "jpg";
- /** Explicit author choice; the Provider never silently changes this policy. */
- readonly nsfwCheck: boolean;
-};
-export type SeedreamTextRequestContent = Common & { readonly mode: "text" };
-export type SeedreamImageRequestContent = Common & {
- readonly mode: "image";
- readonly images: readonly BlobRef[];
-};
-export type SeedreamRequestContent = SeedreamTextRequestContent | SeedreamImageRequestContent;
-export type SeedreamRequest = SeedreamRequestContent;
-const commonFields = {
- contract: { schema: { kind: "literal", value: "svml.seedream-5-lite-request@1" } },
- model: { schema: { kind: "literal", value: "seedream-5-lite" } },
- prompt: { schema: generationPromptSchema },
- aspectRatio: { schema: { kind: "string", minLength: 3, maxLength: 16 } },
- quality: { schema: { kind: "literal", value: "basic" } },
- outputFormat: { schema: { kind: "string", enum: ["png", "jpg"] } },
- nsfwCheck: { schema: { kind: "boolean" } },
-} as const;
-const schemas: Record<SeedreamMode, ValueSchema> = {
- text: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "text" } },
- }),
- image: generationObjectSchema({
- ...commonFields,
- mode: { schema: { kind: "literal", value: "image" } },
- images: { schema: { kind: "array", minItems: 1, maxItems: 16, items: generationBlobRefSchema } },
- }),
-};
-
-function object(value: unknown): Record<string, unknown> {
- if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("Seedream request must be an object");
- return value as Record<string, unknown>;
-}
-
-export function verifySeedreamRequest(value: unknown, expectedMode?: SeedreamMode): asserts value is SeedreamRequest {
- const request = object(value);
- if (request.contract !== "svml.seedream-5-lite-request@1" || request.model !== "seedream-5-lite") {
- throw new Error("Seedream request identity is invalid");
- }
- if (expectedMode !== undefined && request.mode !== expectedMode) throw new Error(`Expected Seedream ${expectedMode}`);
- if (request.mode === "image") {
- if (!Array.isArray(request.images) || request.images.length === 0) throw new Error("Seedream input images are empty");
- request.images.forEach((image) => assertGenerationBlobRef(image, "image/"));
- } else if (request.mode !== "text") {
- throw new Error("Seedream mode is invalid");
- }
-}
+export const seedream5LitePorts: GenerationPortTable = sealGenerationPortTable({
+ contract: "svml.generation-ports@1",
+ model: "seedream-5-lite",
+ result: "image",
+ ports: [
+ { name: "prompt", value: { kind: "text", maxChars: 3_000 }, minItems: 1, maxItems: 1 },
+ {
+ name: "aspectRatio",
+ value: { kind: "enum", values: ["1:1", "4:3", "3:4", "16:9", "9:16", "2:3", "3:2", "21:9"] },
+ minItems: 1,
+ maxItems: 1,
+ },
+ /** Basic renders 2K, high 3K and ultra 4K. */
+ { name: "quality", value: { kind: "enum", values: ["basic", "high", "ultra"] }, minItems: 1, maxItems: 1 },
+ { name: "outputFormat", value: { kind: "enum", values: ["png", "jpeg"] }, minItems: 1, maxItems: 1 },
+ /** Explicit author choice; the Provider never silently changes this policy. */
+ { name: "nsfwCheck", value: { kind: "boolean" }, minItems: 1, maxItems: 1 },
+ { name: "images", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 16 },
+ ],
+ requires: [],
+});
-export function sealSeedreamRequest<T extends SeedreamRequestContent>(
- content: T,
-): T {
- const request = sealGenerationRequest(content);
- verifySeedreamRequest(request, content.mode);
- return request;
+export function sealSeedreamRequest(
+ ports: Readonly<Record<string, readonly GenerationPortValue[]>>,
+): GenerationRequest {
+ return sealGenerationPortRequest(seedream5LitePorts, ports);
}
export const seedreamDefinition = defineExactModelModule({
module: seedreamModuleRef,
- endpoints: (["text", "image"] as const).map((mode) => ({
- key: mode,
- requestTypeName: mode === "text" ? "Seedream5LiteTextRequest" : "Seedream5LiteImageRequest",
- capabilityName: `seedream-5-lite-${mode}-generation`,
- producerName: `request-seedream-5-lite-${mode}`,
- result: "image" as const,
- requestSchema: schemas[mode],
- verifyRequest: (value: unknown) => verifySeedreamRequest(value, mode),
- })),
+ endpoints: [{
+ key: "image",
+ requestTypeName: "Seedream5LiteRequest",
+ producerName: "request-seedream-5-lite",
+ ports: seedream5LitePorts,
+ }],
});
export const seedreamManifest = seedreamDefinition.manifest;
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 027eeddd..c417f3a4 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -984,24 +984,9 @@ importers:
'@narratage/endpoint-kit':
specifier: workspace:*
version: link:../endpoint-kit
- '@narratage/gemini-omni':
- specifier: workspace:*
- version: link:../gemini-omni
'@narratage/generation':
specifier: workspace:*
version: link:../generation
- '@narratage/gpt-image':
- specifier: workspace:*
- version: link:../gpt-image
- '@narratage/grok-imagine':
- specifier: workspace:*
- version: link:../grok-imagine
- '@narratage/minimax-h3':
- specifier: workspace:*
- version: link:../minimax-h3
- '@narratage/nano-banana':
- specifier: workspace:*
- version: link:../nano-banana
'@narratage/protocol':
specifier: workspace:*
version: link:../protocol
@@ -1014,12 +999,6 @@ importers:
'@narratage/runtime-adapter-node':
specifier: workspace:*
version: link:../runtime-adapter-node
- '@narratage/seedance':
- specifier: workspace:*
- version: link:../seedance
- '@narratage/seedream':
- specifier: workspace:*
- version: link:../seedream
devDependencies:
'@narratage/artifact-store-fs':
specifier: workspace:*
@@ -1036,18 +1015,39 @@ importers:
'@narratage/elaborator':
specifier: workspace:*
version: link:../elaborator
+ '@narratage/gemini-omni':
+ specifier: workspace:*
+ version: link:../gemini-omni
+ '@narratage/gpt-image':
+ specifier: workspace:*
+ version: link:../gpt-image
+ '@narratage/grok-imagine':
+ specifier: workspace:*
+ version: link:../grok-imagine
'@narratage/local':
specifier: workspace:*
version: link:../local
'@narratage/media':
specifier: workspace:*
version: link:../media
+ '@narratage/minimax-h3':
+ specifier: workspace:*
+ version: link:../minimax-h3
'@narratage/model-kit':
specifier: workspace:*
version: link:../model-kit
+ '@narratage/nano-banana':
+ specifier: workspace:*
+ version: link:../nano-banana
'@narratage/narrative':
specifier: workspace:*
version: link:../narrative
+ '@narratage/seedance':
+ specifier: workspace:*
+ version: link:../seedance
+ '@narratage/seedream':
+ specifier: workspace:*
+ version: link:../seedream
'@narratage/validation':
specifier: workspace:*
version: link:../validation
diff --git a/tools/package-boundaries.test.mjs b/tools/package-boundaries.test.mjs
index e4aca014..d2cc0610 100644
--- a/tools/package-boundaries.test.mjs
+++ b/tools/package-boundaries.test.mjs
@@ -102,6 +102,31 @@ test("the declared domain-neutral distribution closes without syntax, AIGC or vi
assert.deepEqual(graph.get("@narratage/core"), ["@narratage/protocol"]);
});
+test("a Provider reaches no exact-model package, so models and services stay N+M", async () => {
+ const packages = await workspacePackages();
+ const graph = productionGraph(packages);
+ const models = [
+ "@narratage/gemini-omni",
+ "@narratage/gpt-image",
+ "@narratage/grok-imagine",
+ "@narratage/minimax-h3",
+ "@narratage/nano-banana",
+ "@narratage/seedance",
+ "@narratage/seedream",
+ ];
+ for (const name of [...packages.keys()].filter((item) => item.startsWith("@narratage/provider-"))) {
+ const reached = transitive(graph, name);
+ assert.deepEqual(
+ models.filter((model) => reached.has(model)),
+ [],
+ `${name} depends on an exact-model package; a Provider must map declared ports instead`,
+ );
+ }
+ // The shared port and wire-mapping vocabulary is the only legitimate meeting point.
+ assert.ok(transitive(graph, "@narratage/provider-kie").has("@narratage/generation"));
+ assert.ok(transitive(graph, "@narratage/seedance").has("@narratage/generation"));
+});
+
test("Text compilation is one explicit leaf assembly, not a Package Loader or Local Runtime dependency", async () => {
const graph = productionGraph(await workspacePackages());
assert.ok(transitive(graph, "@narratage/compiler-text-node").has("@narratage/text"));
@@ -172,7 +197,7 @@ test("every workspace package is exercised by some test, directly or through a t
for (const file of await readdir(testRoot)) {
if (!file.endsWith(".ts")) continue;
const source = await readFile(new URL(file, testRoot), "utf8");
- for (const match of source.matchAll(/"(@narratage\/[a-z-]+)"/gu)) {
+ for (const match of source.matchAll(/"(@narratage\/[a-z0-9-]+)"/gu)) {
testedImports.add(match[1]);
for (const dependency of transitive(graph, match[1])) testedImports.add(dependency);
}