videobook 0.0.0-stage → 0.2.0

package/dist/tools/generate-media.js

@@ -0,0 +1,157 @@
+import { z } from "zod";
+import { queue } from "../queue.js";
+import { generationLabel } from "../artifact-label.js";
+import { previewPlaceholderUrl } from "../preview-payload.js";
+import { resolveModel, UnknownModelError } from "../media/descriptor.js";
+import { buildWireRequest } from "../media/request.js";
+import { checkInsertVideoTiming, checkRefDurations, checkRefs, normalizeRefs } from "../media/refs.js";
+import { PROVIDER_ENV_KEYS } from "../media/adapters/index.js";
+import { listModels, modelListing } from "../media/listing.js";
+import { OPERATIONS_BY_MEDIA, REF_ROLES } from "../media/types.js";
+const ARTIFACT_KIND = { image: "img", video: "vid", audio: "aud" };
+const OPERATIONS = [
+    ...OPERATIONS_BY_MEDIA.image,
+    ...OPERATIONS_BY_MEDIA.video,
+    ...OPERATIONS_BY_MEDIA.audio,
+];
+const refList = z.union([z.string(), z.array(z.string())]).optional();
+function refsSchema() {
+    return z.object({
+        image: refList.describe("Reference images: artifact ids, @grid addresses resolved to ids, or https URLs"),
+        first_frame: refList.describe("First frame image"),
+        last_frame: refList.describe("Last frame image"),
+        video: refList.describe("Reference or source videos"),
+        audio: refList.describe("Reference or driving audio"),
+    }).optional().describe("Media inputs by role; each model accepts the roles list_generation_models reports");
+}
+function toolError(text) {
+    return { isError: true, content: [{ type: "text", text }] };
+}
+function textResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+function placeholderRefs(refs) {
+    const placeholders = {};
+    for (const role of REF_ROLES) {
+        const list = refs[role];
+        if (list)
+            placeholders[role] = list.map((ref) => ref.startsWith("http") ? ref : previewPlaceholderUrl(ref));
+    }
+    return placeholders;
+}
+function resolveFor(media, raw) {
+    if (typeof raw !== "string" || raw.trim() === "")
+        return "model is required; call list_generation_models";
+    try {
+        const model = resolveModel(raw.trim());
+        return model.media === media ? model : `${model.id} generates ${model.media}, not ${media}`;
+    }
+    catch (error) {
+        return error instanceof UnknownModelError ? error.message : String(error);
+    }
+}
+function checkOperation(model, operation) {
+    if (typeof operation !== "string" || operation === "")
+        return null;
+    return model.entry.operations.includes(operation)
+        ? null
+        : `${model.id} does not support ${operation}; it supports ${model.entry.operations.join(", ")}`;
+}
+function optionsOf(raw) {
+    return raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
+function optionalString(raw) {
+    return typeof raw === "string" && raw.trim() !== "" ? raw : undefined;
+}
+async function validate(engine, model, args, refs) {
+    const envKey = PROVIDER_ENV_KEYS[model.provider];
+    if (!process.env[envKey])
+        return `${envKey} environment variable is not set`;
+    const operationError = checkOperation(model, args.operation);
+    if (operationError)
+        return operationError;
+    const built = buildWireRequest(model, {
+        prompt: optionalString(args.prompt),
+        refUrls: placeholderRefs(refs),
+        options: optionsOf(args.options),
+        mode: optionalString(args.mode),
+    });
+    if (!built.ok)
+        return built.error;
+    return (await checkRefs(engine, refs))
+        ?? (await checkInsertVideoTiming(engine, model, refs, optionsOf(args.options)))
+        ?? checkRefDurations(engine, model, refs);
+}
+async function enqueueGeneration(engine, model, args, refs) {
+    const prompt = optionalString(args.prompt);
+    const created = await engine.artifacts.create(ARTIFACT_KIND[model.media], generationLabel(model.title, prompt));
+    if (!created.ok)
+        return toolError(`Failed to create ${model.media} asset: ${created.error.message}`);
+    const { artifactId, path } = created.value;
+    const jobId = `generate-${model.media}-${artifactId}-${Date.now()}`;
+    const job = {
+        type: "generate_media",
+        model: model.id,
+        bookId: String(args.book_id),
+        assetId: artifactId,
+        assetDir: path,
+        ...(prompt !== undefined ? { prompt } : {}),
+        refs,
+        options: optionsOf(args.options),
+        ...(optionalString(args.mode) ? { mode: optionalString(args.mode) } : {}),
+        ...(optionalString(args.replace_audio_with) ? { replaceAudioWith: optionalString(args.replace_audio_with) } : {}),
+    };
+    await queue.enqueue(jobId, job);
+    return textResult({ asset_id: artifactId, job_id: jobId, model: model.id, status: "enqueued" });
+}
+function generateDef(engine, media) {
+    return {
+        name: `generate_${media}`,
+        description: `Generate ${media === "audio" ? "audio (speech, dialogue, music, sound effects)" : media === "image" ? "an image" : "a video"} with any catalog model. `
+            + "Pick a model id from list_generation_models; options are validated against that model's apicity schema and omitted options use apicity defaults.",
+        schema: {
+            book_id: z.string().describe("Book id"),
+            model: z.string().describe("Model id such as kie:nano-banana-2-1 or fal:fal-ai/nano-banana-pro; see list_generation_models"),
+            prompt: z.string().optional().describe("Prompt; name inputs as @image1, @video1, @audio1, @firstframe or @lastframe"),
+            refs: refsSchema(),
+            mode: z.string().optional().describe("Input mode id for models with several (for example i2v or r2v)"),
+            operation: z.enum(OPERATIONS_BY_MEDIA[media]).optional().describe("Optional check that the model supports this operation"),
+            options: z.record(z.string(), z.unknown()).optional().describe("Model options from list_generation_models"),
+            ...(media === "video" ? { replace_audio_with: z.string().optional().describe("Audio artifact to splice over the generated video") } : {}),
+        },
+        handler: async (args) => {
+            const model = resolveFor(media, args.model);
+            if (typeof model === "string")
+                return toolError(model);
+            const refs = normalizeRefs(args.refs);
+            const invalid = await validate(engine, model, args, refs);
+            if (invalid)
+                return toolError(invalid);
+            return enqueueGeneration(engine, model, args, refs);
+        },
+    };
+}
+function listDef() {
+    return {
+        name: "list_generation_models",
+        description: "List the image, video and audio generation models with their input roles, modes and options, read from apicity",
+        scope: "global",
+        annotations: { readOnlyHint: true },
+        schema: {
+            media: z.enum(["image", "video", "audio"]).optional().describe("Only models that generate this media"),
+            operation: z.enum(OPERATIONS).optional().describe("Only models that support this operation"),
+            include_hidden: z.boolean().optional().describe("Include provider variants hidden from the picker"),
+        },
+        handler: async (args) => {
+            const models = listModels({
+                ...(typeof args.media === "string" ? { media: args.media } : {}),
+                ...(typeof args.operation === "string" ? { operation: args.operation } : {}),
+                includeHidden: args.include_hidden === true,
+            });
+            return textResult({ models: models.map(modelListing) });
+        },
+    };
+}
+export function generateMediaDefs(engine) {
+    return [generateDef(engine, "image"), generateDef(engine, "video"), generateDef(engine, "audio"), listDef()];
+}

package/dist/tools/generation-payload.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+import { readProviderTaskStatus } from "../provider-task-status.js";
+export function generationPayloadDef(engine) {
+    return {
+        name: "inspect_generation_request",
+        description: "Read the persisted provider request payload, task details, status-page information, and failure info for a single asset. Used by the generating-cell inspector to show what was sent to the provider.",
+        schema: {
+            book_id: z.string().describe("Book id"),
+            asset_id: z.string().describe("Artifact id"),
+        },
+        handler: async (args) => {
+            const { book_id: _book_id, asset_id } = args;
+            const [payloadRes, taskRes, errorRes, providerTask] = await Promise.all([
+                engine.metadata.artifacts.read(asset_id, "generation-payload"),
+                engine.jobs.pending.read(asset_id),
+                engine.jobs.failures.read(asset_id),
+                readProviderTaskStatus(engine, asset_id),
+            ]);
+            const task = taskRes.ok ? taskRes.value : null;
+            const errorRecord = errorRes.ok ? errorRes.value : null;
+            const error = errorRecord
+                ? {
+                    message: errorRecord.message,
+                    failedAt: new Date(errorRecord.failedAt).toISOString(),
+                    ...(errorRecord.failCode !== undefined ? { failCode: errorRecord.failCode } : {}),
+                    ...(errorRecord.prompt !== undefined && errorRecord.prompt !== null ? { prompt: errorRecord.prompt } : {}),
+                }
+                : null;
+            const response = {
+                payload: payloadRes.ok ? payloadRes.value : null,
+                meta: task ? task.meta : null,
+                error,
+                taskType: task ? task.taskType : null,
+                providerTask,
+                task: task
+                    ? {
+                        taskId: task.taskId,
+                        submittedAt: new Date(task.createdAt).toISOString(),
+                        completing: task.completing,
+                    }
+                    : null,
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(response) }],
+            };
+        },
+    };
+}

package/dist/tools/get-timeline.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { readTimeline, timelineSuccess } from "../timeline-helpers.js";
+export function getTimelineDef(engine) {
+    return {
+        name: "get_timeline",
+        description: "Get the selected book's typed v2 timeline",
+        schema: {
+            book_id: z.string().uuid(),
+        },
+        handler: async () => timelineSuccess(readTimeline(engine)),
+    };
+}

package/dist/tools/get-watermark-config.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { effectiveWatermarkProfile, readWatermarkConfig, setAuthenticatedHandle } from "../watermark-config.js";
+import { fetchAuthenticatedXHandle } from "../x/authenticated-handle.js";
+import { WATERMARK_PLATFORMS } from "../watermark-platform.js";
+/**
+ * Return the persisted watermark handle preferences so the chat watermark review can
+ * default to the saved / last-used X handle and list recent handles to pick from.
+ *
+ * `authenticatedHandle` is read-through cached: we try @apicity/x's /2/users/me
+ * live and update the cache on success; on any failure we fall back to the last
+ * cached value (null on first-ever call).
+ */
+export function getWatermarkConfigDef(engine) {
+    return {
+        name: "get_watermark_config",
+        description: "Read the effective watermark profile for TikTok or X, including alias preferences and appearance. A fresh book returns the TikTok profile. The authenticated handle is available only for X.",
+        schema: {
+            book_id: z.string().describe("Book UUID"),
+            platform: z.enum(WATERMARK_PLATFORMS).optional().describe("Alias platform (default tiktok)"),
+        },
+        handler: async (args) => {
+            const { platform = "tiktok" } = args;
+            const cached = await readWatermarkConfig(engine, platform);
+            const live = platform === "x" ? await fetchAuthenticatedXHandle() : null;
+            const authenticatedHandle = live !== null
+                ? (await setAuthenticatedHandle(live, engine)).authenticatedHandle
+                : cached.authenticatedHandle;
+            const config = {
+                ...cached,
+                authenticatedHandle,
+                profile: effectiveWatermarkProfile({ ...cached, authenticatedHandle }, platform),
+            };
+            return {
+                content: [{ type: "text", text: JSON.stringify(config) }],
+            };
+        },
+    };
+}