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

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;

package/lib/API/minimax/VideoToolset.js

@@ -0,0 +1,296 @@
+/**
+ * @file lib/API/minimax/VideoToolset.js
+ * @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.
+ *
+ * It is designed to be used directly by AI agents or merged into larger toolsets.
+ *
+ * Video generation is asynchronous. The main `generate_video` tool automatically
+ * waits for completion and downloads the MP4 to .cache/minimax/.
+ *
+ * @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 * as minimax from './video.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   CORE VIDEO GENERATION (Full async flow with auto-download)
+   ============================================================ */
+
+tools.add(
+  'generate_video',
+  '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.',
+  {
+    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]"'
+      },
+      model: {
+        type: 'string',
+        enum: [
+          'MiniMax-Hailuo-2.3',
+          'MiniMax-Hailuo-02',
+          'T2V-01-Director',
+          'T2V-01',
+          'MiniMax-Hailuo-2.3-Fast',
+          'I2V-01-Director',
+          'I2V-01-live',
+          'I2V-01',
+          '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.'
+      },
+      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.'
+      },
+      last_frame_image: {
+        type: 'string',
+        description: 'Public URL or data: URL of the last frame image (for First & Last Frame mode only).'
+      },
+      subject_reference: {
+        type: 'array',
+        items: {
+          type: 'object',
+          properties: {
+            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).'
+            }
+          },
+          required: ['type', 'image']
+        },
+        description: 'For Subject-Reference to Video (S2V-01 model). Array of character references.'
+      },
+      prompt_optimizer: {
+        type: 'boolean',
+        default: true,
+        description: 'Automatically optimize the prompt. Default true.'
+      },
+      fast_pretreatment: {
+        type: 'boolean',
+        default: false,
+        description: 'Reduces optimization time when prompt_optimizer is enabled (Hailuo models only).'
+      },
+      duration: {
+        type: 'integer',
+        enum: [6, 10],
+        default: 6,
+        description: 'Video duration in seconds. Available values depend on model and resolution.'
+      },
+      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.'
+      },
+      max_wait_ms: {
+        type: 'integer',
+        default: 300000,
+        description: 'Maximum wait time for polling (default 5 minutes).'
+      },
+      poll_interval_ms: {
+        type: 'integer',
+        default: 5000,
+        description: 'Polling interval in milliseconds (default 5 seconds).'
+      },
+      extra: {
+        type: 'object',
+        description: 'Additional parameters not yet documented.'
+      }
+    },
+    required: ['prompt']
+  },
+  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);
+  }
+);
+
+/* ============================================================
+   LOW-LEVEL: CREATE TASK ONLY
+   ============================================================ */
+
+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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Text description of the video.'
+      },
+      model: {
+        type: 'string',
+        default: 'MiniMax-Hailuo-2.3',
+        description: 'Video model to use.'
+      },
+      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.'
+      }
+    },
+    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
+    );
+
+    return JSON.stringify({
+      local_path: localPath,
+      note: 'Video file saved successfully.'
+    });
+  }
+);
+
+export default tools;