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

package/lib/API/minimax/ImageToolset.js

@@ -0,0 +1,169 @@
+/**
+ * @file lib/API/minimax/ImageToolset.js
+ * @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.
+ *
+ * @example
+ * import imageToolset from './lib/API/minimax/ImageToolset.js';
+ *
+ * // Use in an agent:
+ * const toolset = agent.getToolset();
+ * toolset.merge(imageToolset);
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as minimax from './image.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   CORE IMAGE GENERATION (Text-to-Image + Image-to-Image)
+   ============================================================ */
+
+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/.',
+  {
+    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"'
+      },
+      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.'
+      },
+      aspect_ratio: {
+        type: 'string',
+        enum: ['1:1', '16:9', '4:3', '3:2', '2:3', '3:4', '9:16', '21:9'],
+        default: '1:1',
+        description: 'Image aspect ratio. Default "1:1" (1024x1024).'
+      },
+      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.'
+      },
+      height: {
+        type: 'integer',
+        description: 'Image height in pixels (same rules as width).'
+      },
+      response_format: {
+        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).'
+      },
+      seed: {
+        type: 'integer',
+        description: 'Random seed for reproducible results. Omit for random seed per image.'
+      },
+      n: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 9,
+        default: 1,
+        description: 'Number of images to generate per request (1-9).'
+      },
+      prompt_optimizer: {
+        type: 'boolean',
+        default: false,
+        description: 'Enable automatic prompt optimization.'
+      },
+      subject_reference: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            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).'
+            }
+          },
+          required: ['type', 'image_file']
+        },
+        description: 'For Image-to-Image generation. Array of subject references (currently supports character portraits).'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional parameters not yet documented.'
+      }
+    },
+    required: ['prompt']
+  },
+  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);
+  }
+);
+
+/* ============================================================
+   HELPER: DIRECT LOCAL SAVE
+   ============================================================ */
+
+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.',
+  {
+    type: 'object',
+    properties: {
+      image_data: {
+        type: 'string',
+        description: 'Either a URL or a base64-encoded image string (with or without data: prefix).'
+      },
+      filename_prefix: {
+        type: 'string',
+        default: 'minimax-image',
+        description: 'Prefix for the generated filename.'
+      },
+      index: {
+        type: 'integer',
+        default: 0,
+        description: 'Index suffix for multiple images (avoids filename collisions).'
+      }
+    },
+    required: ['image_data']
+  },
+  async (params) => {
+    const localPath = await minimax.saveImageToLocal(
+      params.image_data,
+      params.filename_prefix,
+      params.index ?? 0
+    );
+
+    return JSON.stringify({
+      local_path: localPath,
+      note: 'File saved successfully.'
+    });
+  }
+);
+
+export default tools;

package/lib/API/minimax/MusicToolset.js

@@ -0,0 +1,290 @@
+/**
+ * @file lib/API/minimax/MusicToolset.js
+ * @module minimax/MusicToolset
+ * @description Comprehensive ToolSet for the Minimax Music Generation API.
+ *
+ * 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
+ *   - lyrics           → generate, edit or continue song lyrics
+ *
+ * Designed for direct use by AI agents.
+ *
+ * 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.
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as minimax from './music.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   WORKFLOW 1: CREATE MUSIC (Text-to-Music)
+   ============================================================ */
+
+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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of style, mood, and scenario (1–2000 characters). ' +
+                     'Example: "Indie folk, melancholic, introspective, longing, solitary walk, coffee shop"'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Song lyrics using \\n for line breaks. Supports structure tags: ' +
+                     '[Intro], [Verse], [Pre Chorus], [Chorus], [Interlude], [Bridge], [Outro], [Post Chorus], [Transition], [Break], [Hook], [Build Up], [Inst], [Solo]. ' +
+                     'Length: 1–3500 characters. Optional for both instrumental and non-instrumental generation.'
+      },
+      model: {
+        type: 'string',
+        enum: ['music-2.6', 'music-2.6-free'],
+        default: 'music-2.6',
+        description: 'Model to use. "music-2.6" recommended.'
+      },
+      is_instrumental: {
+        type: 'boolean',
+        default: false,
+        description: 'Generate instrumental music (no vocals). Lyrics are still optional.'
+      },
+      lyrics_optimizer: {
+        type: 'boolean',
+        default: false,
+        description: 'Auto-generate lyrics from prompt when lyrics is empty.'
+      },
+      output_format: {
+        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.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['prompt']
+  },
+  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);
+  }
+);
+
+/* ============================================================
+   WORKFLOW 2: CHANGE MUSIC (Cover Generation)
+   ============================================================ */
+
+tools.add(
+  'change_music',
+  'Generate a cover version of a reference song or track. ' +
+  'Uses music-cover or music-cover-free models. ' +
+  '**Strict rules**: Provide exactly ONE of audio_url/audio_base64 (direct one-step) ' +
+  'OR cover_feature_id (two-step from analyze_music). Never both. ' +
+  '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.',
+  {
+    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.'
+      },
+      audio_url: {
+        type: 'string',
+        description: 'Public URL of reference audio for direct one-step cover. ' +
+                     'Mutually exclusive with cover_feature_id.'
+      },
+      audio_base64: {
+        type: 'string',
+        description: 'Base64-encoded reference audio (alternative to audio_url).'
+      },
+      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.'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'New or modified structured lyrics. ' +
+                     'Required/recommended when using cover_feature_id. ' +
+                     'Optional when using direct audio_url (API can extract). ' +
+                     'Optional for both instrumental and non-instrumental covers.'
+      },
+      lyrics_optimizer: {
+        type: 'boolean',
+        default: false,
+        description: 'Auto-optimize lyrics (limited support on cover models).'
+      },
+      is_instrumental: {
+        type: 'boolean',
+        default: false,
+        description: 'Generate instrumental cover.'
+      },
+      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.'
+      },
+      extra: { type: 'object', description: 'Additional parameters.' }
+    },
+    required: ['prompt']
+  },
+  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);
+  }
+);
+
+/* ============================================================
+   WORKFLOW 3: ANALYZE MUSIC (Preprocess for Cover)
+   ============================================================ */
+
+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.',
+  {
+    type: 'object',
+    properties: {
+      audio_url: {
+        type: 'string',
+        description: 'Public URL of the reference audio (6 seconds to 6 minutes, max 50MB).'
+      },
+      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".'
+      }
+    },
+    required: ['audio_url']
+  },
+  async (params) => {
+    const result = await minimax.analyzeMusic(params.audio_url, params);
+
+    return JSON.stringify({
+      cover_feature_id: result.cover_feature_id,
+      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);
+  }
+);
+
+/* ============================================================
+   WORKFLOW 4: LYRICS (Generate / Edit / Snippet)
+   ============================================================ */
+
+tools.add(
+  'lyrics',
+  'Generate, edit, or continue song lyrics.\n\n' +
+  'Behavior depends on the parameters you provide:\n' +
+  '• 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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Theme, style, mood, or editing instruction.\n' +
+                     'Examples:\n' +
+                     '• "Energetic 80s new-wave synth-pop about longing and distant love"\n' +
+                     '• "Make the bridge more emotional and add one final chorus repeat"\n' +
+                     '• "Write a short melancholic verse in the style of Yazoo"'
+      },
+      mode: {
+        type: 'string',
+        enum: ['write_full_song', 'edit'],
+        default: 'write_full_song',
+        description: 'Generation mode.\n' +
+                     '• "write_full_song" = create a full song or a short snippet.\n' +
+                     '• "edit" = modify, continue, or rewrite existing lyrics (requires the lyrics parameter).'
+      },
+      lyrics: {
+        type: 'string',
+        description: 'Existing lyrics to edit or continue.\n' +
+                     'Only used when mode = "edit". ' +
+                     'Can contain structure tags like [Verse], [Chorus], [Bridge], etc.'
+      },
+      title: {
+        type: 'string',
+        description: 'Optional song title. ' +
+                     'If provided, the generated lyrics will keep this exact title.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await minimax.generateLyrics(params.prompt, params);
+    return JSON.stringify({
+      song_title: result.song_title,
+      style_tags: result.style_tags,
+      lyrics: result.lyrics,
+      note: `Lyrics generated using mode: ${params.mode || 'write_full_song'}`
+    }, null, 2);
+  }
+);
+
+export default tools;