@j-o-r/hello-dave 0.1.0 → 0.1.4

package/lib/API/minimax/VideoToolset.js

@@ -3,46 +3,169 @@
  * @module minimax/VideoToolset
  * @description Comprehensive ToolSet for the Minimax Video Generation API.
  *
- * This ToolSet exposes the full Minimax Video API with every available option
- * and detailed return values, following the same pattern as lib/genericToolset.js,
- * MusicToolset.js, and ImageToolset.js.
+ * This ToolSet exposes the Minimax Video API with descriptive function-call
+ * schemas and compact, self-describing function responses. Tool responses
+ * preserve durable follow-up references such as task_id, file_id, video_url,
+ * local_path, source image URLs, model, mode, dimensions, and status so the
+ * assistant can repeat those values in a normal assistant message before old
+ * raw tool I/O is pruned.
  *
- * It is designed to be used directly by AI agents or merged into larger toolsets.
+ * Video generation is asynchronous. The main `generate_video_minimax` tool
+ * automatically waits for completion and downloads the MP4 to .cache/minimax/.
  *
- * Video generation is asynchronous. The main `generate_video` tool automatically
- * waits for completion and downloads the MP4 to .cache/minimax/.
+ * IMPORTANT: `wait_for_video_ready_minimax` is an emergency / last-chance tool.
+ * Use it only when `generate_video_minimax` has timed out. Timeout errors from
+ * the wrapper include the `task_id` so the task can be polled later.
+ *
+ * ============================================================
+ * CLEAR MODEL ↔ MODE MAPPING (enforced by the underlying video.js wrapper)
+ * ============================================================
+ * | Mode                  | Supported Models                                      | Required Fields             |
+ * |-----------------------|-------------------------------------------------------|-----------------------------|
+ * | Text-to-Video         | MiniMax-Hailuo-2.3, MiniMax-Hailuo-02, T2V-01-*       | prompt                      |
+ * | Image-to-Video        | MiniMax-Hailuo-2.3 / 2.3-Fast / 02, I2V-01-*          | first_frame_image           |
+ * | First & Last Frame    | MiniMax-Hailuo-02 ONLY                                | last_frame_image            |
+ * | Subject-Reference     | S2V-01 ONLY                                           | subject_reference           |
+ *
+ * IMAGE REFERENCE RULES:
+ * - `first_frame_image`, `last_frame_image`, and all images inside
+ *   `subject_reference` MUST be public HTTP/HTTPS URLs.
+ * - Base64 / data: URLs are explicitly NOT supported and are rejected by the
+ *   underlying wrapper before the API call.
  *
  * @example
  * import videoToolset from './lib/API/minimax/VideoToolset.js';
  *
- * // Use in an agent:
  * const toolset = agent.getToolset();
  * toolset.merge(videoToolset);
  */
 
-import ToolSet  from '../../ToolSet.js';
+import ToolSet from '../../ToolSet.js';
 import * as minimax from './video.js';
 
 const tools = new ToolSet('auto');
 
+/**
+ * Serialize a tool response as pretty JSON.
+ *
+ * @param {Record<string, unknown>} value Response payload to serialize.
+ * @returns {string} Pretty JSON response for function-calling output.
+ */
+function json(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+/**
+ * Infer the Minimax video mode from submitted parameters.
+ *
+ * @param {Record<string, unknown>} params Tool parameters.
+ * @returns {'text'|'image'|'first-last'|'subject'} Inferred mode.
+ */
+function inferMode(params) {
+  if (params.last_frame_image) return 'first-last';
+  if (params.subject_reference) return 'subject';
+  if (params.first_frame_image) return 'image';
+  return 'text';
+}
+
+/**
+ * Return the first subject-reference image URL, if present.
+ *
+ * @param {unknown} subjectReference Subject reference parameter.
+ * @returns {string|undefined} First subject image URL.
+ */
+function firstSubjectImageUrl(subjectReference) {
+  if (!Array.isArray(subjectReference)) return undefined;
+  const first = subjectReference[0];
+  if (!first || !Array.isArray(first.image)) return undefined;
+  return first.image[0];
+}
+
+/**
+ * Build a compact, self-describing Minimax video generation response.
+ *
+ * @param {string} tool Tool/function name that produced the response.
+ * @param {Record<string, unknown>} params Original tool parameters.
+ * @param {Record<string, unknown>} result Wrapper result object.
+ * @returns {string} JSON response containing durable references and assistant instructions.
+ */
+function videoGenerationResponse(tool, params, result) {
+  const mode = inferMode(params);
+
+  return json({
+    tool,
+    success: true,
+    mode,
+    prompt: params.prompt,
+    model: params.model || (mode === 'subject' ? 'S2V-01' : mode === 'first-last' ? 'MiniMax-Hailuo-02' : 'MiniMax-Hailuo-2.3'),
+    task_id: result.task_id,
+    taskId: result.task_id,
+    file_id: result.file_id,
+    fileId: result.file_id,
+    video_url: result.video_url,
+    videoUrl: result.video_url,
+    local_path: result.local_path,
+    localPath: result.local_path,
+    video_width: result.video_width,
+    video_height: result.video_height,
+    duration_seconds: params.duration || 6,
+    resolution: params.resolution,
+    total_duration_ms: result.duration,
+    first_frame_image: params.first_frame_image,
+    last_frame_image: params.last_frame_image,
+    subject_reference: params.subject_reference,
+    subject_image_url: firstSubjectImageUrl(params.subject_reference),
+    note:
+      'Assistant: tell the user the exact task_id, file_id, local_path, and video_url in your normal response. ' +
+      'Use local_path as the durable saved MP4 reference for follow-up file/CDN operations. ' +
+      'Use task_id for later polling/debugging, file_id for file retrieval, and video_url only while the provider download URL remains valid. ' +
+      'If first_frame_image, last_frame_image, or subject_reference was used, repeat the exact source URL(s) when relevant.'
+  });
+}
+
+/**
+ * Build a compact, self-describing Minimax video polling response.
+ *
+ * @param {Record<string, unknown>} params Tool parameters.
+ * @param {Record<string, unknown>} result Wrapper result object.
+ * @returns {string} JSON response containing status and follow-up references.
+ */
+function videoPollingResponse(params, result) {
+  return json({
+    tool: 'wait_for_video_ready_minimax',
+    success: true,
+    task_id: result.task_id || params.task_id,
+    taskId: result.task_id || params.task_id,
+    status: result.status,
+    file_id: result.file_id,
+    fileId: result.file_id,
+    video_width: result.video_width,
+    video_height: result.video_height,
+    note:
+      'Assistant: tell the user the exact task_id, status, and file_id when present in your normal response. ' +
+      'If status is Success, use file_id for retrieval/download follow-up. If status is not Success, keep task_id for later polling.'
+  });
+}
+
 /* ============================================================
    CORE VIDEO GENERATION (Full async flow with auto-download)
    ============================================================ */
 
 tools.add(
-  'generate_video',
+  'generate_video_minimax',
   'Generate a video using the Minimax Video Generation API. ' +
   'Supports Text-to-Video, Image-to-Video, First & Last Frame, and Subject-Reference modes. ' +
   'Automatically polls until the video is ready, then downloads the MP4 to .cache/minimax/. ' +
-  'This is the recommended high-level tool for video generation.',
+  'This is the recommended high-level tool for video generation. ' +
+  'After success, include the exact task_id, file_id, local_path, and video_url in your assistant response. ' +
+  'The local_path is the durable saved MP4 reference; video_url may be temporary. ' +
+  'The underlying wrapper enforces model↔mode mapping and strict public-URL validation for all image references. Base64/data: URLs are rejected.',
   {
     type: 'object',
     properties: {
       prompt: {
         type: 'string',
-        description: 'Text description of the video, up to 2000 characters. ' +
-                     'Supports camera movement commands in [brackets] for supported models. ' +
-                     'Example: "A cute cat jumping on a wooden table [Static shot]"'
+        description: 'Text description of the video, up to 2000 characters. Supports camera movement commands in [brackets] for supported models. Example: "A cute cat jumping on a wooden table [Static shot]". Camera commands: [Truck left/right], [Pan left/right], [Push in/out], [Pedestal up/down], [Tilt up/down], [Zoom in/out], [Shake], [Tracking shot], [Static shot].'
       },
       model: {
         type: 'string',
@@ -58,35 +181,35 @@ tools.add(
           'S2V-01'
         ],
         default: 'MiniMax-Hailuo-2.3',
-        description: 'Video generation model. ' +
-                     '"MiniMax-Hailuo-2.3" = recommended for text-to-video and image-to-video. ' +
-                     '"MiniMax-Hailuo-02" = good for first-last frame. ' +
-                     '"S2V-01" = subject reference mode.'
+        description: 'Video generation model. The wrapper validates compatibility with the detected mode. Recommended defaults: Text-to-Video → MiniMax-Hailuo-2.3; Image-to-Video → MiniMax-Hailuo-2.3; First & Last Frame → MiniMax-Hailuo-02; Subject-Reference → S2V-01.'
       },
       first_frame_image: {
         type: 'string',
-        description: 'Public URL or data: URL of the first frame image (for Image-to-Video or First-Last mode). ' +
-                     'Formats: JPG, JPEG, PNG, WebP. Size < 20MB. Short side > 300px.'
+        description: 'PUBLIC HTTP/HTTPS image_url ONLY (no Base64/data URLs). URL of the first frame image for Image-to-Video or First-Last mode. Preserve this exact URL in the assistant response when relevant.'
       },
       last_frame_image: {
         type: 'string',
-        description: 'Public URL or data: URL of the last frame image (for First & Last Frame mode only).'
+        description: 'PUBLIC HTTP/HTTPS image_url ONLY (no Base64/data URLs). URL of the last frame image for First & Last Frame mode only; requires model MiniMax-Hailuo-02. Preserve this exact URL in the assistant response when relevant.'
       },
       subject_reference: {
         type: 'array',
         items: {
           type: 'object',
           properties: {
-            type: { type: 'string', enum: ['character'], description: 'Subject type. Currently only "character" supported.' },
+            type: {
+              type: 'string',
+              enum: ['character'],
+              description: 'Subject type. Currently only "character" supported.'
+            },
             image: {
               type: 'array',
               items: { type: 'string' },
-              description: 'Array of reference image URLs (usually one image).'
+              description: 'Array containing exactly one public HTTP/HTTPS image_url. Base64/data URLs are not supported. Preserve exact subject image URL(s) in the assistant response when relevant.'
             }
           },
           required: ['type', 'image']
         },
-        description: 'For Subject-Reference to Video (S2V-01 model). Array of character references.'
+        description: 'For Subject-Reference to Video (S2V-01 model only). Each reference must contain exactly one public HTTP/HTTPS image URL.'
       },
       prompt_optimizer: {
         type: 'boolean',
@@ -107,12 +230,7 @@ tools.add(
       resolution: {
         type: 'string',
         enum: ['512P', '720P', '768P', '1080P'],
-        description: 'Video resolution. Options depend on model and duration. ' +
-                     'Example: "768P" or "1080P".'
-      },
-      callback_url: {
-        type: 'string',
-        description: 'Optional callback URL for async status updates.'
+        description: 'Video resolution. Options depend on model and duration. Examples: "768P" or "1080P".'
       },
       max_wait_ms: {
         type: 'integer',
@@ -133,164 +251,49 @@ tools.add(
   },
   async (params) => {
     const result = await minimax.generateVideo(params.prompt, params);
-
-    return JSON.stringify({
-      task_id: result.task_id,
-      file_id: result.file_id,
-      video_url: result.video_url,
-      local_path: result.local_path,
-      video_width: result.video_width,
-      video_height: result.video_height,
-      total_duration_ms: result.duration,
-      raw_responses: result.raw,
-      note: 'Video has been automatically saved to local_path. ' +
-            'The generation was polled until completion. Use max_wait_ms to adjust timeout.'
-    }, null, 2);
+    return videoGenerationResponse('generate_video_minimax', params, result);
   }
 );
 
 /* ============================================================
-   LOW-LEVEL: CREATE TASK ONLY
+   EMERGENCY / LAST-CHANCE POLLING TOOL
    ============================================================ */
 
 tools.add(
-  'create_video_task',
-  'Create a video generation task without waiting. ' +
-  'Returns a task_id that can be polled manually with query_video_task. ' +
-  'Useful for advanced workflows or when using callbacks.',
+  'wait_for_video_ready_minimax',
+  'EMERGENCY / LAST-CHANCE tool to poll a video generation task that timed out during generate_video_minimax. ' +
+  'Use this only as a last resort when the main generation call has already timed out. ' +
+  'It continues polling until the video is ready (Success), fails, or max_wait_ms is reached. ' +
+  'After success or timeout recovery, include the exact task_id, status, and file_id when present in your assistant response.',
   {
     type: 'object',
     properties: {
-      prompt: {
+      task_id: {
         type: 'string',
-        description: 'Text description of the video.'
+        description: 'The minimax task_id returned by a previous generate_video_minimax call or timeout error. Required. Preserve this exact task_id in the assistant response.'
       },
-      model: {
-        type: 'string',
-        default: 'MiniMax-Hailuo-2.3',
-        description: 'Video model to use.'
+      max_wait_ms: {
+        type: 'integer',
+        default: 300000,
+        description: 'Maximum additional wait time for this emergency poll (default 5 minutes).'
       },
-      first_frame_image: { type: 'string' },
-      last_frame_image: { type: 'string' },
-      subject_reference: { type: 'array' },
-      prompt_optimizer: { type: 'boolean', default: true },
-      duration: { type: 'integer', default: 6 },
-      resolution: { type: 'string' },
-      callback_url: { type: 'string' },
-      extra: { type: 'object' }
-    },
-    required: ['prompt']
-  },
-  async (params) => {
-    const result = await minimax.createVideoGenerationTask(params.prompt, params);
-
-    return JSON.stringify({
-      task_id: result.task_id,
-      duration_ms: result.duration,
-      raw_response: result.raw,
-      note: 'Use query_video_task with this task_id to check status.'
-    }, null, 2);
-  }
-);
-
-/* ============================================================
-   LOW-LEVEL: QUERY TASK STATUS
-   ============================================================ */
-
-tools.add(
-  'query_video_task',
-  'Query the current status of a video generation task. ' +
-  'Returns status (Preparing, Queueing, Processing, Success, Fail) and file_id when ready.',
-  {
-    type: 'object',
-    properties: {
-      task_id: {
-        type: 'string',
-        description: 'The task_id returned by create_video_task or generate_video.'
+      poll_interval_ms: {
+        type: 'integer',
+        default: 5000,
+        description: 'Polling interval in milliseconds (default 5 seconds).'
       }
     },
     required: ['task_id']
   },
   async (params) => {
-    const result = await minimax.queryVideoGenerationTask(params.task_id);
-
-    return JSON.stringify({
-      task_id: result.task_id,
-      status: result.status,
-      file_id: result.file_id,
-      video_width: result.video_width,
-      video_height: result.video_height,
-      raw_response: result.raw,
-      note: 'Poll this until status === "Success" to get the file_id.'
-    }, null, 2);
-  }
-);
-
-/* ============================================================
-   LOW-LEVEL: RETRIEVE FILE
-   ============================================================ */
-
-tools.add(
-  'retrieve_video_file',
-  'Retrieve the download URL and metadata for a completed video using its file_id.',
-  {
-    type: 'object',
-    properties: {
-      file_id: {
-        type: 'string',
-        description: 'The file_id returned when a video task reaches Success status.'
-      }
-    },
-    required: ['file_id']
-  },
-  async (params) => {
-    const result = await minimax.retrieveVideoFile(params.file_id);
-
-    return JSON.stringify({
-      file_id: result.file_id,
-      filename: result.filename,
-      download_url: result.download_url,
-      bytes: result.bytes,
-      raw_response: result.raw,
-      note: 'Use save_video_to_local with the download_url to download the file.'
-    }, null, 2);
-  }
-);
-
-/* ============================================================
-   HELPER: DIRECT LOCAL SAVE
-   ============================================================ */
-
-tools.add(
-  'save_video_to_local',
-  'Save a video from a download URL to a local file in .cache/minimax/. ' +
-  'Useful when you already have a download_url from retrieve_video_file.',
-  {
-    type: 'object',
-    properties: {
-      video_url: {
-        type: 'string',
-        description: 'Public download URL of the video (from retrieve_video_file).'
-      },
-      filename_prefix: {
-        type: 'string',
-        default: 'minimax-video',
-        description: 'Prefix for the generated filename.'
-      }
-    },
-    required: ['video_url']
-  },
-  async (params) => {
-    const localPath = await minimax.saveVideoToLocal(
-      params.video_url,
-      params.filename_prefix
+    const result = await minimax.waitForVideoReady(
+      params.task_id,
+      params.max_wait_ms ?? 300000,
+      params.poll_interval_ms ?? 5000
     );
 
-    return JSON.stringify({
-      local_path: localPath,
-      note: 'Video file saved successfully.'
-    });
+    return videoPollingResponse(params, result);
   }
 );
 
-export default tools;
+export default tools;

package/lib/API/minimax/image.js

@@ -14,6 +14,9 @@
  *
  *              For publishing generated or reference files to a remote CDN,
  *              use the reusable `lib/cdn.js` module instead.
+ *
+ *              Supports both Text-to-Image and Image-to-Image (subject reference) via the same endpoint.
+ *              Generated images are automatically saved locally to .cache/minimax/ as PNG.
  */
 
 import { request as doRequest } from '@j-o-r/apiserver';
@@ -92,7 +95,7 @@ async function saveImageToLocal(imageData, filenamePrefix = 'minimax-image', ind
  * Supports all models, parameters, and response formats.
  *
  * @param {string} prompt - Text description of the image, max 1500 characters.
- * @param {Object} [options] - All available options from the official spec.
+ * @param {Object} [options={}] - All available options from the official spec.
  *
  * @param {string} [options.model='image-01'] - Model to use.
  *   Supported values:
@@ -101,6 +104,7 @@ async function saveImageToLocal(imageData, filenamePrefix = 'minimax-image', ind
  *
  * @param {string} [options.aspect_ratio='1:1'] - Image aspect ratio.
  *   Options: '1:1', '16:9', '4:3', '3:2', '2:3', '3:4', '9:16', '21:9'
+ *   (aspect_ratio takes priority over explicit width/height)
  *
  * @param {number} [options.width] - Image width in px (512-2048, divisible by 8).
  *   Only effective for model 'image-01'. aspect_ratio takes priority if both provided.