@j-o-r/hello-dave 0.1.1 → 0.1.5

package/lib/API/openai.com/videoToolset.js

@@ -0,0 +1,616 @@
+/**
+ * @file lib/API/openai.com/videoToolset.js
+ * @module openai.com/videoToolset
+ * @description ToolSet wrapper for the OpenAI video API wrapper.
+ *
+ * Exposes OpenAI video operations as function-call tools:
+ * - create_video_openai
+ * - retrieve_video_openai
+ * - list_videos_openai
+ * - download_video_openai
+ * - delete_video_openai
+ * - edit_video_openai
+ * - extend_video_openai
+ * - remix_video_openai
+ * - emergency_poll_video_openai
+ * - create_character_openai
+ * - fetch_character_openai
+ *
+ * For video creation with a visual reference, prefer `image_url`. The handler
+ * maps `image_url` to the wrapper's `input_reference: { image_url }` shape.
+ * Use `file_id` only when a URL/data URL is not available.
+ *
+ * @see ./video.js for the underlying implementation and full JSDoc.
+ * @see ./video.create.md
+ * @see ./video.retrieve.md
+ * @see ./video.download.md
+ * @see ./video.edit.md
+ * @see ./video.extend.md
+ * @see ./video.remix.md
+ * @see ./video.list.md
+ * @see ./video.delete.md
+ * @see ./video.create.character.md
+ * @see ./video.fetch.character.md
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as openaiVideo from './video.js';
+
+const tools = new ToolSet('auto');
+
+/**
+ * Supported downloadable video asset variants.
+ * @typedef {'video'|'thumbnail'|'spritesheet'} VideoAssetVariant
+ */
+
+/**
+ * JSON-serializable summary returned for downloaded media content.
+ * @typedef {Object} DownloadSummary
+ * @property {string} contentType - Response content type.
+ * @property {number} bytes - Number of downloaded bytes.
+ * @property {string} [local_path] - Local saved file path when available.
+ */
+
+/**
+ * Extract a compact, JSON-safe summary from a downloaded media result.
+ * Avoids serializing raw Buffer bytes into tool responses.
+ * @param {{contentType?: string, bytes?: number, local_path?: string}} [content] - Download result from video.js.
+ * @returns {DownloadSummary|undefined} JSON-safe media summary.
+ */
+function summarizeContent(content) {
+  if (!content) return undefined;
+  return {
+    contentType: content.contentType,
+    bytes: content.bytes,
+    local_path: content.local_path
+  };
+}
+
+/**
+ * Return an object copy without raw binary content buffers.
+ * @param {Record<string, *>} value - API response object.
+ * @returns {Record<string, *>} JSON-safe response object.
+ */
+function withoutRawBuffers(value) {
+  if (!value || typeof value !== 'object') return value;
+  const copy = { ...value };
+  if (copy.content) copy.content = summarizeContent(copy.content);
+  if (copy.buffer) delete copy.buffer;
+  return copy;
+}
+
+/**
+ * Stringify a tool response with stable two-space formatting.
+ * @param {Record<string, *>} payload - Response payload.
+ * @returns {string} JSON string for function-call response.
+ */
+function json(payload) {
+  return JSON.stringify(payload, null, 2);
+}
+
+/**
+ * Build the OpenAI create-video options object from tool parameters.
+ * Prefers `image_url` over `file_id` for `input_reference` when both are present.
+ * @param {Record<string, *>} params - Tool parameters.
+ * @returns {Record<string, *>} Options for createVideo().
+ */
+function buildCreateOptions(params) {
+  const options = { ...params };
+  delete options.prompt;
+  delete options.image_url;
+  delete options.file_id;
+
+  if (params.image_url) {
+    options.input_reference = { image_url: params.image_url };
+  } else if (params.file_id) {
+    options.input_reference = { file_id: params.file_id };
+  }
+
+  return options;
+}
+
+/**
+ * Download the final video asset for a completed video response when requested.
+ * @param {Record<string, *>} video - Completed video response.
+ * @param {Record<string, *>} params - Tool parameters.
+ * @returns {Promise<Record<string, *>>} Video response with optional JSON-safe content summary.
+ */
+async function maybeDownloadCompletedVideo(video, params) {
+  if (!params.download) return withoutRawBuffers(video);
+
+  const content = await openaiVideo.downloadVideoContent(video.id, {
+    variant: params.variant || 'video',
+    save: true,
+    filenamePrefix: params.filenamePrefix || 'openai-video',
+    userAgent: params.userAgent
+  });
+
+  return withoutRawBuffers({ ...video, content });
+}
+
+/* ============================================================
+   CREATE VIDEO
+   ============================================================ */
+
+tools.add(
+  'create_video_openai',
+  'Create an OpenAI Sora video from a text prompt and wait until the job completes. ' +
+  'Optionally provide a visual reference via image_url; this is strongly preferred over file_id and is mapped to input_reference.image_url. ' +
+  'Use a public HTTPS image URL or base64 data URL for image_url. ' +
+  'Returns the completed video metadata including id; that id is the videoId for retrieve/download/edit/extend/remix/delete. ' +
+  'Set download=true to save the completed MP4 locally under .cache/openai/. Video generation can take several minutes.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Text prompt describing the video to generate. Be specific about subject, motion, camera movement, style, lighting, and scene changes.'
+      },
+      image_url: {
+        type: 'string',
+        description: 'Preferred optional visual reference: fully-qualified image URL or base64 data URL. Internally mapped to input_reference.image_url.'
+      },
+      file_id: {
+        type: 'string',
+        description: 'Optional OpenAI file id for an image reference. Use only when image_url is not available.'
+      },
+      model: {
+        type: 'string',
+        default: 'sora-2',
+        description: 'Video model. Common values: sora-2, sora-2-pro.'
+      },
+      seconds: {
+        type: 'string',
+        enum: ['4', '8', '12'],
+        default: '4',
+        description: 'Clip duration in seconds. Allowed values: 4, 8, 12.'
+      },
+      size: {
+        type: 'string',
+        enum: ['720x1280', '1280x720', '1024x1792', '1792x1024'],
+        default: '720x1280',
+        description: 'Output resolution as width x height.'
+      },
+      download: {
+        type: 'boolean',
+        default: false,
+        description: 'When true, download and save the completed video locally after generation.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Asset variant to download when download=true.'
+      },
+      filenamePrefix: {
+        type: 'string',
+        default: 'openai-video',
+        description: 'Local filename prefix when download=true.'
+      },
+      maxWaitMs: {
+        type: 'integer',
+        default: 600000,
+        description: 'Maximum polling time in milliseconds. Default: 600000 (10 minutes).'
+      },
+      pollIntervalMs: {
+        type: 'integer',
+        default: 5000,
+        description: 'Delay between polling requests in milliseconds. Default: 5000.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await openaiVideo.createVideo(params.prompt, buildCreateOptions(params));
+    return json({
+      ...withoutRawBuffers(result),
+      videoId: result.id,
+      note: 'Video created successfully with create_video_openai. Use videoId for follow-up tools.'
+    });
+  }
+);
+
+/* ============================================================
+   RETRIEVE / LIST
+   ============================================================ */
+
+tools.add(
+  'retrieve_video_openai',
+  'Retrieve the latest metadata for an OpenAI video job. Use this to check status, progress, expiry, prompt, size, seconds, and model. Requires videoId.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'OpenAI video id. This is the id returned by create_video_openai or list_videos_openai.'
+      }
+    },
+    required: ['videoId']
+  },
+  async (params) => {
+    const result = await openaiVideo.retrieveVideo(params.videoId, params);
+    return json({
+      ...withoutRawBuffers(result),
+      videoId: result.id,
+      note: 'Video metadata retrieved successfully with retrieve_video_openai.'
+    });
+  }
+);
+
+tools.add(
+  'list_videos_openai',
+  'List recently generated OpenAI videos for the current project. Use this to discover existing videoId values for download, retrieve, edit, extend, remix, or delete.',
+  {
+    type: 'object',
+    properties: {
+      after: {
+        type: 'string',
+        description: 'Pagination cursor: id of the last item from the previous page.'
+      },
+      limit: {
+        type: 'integer',
+        minimum: 1,
+        description: 'Maximum number of videos to retrieve.'
+      },
+      order: {
+        type: 'string',
+        enum: ['asc', 'desc'],
+        description: 'Sort order by timestamp.'
+      }
+    }
+  },
+  async (params) => {
+    const query = {
+      after: params.after,
+      limit: params.limit,
+      order: params.order
+    };
+    const result = await openaiVideo.listVideos(query, params);
+    return json({
+      ...result,
+      videoIds: Array.isArray(result.data) ? result.data.map(video => video.id).filter(Boolean) : [],
+      note: 'Videos listed successfully with list_videos_openai. Each item id is a usable videoId.'
+    });
+  }
+);
+
+/* ============================================================
+   DOWNLOAD / DELETE
+   ============================================================ */
+
+tools.add(
+  'download_video_openai',
+  'Download generated OpenAI video bytes or a preview asset. By default saves the MP4 locally under .cache/openai/ and returns local_path, contentType, and byte count. Requires a completed videoId.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'OpenAI video id to download. The video should be completed.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Which downloadable asset to return. Defaults to MP4 video.'
+      },
+      save: {
+        type: 'boolean',
+        default: true,
+        description: 'Save downloaded bytes to .cache/openai/. Defaults to true for tool usage.'
+      },
+      filenamePrefix: {
+        type: 'string',
+        default: 'openai-video',
+        description: 'Local filename prefix when save=true.'
+      }
+    },
+    required: ['videoId']
+  },
+  async (params) => {
+    const result = await openaiVideo.downloadVideoContent(params.videoId, {
+      ...params,
+      save: params.save !== false,
+      variant: params.variant || 'video',
+      filenamePrefix: params.filenamePrefix || 'openai-video'
+    });
+
+    return json({
+      videoId: params.videoId,
+      ...summarizeContent(result),
+      note: 'Video content downloaded successfully with download_video_openai.'
+    });
+  }
+);
+
+tools.add(
+  'delete_video_openai',
+  'Permanently delete a completed or failed OpenAI video and its stored assets. Requires videoId. Use carefully; this cannot be undone.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'OpenAI video id to delete.'
+      }
+    },
+    required: ['videoId']
+  },
+  async (params) => {
+    const result = await openaiVideo.deleteVideo(params.videoId, params);
+    return json({
+      ...result,
+      videoId: result.id,
+      note: 'Video deleted successfully with delete_video_openai.'
+    });
+  }
+);
+
+/* ============================================================
+   EDIT / EXTEND / REMIX
+   ============================================================ */
+
+tools.add(
+  'edit_video_openai',
+  'Create a new OpenAI video by editing a completed source video. Requires source videoId and an edit prompt. Returns the new completed video id. Optionally downloads the result locally.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'Completed source OpenAI video id to edit.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Natural-language edit instruction describing how to change the source video.'
+      },
+      download: {
+        type: 'boolean',
+        default: false,
+        description: 'When true, download and save the edited video locally after completion.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Asset variant to download when download=true.'
+      },
+      maxWaitMs: {
+        type: 'integer',
+        default: 600000,
+        description: 'Maximum polling time in milliseconds.'
+      },
+      pollIntervalMs: {
+        type: 'integer',
+        default: 5000,
+        description: 'Delay between polling requests in milliseconds.'
+      }
+    },
+    required: ['videoId', 'prompt']
+  },
+  async (params) => {
+    const result = await openaiVideo.editVideo(params.videoId, params.prompt, params);
+    const finalResult = await maybeDownloadCompletedVideo(result, params);
+    return json({
+      ...finalResult,
+      sourceVideoId: params.videoId,
+      videoId: result.id,
+      note: 'Video edited successfully with edit_video_openai. The returned videoId is the new edited video.'
+    });
+  }
+);
+
+tools.add(
+  'extend_video_openai',
+  'Create an extension of a completed OpenAI video. Requires source videoId, prompt, and optional seconds for the new segment. Returns the new completed video id. Optionally downloads the result locally.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'Completed source OpenAI video id to extend.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Prompt directing the continuation/extension generation.'
+      },
+      seconds: {
+        type: 'string',
+        enum: ['4', '8', '12', '16', '20'],
+        default: '4',
+        description: 'Length of the newly generated extension segment in seconds.'
+      },
+      download: {
+        type: 'boolean',
+        default: false,
+        description: 'When true, download and save the extended video locally after completion.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Asset variant to download when download=true.'
+      },
+      maxWaitMs: {
+        type: 'integer',
+        default: 600000,
+        description: 'Maximum polling time in milliseconds.'
+      },
+      pollIntervalMs: {
+        type: 'integer',
+        default: 5000,
+        description: 'Delay between polling requests in milliseconds.'
+      }
+    },
+    required: ['videoId', 'prompt']
+  },
+  async (params) => {
+    const result = await openaiVideo.extendVideo(params.videoId, params.prompt, params.seconds || '4', params);
+    const finalResult = await maybeDownloadCompletedVideo(result, params);
+    return json({
+      ...finalResult,
+      sourceVideoId: params.videoId,
+      videoId: result.id,
+      note: 'Video extended successfully with extend_video_openai. The returned videoId is the new extended video.'
+    });
+  }
+);
+
+tools.add(
+  'remix_video_openai',
+  'Create a remix of a completed OpenAI video using a refreshed prompt. Requires source videoId and prompt. Returns the new completed video id. Optionally downloads the result locally.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'Completed source OpenAI video id to remix.'
+      },
+      prompt: {
+        type: 'string',
+        description: 'Updated prompt that directs the remix generation.'
+      },
+      download: {
+        type: 'boolean',
+        default: false,
+        description: 'When true, download and save the remixed video locally after completion.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Asset variant to download when download=true.'
+      },
+      maxWaitMs: {
+        type: 'integer',
+        default: 600000,
+        description: 'Maximum polling time in milliseconds.'
+      },
+      pollIntervalMs: {
+        type: 'integer',
+        default: 5000,
+        description: 'Delay between polling requests in milliseconds.'
+      }
+    },
+    required: ['videoId', 'prompt']
+  },
+  async (params) => {
+    const result = await openaiVideo.remixVideo(params.videoId, params.prompt, params);
+    const finalResult = await maybeDownloadCompletedVideo(result, params);
+    return json({
+      ...finalResult,
+      sourceVideoId: params.videoId,
+      videoId: result.id,
+      note: 'Video remixed successfully with remix_video_openai. The returned videoId is the new remixed video.'
+    });
+  }
+);
+
+/* ============================================================
+   EMERGENCY POLLING
+   ============================================================ */
+
+tools.add(
+  'emergency_poll_video_openai',
+  'Continue polling an OpenAI video job after a previous generation/edit/extend/remix timeout. Requires videoId from the original job or thrown timeout metadata. Defaults are long and conservative. Optionally downloads the final asset.',
+  {
+    type: 'object',
+    properties: {
+      videoId: {
+        type: 'string',
+        description: 'OpenAI video id to continue polling.'
+      },
+      maxWaitMs: {
+        type: 'integer',
+        default: 3600000,
+        description: 'Maximum polling time in milliseconds. Default: 3600000 (1 hour).'
+      },
+      pollIntervalMs: {
+        type: 'integer',
+        default: 30000,
+        description: 'Delay between polling requests in milliseconds. Default: 30000.'
+      },
+      download: {
+        type: 'boolean',
+        default: false,
+        description: 'When true, download and save final media after completion.'
+      },
+      variant: {
+        type: 'string',
+        enum: ['video', 'thumbnail', 'spritesheet'],
+        default: 'video',
+        description: 'Asset variant to download when download=true.'
+      },
+      filenamePrefix: {
+        type: 'string',
+        default: 'openai-video',
+        description: 'Local filename prefix when download=true.'
+      }
+    },
+    required: ['videoId']
+  },
+  async (params) => {
+    const result = await openaiVideo.emergencyPollVideo(params.videoId, params);
+    return json({
+      ...withoutRawBuffers(result),
+      videoId: result.id,
+      note: 'Emergency polling completed successfully with emergency_poll_video_openai.'
+    });
+  }
+);
+
+/* ============================================================
+   CHARACTERS
+   ============================================================ */
+
+tools.add(
+  'create_character_openai',
+  'Create an OpenAI video character/cameo from an uploaded video. This endpoint requires a video file input, so image_url is not applicable here.',
+  {
+    type: 'object',
+    properties: {
+      name: {
+        type: 'string',
+        description: 'Display name for the character.'
+      },
+      video_path: {
+        type: 'string',
+        description: 'Local path to a video file to upload for character creation.'
+      }
+    },
+    required: ['name', 'video_path']
+  },
+  async (params) => {
+    const result = await openaiVideo.createCharacter(params.name, params.video_path, params);
+    return json({
+      ...result,
+      characterId: result.id,
+      note: 'Character created successfully with create_character_openai. Use characterId with fetch_character_openai.'
+    });
+  }
+);
+
+tools.add(
+  'fetch_character_openai',
+  'Fetch an OpenAI video character/cameo by characterId.',
+  {
+    type: 'object',
+    properties: {
+      characterId: {
+        type: 'string',
+        description: 'OpenAI video character id returned by create_character_openai.'
+      }
+    },
+    required: ['characterId']
+  },
+  async (params) => {
+    const result = await openaiVideo.fetchCharacter(params.characterId, params);
+    return json({
+      ...result,
+      characterId: result.id,
+      note: 'Character fetched successfully with fetch_character_openai.'
+    });
+  }
+);
+
+export default tools;