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

package/lib/API/minimax/ImageToolset.js

@@ -3,16 +3,15 @@
  * @module minimax/ImageToolset
  * @description Comprehensive ToolSet for the Minimax Image Generation API.
  *
- * This ToolSet exposes the full Minimax Image API with every available option
- * and detailed return values, following the same pattern as lib/genericToolset.js
- * and MusicToolset.js.
- *
- * It is designed to be used directly by AI agents or merged into larger toolsets.
+ * This ToolSet exposes the Minimax Image API with descriptive function-call
+ * schemas and compact, self-describing function responses. Tool responses
+ * preserve durable references such as local paths, temporary image URLs, seeds,
+ * trace IDs, and source image references so the assistant can repeat those
+ * values in a normal assistant message before old raw tool I/O is pruned.
  *
  * @example
  * import imageToolset from './lib/API/minimax/ImageToolset.js';
  *
- * // Use in an agent:
  * const toolset = agent.getToolset();
  * toolset.merge(imageToolset);
  */
@@ -22,6 +21,54 @@ import * as minimax from './image.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);
+}
+
+/**
+ * Build a compact, self-describing Minimax image tool 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 imageToolResponse(tool, params, result) {
+  const imageUrls = Array.isArray(result.image_urls) ? result.image_urls : [];
+  const imageBase64 = Array.isArray(result.image_base64) ? result.image_base64 : [];
+  const localPaths = Array.isArray(result.local_paths) ? result.local_paths : [];
+
+  return json({
+    tool,
+    success: true,
+    trace_id: result.id,
+    prompt: params.prompt,
+    model: params.model || 'image-01',
+    aspect_ratio: params.aspect_ratio || '1:1',
+    response_format: params.response_format || 'url',
+    seed: params.seed,
+    image_urls: imageUrls,
+    image_url: imageUrls[0],
+    image_url_count: imageUrls.length,
+    has_base64_output: imageBase64.length > 0,
+    image_base64_count: imageBase64.length,
+    local_paths: localPaths,
+    local_path: localPaths[0],
+    metadata: result.metadata,
+    duration_ms: result.duration,
+    source_subject_reference: params.subject_reference,
+    note:
+      'Assistant: tell the user the exact local_path/local_paths and, when present, image_url/image_urls, trace_id, and seed in your normal response. ' +
+      'Use local_path as the durable local reference for follow-up file/CDN operations. Minimax image URLs are temporary and may expire.'
+  });
+}
+
 /* ============================================================
    CORE IMAGE GENERATION (Text-to-Image + Image-to-Image)
    ============================================================ */
@@ -29,22 +76,23 @@ const tools = new ToolSet('auto');
 tools.add(
   'generate_image',
   'Generate images using the Minimax Image Generation API. ' +
-  'Supports both Text-to-Image and Image-to-Image (via subject_reference). ' +
-  'All generated images are automatically saved locally in .cache/minimax/.',
+  'Supports both Text-to-Image and Image-to-Image via subject_reference. ' +
+  'All generated images are automatically saved locally in .cache/minimax/. ' +
+  'After success, include the exact local_path/local_paths in your assistant response. ' +
+  'If image_url/image_urls are returned, include them too, but mention they are temporary. ' +
+  'Also preserve trace_id and seed when present for reproducibility or debugging.',
   {
     type: 'object',
     properties: {
       prompt: {
         type: 'string',
-        description: 'Text description of the image, max 1500 characters. ' +
-                     'Example: "A serene mountain landscape at sunset, photorealistic, cinematic lighting"'
+        description: 'Text description of the image, max 1500 characters. Example: "A serene mountain landscape at sunset, photorealistic, cinematic lighting".'
       },
       model: {
         type: 'string',
         enum: ['image-01', 'image-01-live'],
         default: 'image-01',
-        description: 'Model to use. "image-01" = standard (text-to-image and img2img). ' +
-                     '"image-01-live" = optimized for image-to-image.'
+        description: 'Model to use. "image-01" = standard text-to-image and image-to-image. "image-01-live" = optimized for image-to-image.'
       },
       aspect_ratio: {
         type: 'string',
@@ -54,8 +102,7 @@ tools.add(
       },
       width: {
         type: 'integer',
-        description: 'Image width in pixels (512-2048, must be divisible by 8). ' +
-                     'Only effective for model "image-01". aspect_ratio takes priority if both are provided.'
+        description: 'Image width in pixels (512-2048, divisible by 8). Only effective for model "image-01". aspect_ratio takes priority if both are provided.'
       },
       height: {
         type: 'integer',
@@ -65,8 +112,7 @@ tools.add(
         type: 'string',
         enum: ['url', 'base64'],
         default: 'url',
-        description: 'Output format. "url" returns temporary signed links (expire after 24h). ' +
-                     '"base64" returns raw base64 data. Default is "url" (user preference).'
+        description: 'Output format. Prefer "url" where possible. URL links are temporary and expire after about 24 hours. Generated output is also saved to local_path.'
       },
       seed: {
         type: 'integer',
@@ -89,16 +135,19 @@ tools.add(
         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_file: {
               type: 'string',
-              description: 'Reference image URL or Base64 data URL (data:image/jpeg;base64,...). ' +
-                           'Best results with front-facing portrait photos (JPG/PNG < 10MB).'
+              description: 'Reference image URL or Base64 data URL (data:image/jpeg;base64,...). Prefer image_url/public URL where possible. Best results with front-facing portrait photos (JPG/PNG < 10MB).'
             }
           },
           required: ['type', 'image_file']
         },
-        description: 'For Image-to-Image generation. Array of subject references (currently supports character portraits).'
+        description: 'For Image-to-Image generation. Array of subject references. Preserve the exact source image_file in the final assistant response when it matters for follow-up.'
       },
       extra: {
         type: 'object',
@@ -109,18 +158,7 @@ tools.add(
   },
   async (params) => {
     const result = await minimax.requestImage(params.prompt, params);
-
-    return JSON.stringify({
-      image_urls: result.image_urls,
-      image_base64: result.image_base64,
-      local_paths: result.local_paths,
-      metadata: result.metadata,
-      trace_id: result.id,
-      duration_ms: result.duration,
-      raw_response: result.raw,
-      note: 'Images have been automatically saved to local_paths. ' +
-            'Use response_format="base64" if you need the raw data instead of URLs.'
-    }, null, 2);
+    return imageToolResponse('generate_image', params, result);
   }
 );
 
@@ -131,13 +169,14 @@ tools.add(
 tools.add(
   'save_image_to_local',
   'Save image data (URL or base64) to a local file in .cache/minimax/. ' +
-  'Useful when you already have image data from another source or previous generation.',
+  'Useful when you already have image data from another source or previous generation. ' +
+  'After success, include the exact local_path in your assistant response so it remains available after function-call history is pruned.',
   {
     type: 'object',
     properties: {
       image_data: {
         type: 'string',
-        description: 'Either a URL or a base64-encoded image string (with or without data: prefix).'
+        description: 'Either an image URL or a base64-encoded image string (with or without data: prefix). Prefer URL/image_url where possible.'
       },
       filename_prefix: {
         type: 'string',
@@ -159,11 +198,17 @@ tools.add(
       params.index ?? 0
     );
 
-    return JSON.stringify({
+    return json({
+      tool: 'save_image_to_local',
+      success: true,
       local_path: localPath,
-      note: 'File saved successfully.'
+      localPath,
+      filename_prefix: params.filename_prefix || 'minimax-image',
+      index: params.index ?? 0,
+      source_image_data_type: typeof params.image_data === 'string' && params.image_data.startsWith('http') ? 'url' : 'base64',
+      note: 'Assistant: tell the user the exact local_path in your normal response. Use local_path as the durable reference for follow-up file/CDN operations.'
     });
   }
 );
 
-export default tools;
+export default tools;

package/lib/API/minimax/MusicToolset.js

@@ -5,8 +5,8 @@
  *
  * Exposes four clear workflows matching the underlying music.js design:
  *   - create_music     → text-to-music (music-2.6 / music-2.6-free)
- *   - change_music     → cover generation (music-cover) with strict reference rules
- *   - analyze_music    → preprocess reference audio for two-step covers
+ *   - change_music     → cover generation (music-cover) — model fixed to 'music-cover'
+ *   - analyze_music    → preprocess reference audio for two-step covers (model fixed to 'music-cover')
  *   - lyrics           → generate, edit or continue song lyrics
  *
  * Designed for direct use by AI agents.
@@ -14,6 +14,10 @@
  * Important notes:
  * - Lyrics are optional for both instrumental and non-instrumental music generation.
  * - Streaming is not supported; the `stream` parameter is always false and not exposed as an option.
+ * - For change_music and analyze_music: model is fixed to 'music-cover' (recommended paid model).
+ * - For change_music (music-cover models): prompt is strictly limited to 300 characters.
+ * - audio_setting is fixed internally (44100 Hz / 256 kbps / mp3) — not exposed to users.
+ * - **Critical for two-step covers**: When using `cover_feature_id` + non-instrumental (`is_instrumental: false`), the `lyrics` parameter is **mandatory**.
  */
 
 import ToolSet from '../../ToolSet.js';
@@ -21,6 +25,49 @@ import * as minimax from './music.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);
+}
+
+/**
+ * Build a compact, self-describing music-generation tool response.
+ *
+ * The response intentionally keeps durable follow-up references and avoids the
+ * full raw API response so old function-call transcripts can be pruned safely
+ * after the assistant has repeated the important values in normal text.
+ *
+ * @param {string} tool Tool/function name that produced the result.
+ * @param {Record<string, unknown>} params Tool parameters supplied by the model.
+ * @param {{audio_url?: string, local_path?: string, duration?: number}} result Wrapper result.
+ * @param {string} note Assistant-facing preservation note.
+ * @returns {string} Pretty JSON response for function-calling output.
+ */
+function musicToolResponse(tool, params, result, note) {
+  return json({
+    tool,
+    success: true,
+    audio_url: result.audio_url,
+    audioUrl: result.audio_url,
+    local_path: result.local_path,
+    localPath: result.local_path,
+    duration_ms: result.duration,
+    model: tool === 'change_music' ? 'music-cover' : (params.model || 'music-2.6'),
+    prompt: params.prompt,
+    is_instrumental: params.is_instrumental ?? false,
+    output_format: params.output_format || 'url',
+    source_audio_url: params.audio_url,
+    has_audio_base64: Boolean(params.audio_base64),
+    cover_feature_id: params.cover_feature_id,
+    note
+  });
+}
+
 /* ============================================================
    WORKFLOW 1: CREATE MUSIC (Text-to-Music)
    ============================================================ */
@@ -29,8 +76,9 @@ tools.add(
   'create_music',
   'Create original music from a text prompt and optional lyrics. ' +
   'Lyrics are optional for both instrumental and non-instrumental tracks. ' +
-  'Uses music-2.6 or music-2.6-free models. ' +
-  'No reference audio is allowed — this is pure text-to-music generation.',
+  'Uses minimax music-2.6 or music-2.6-free models. ' +
+  'No reference audio is allowed — this is pure text-to-music generation. ' +
+  'After success, include the returned local_path and audio_url exactly in your assistant response; these are needed for download/playback or follow-up audio operations.',
   {
     type: 'object',
     properties: {
@@ -65,16 +113,7 @@ tools.add(
         type: 'string',
         enum: ['url', 'hex'],
         default: 'url',
-        description: 'Output format. Default "url".'
-      },
-      audio_setting: {
-        type: 'object',
-        properties: {
-          sample_rate: { type: 'integer', enum: [16000, 24000, 32000, 44100], default: 44100 },
-          bitrate: { type: 'integer', enum: [32000, 64000, 128000, 256000], default: 256000 },
-          format: { type: 'string', enum: ['mp3', 'wav', 'pcm'], default: 'mp3' }
-        },
-        description: 'Audio output configuration.'
+        description: 'Output format. Default "url". Prefer "url" for durable assistant-visible references.'
       },
       extra: { type: 'object', description: 'Additional parameters.' }
     },
@@ -83,60 +122,71 @@ tools.add(
   async (params) => {
     const result = await minimax.createMusic(params.prompt, params);
 
-    return JSON.stringify({
-      audio_url: result.audio_url,
-      local_path: result.local_path,
-      duration_ms: result.duration,
-      raw_response: result.raw,
-      note: 'Music created successfully with create_music (text-to-music workflow). ' +
-            'Audio saved to local_path.'
-    }, null, 2);
+    return musicToolResponse(
+      'create_music',
+      params,
+      result,
+      'Music created successfully with create_music. Assistant: tell the user the exact local_path and audio_url. Use local_path/audio_url as durable references after raw function-call history is pruned.'
+    );
   }
 );
 
 /* ============================================================
-   WORKFLOW 2: CHANGE MUSIC (Cover Generation)
+   WORKFLOW 2: CHANGE MUSIC (Cover Generation) — MODEL FIXED
    ============================================================ */
 
 tools.add(
   'change_music',
-  'Generate a cover version of a reference song or track. ' +
-  'Uses music-cover or music-cover-free models. ' +
+  'Generate a cover version of a reference song or track with minimax.io. ' +
+  'Uses the music-cover model (fixed — the recommended paid model; music-cover-free is not supported). ' +
   '**Strict rules**: Provide exactly ONE of audio_url/audio_base64 (direct one-step) ' +
   'OR cover_feature_id (two-step from analyze_music). Never both. ' +
+  '**Critical rule**: When using `cover_feature_id` + non-instrumental (`is_instrumental: false`), ' +
+  'the `lyrics` parameter is **MANDATORY**. ' +
   'Lyrics are optional for direct reference (API can extract), required/recommended for cover_feature_id. ' +
-  'Lyrics are optional for both instrumental and non-instrumental covers.',
+  'Lyrics are optional for both instrumental and non-instrumental covers. ' +
+  '**Important**: There are NO dedicated settings or parameters to control how closely the cover stays faithful to the original reference (e.g. no "strength", "fidelity", or "similarity" sliders). ' +
+  'The `prompt` parameter fully controls the degree of adherence to the reference audio. ' +
+  'To stay close to the original, craft detailed (but short) prompts such as:\n' +
+  '- "faithful cover, identical melody and arrangement to the original"\n' +
+  '- "very close vocal and instrumental cover, minimal changes"\n' +
+  '- "exact replica of the reference track"\n' +
+  'Vague prompts may lead to more creative reinterpretations. ' +
+  '**Prompt limit**: Maximum 300 characters (enforced). ' +
+  '**audio_setting**: Fixed internally to 44100 Hz / 256 kbps / mp3 — not configurable. ' +
+  'Model parameter is ignored (always "music-cover"). ' +
+  'After success, include the returned local_path/audio_url and the source audio_url or cover_feature_id exactly in your assistant response.',
   {
     type: 'object',
     properties: {
       prompt: {
         type: 'string',
-        description: 'Target style/mood for the cover (e.g. "same melody but jazz style"). Required.'
-      },
-      model: {
-        type: 'string',
-        enum: ['music-cover', 'music-cover-free'],
-        default: 'music-cover',
-        description: 'Cover model to use.'
+        maxLength: 300,
+        description: 'Target style/mood for the cover AND instructions for fidelity to the reference. ' +
+                     'Examples for staying faithful: "faithful cover, identical melody and arrangement to the original", ' +
+                     '"very close vocal and instrumental cover, minimal changes", "exact replica of the reference track". ' +
+                     'No other parameters control closeness — the prompt is the only control. ' +
+                     'Maximum 300 characters. Required.'
       },
       audio_url: {
         type: 'string',
         description: 'Public URL of reference audio for direct one-step cover. ' +
-                     'Mutually exclusive with cover_feature_id.'
+                     'Mutually exclusive with cover_feature_id. Prefer audio_url where possible because it is assistant-visible and durable.'
       },
       audio_base64: {
         type: 'string',
-        description: 'Base64-encoded reference audio (alternative to audio_url).'
+        description: 'Base64-encoded reference audio (alternative to audio_url). Prefer audio_url where possible.'
       },
       cover_feature_id: {
         type: 'string',
         description: 'Feature ID from analyze_music() for two-step cover with modified lyrics. ' +
-                     'Mutually exclusive with audio_url/audio_base64.'
+                     '**Requires lyrics** when is_instrumental=false. ' +
+                     'Mutually exclusive with audio_url/audio_base64. Include this exact ID in the assistant response when it is used.'
       },
       lyrics: {
         type: 'string',
         description: 'New or modified structured lyrics. ' +
-                     'Required/recommended when using cover_feature_id. ' +
+                     '**MANDATORY** when using cover_feature_id + non-instrumental (`is_instrumental: false`). ' +
                      'Optional when using direct audio_url (API can extract). ' +
                      'Optional for both instrumental and non-instrumental covers.'
       },
@@ -148,22 +198,13 @@ tools.add(
       is_instrumental: {
         type: 'boolean',
         default: false,
-        description: 'Generate instrumental cover.'
+        description: 'Generate instrumental cover. When false + cover_feature_id, lyrics are required.'
       },
       output_format: {
         type: 'string',
         enum: ['url', 'hex'],
         default: 'url',
-        description: 'Output format. Default "url".'
-      },
-      audio_setting: {
-        type: 'object',
-        properties: {
-          sample_rate: { type: 'integer', default: 44100 },
-          bitrate: { type: 'integer', default: 256000 },
-          format: { type: 'string', default: 'mp3' }
-        },
-        description: 'Audio output settings.'
+        description: 'Output format. Default "url". Prefer "url" for durable assistant-visible references.'
       },
       extra: { type: 'object', description: 'Additional parameters.' }
     },
@@ -172,45 +213,38 @@ tools.add(
   async (params) => {
     const result = await minimax.changeMusic(params.prompt, params);
 
-    return JSON.stringify({
-      audio_url: result.audio_url,
-      local_path: result.local_path,
-      duration_ms: result.duration,
-      raw_response: result.raw,
-      note: params.cover_feature_id
-        ? 'Two-step cover generated using cover_feature_id (from analyze_music). ' +
-          'Lyrics were applied. Audio saved to local_path.'
-        : 'Direct one-step cover generated using audio_url/audio_base64. ' +
-          'Audio saved to local_path.'
-    }, null, 2);
+    return musicToolResponse(
+      'change_music',
+      params,
+      result,
+      params.cover_feature_id
+        ? 'Two-step cover generated using cover_feature_id. Assistant: tell the user the exact cover_feature_id, local_path, and audio_url. Use local_path/audio_url as durable references after pruning.'
+        : 'Direct one-step cover generated using audio_url/audio_base64. Assistant: tell the user the exact source_audio_url when available, plus local_path and audio_url for the generated cover.'
+    );
   }
 );
 
 /* ============================================================
-   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover)
+   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover) — MODEL FIXED
    ============================================================ */
 
 tools.add(
   'analyze_music',
   'Preprocess a reference audio file to extract voice features, structure, and lyrics. ' +
   'This is the first step of the advanced two-step cover workflow. ' +
-  'Returns a cover_feature_id that can be used with change_music for lyric modifications.',
+  'Returns a cover_feature_id that can be used with change_music for lyric modifications. ' +
+  'Model is fixed to "music-cover". ' +
+  'After success, include the exact cover_feature_id, trace_id, and source audio_url in your assistant response; cover_feature_id is valid for 24 hours and is required for follow-up two-step cover calls.',
   {
     type: 'object',
     properties: {
       audio_url: {
         type: 'string',
-        description: 'Public URL of the reference audio (6 seconds to 6 minutes, max 50MB).'
+        description: 'Public URL of the reference audio (6 seconds to 6 minutes, max 50MB). Prefer audio_url where possible.'
       },
       audio_base64: {
         type: 'string',
-        description: 'Base64-encoded reference audio (alternative to audio_url).'
-      },
-      model: {
-        type: 'string',
-        enum: ['music-cover'],
-        default: 'music-cover',
-        description: 'Must be "music-cover".'
+        description: 'Base64-encoded reference audio (alternative to audio_url). Prefer audio_url where possible.'
       }
     },
     required: ['audio_url']
@@ -218,16 +252,21 @@ tools.add(
   async (params) => {
     const result = await minimax.analyzeMusic(params.audio_url, params);
 
-    return JSON.stringify({
+    return json({
+      tool: 'analyze_music',
+      success: true,
       cover_feature_id: result.cover_feature_id,
+      coverFeatureId: result.cover_feature_id,
+      source_audio_url: params.audio_url,
+      has_audio_base64: Boolean(params.audio_base64),
       formatted_lyrics: result.formatted_lyrics,
       structure_result: result.structure_result,
       audio_duration_seconds: result.audio_duration,
       trace_id: result.trace_id,
-      raw_response: result.raw,
-      note: 'Use this cover_feature_id with change_music for two-step covers with custom lyrics. ' +
-            'Valid for 24 hours. Same audio always returns the same ID.'
-    }, null, 2);
+      model: 'music-cover',
+      expires_in: '24 hours',
+      note: 'Assistant: tell the user the exact cover_feature_id and trace_id. Use cover_feature_id with change_music for two-step covers with custom lyrics. Preserve the exact source_audio_url if present.'
+    });
   }
 );
 
@@ -242,7 +281,8 @@ tools.add(
   '• mode = "write_full_song" (default) + no existing lyrics → creates a complete song with title, style tags, and full structured lyrics.\n' +
   '• Short prompt only → generates a short snippet, hook, verse, or chorus idea.\n' +
   '• mode = "edit" + existing lyrics → edits, rewrites, continues, or modifies the provided lyrics.\n' +
-  '• title parameter → keeps the specified song title in the output.',
+  '• title parameter → keeps the specified song title in the output.\n\n' +
+  'After success, include the exact song_title and generated lyrics in your assistant response if they are needed for create_music or change_music follow-up calls.',
   {
     type: 'object',
     properties: {
@@ -278,13 +318,19 @@ tools.add(
   },
   async (params) => {
     const result = await minimax.generateLyrics(params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'lyrics',
+      success: true,
       song_title: result.song_title,
+      songTitle: result.song_title,
       style_tags: result.style_tags,
       lyrics: result.lyrics,
-      note: `Lyrics generated using mode: ${params.mode || 'write_full_song'}`
-    }, null, 2);
+      mode: params.mode || 'write_full_song',
+      title: params.title,
+      prompt: params.prompt,
+      note: 'Assistant: preserve the exact song_title, style_tags, and lyrics in your normal response if they are needed for follow-up create_music/change_music calls.'
+    });
   }
 );
 
-export default tools;
+export default tools;