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

package/lib/API/stability.ai/ImageToolset.js

@@ -37,6 +37,17 @@ import * as stability 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);
+}
+
+
 /* ============================================================
    GENERATE: ULTRA
    ============================================================ */
@@ -45,7 +56,8 @@ tools.add(
   'generate_ultra',
   'Generate the highest quality photorealistic image using Stability AI\'s Stable Image Ultra model. ' +
   'Best for professional, highly detailed, realistic results. Supports text-to-image and image-to-image. ' +
-  'Automatically handles polling for async generations.',
+  'Automatically handles polling for async generations. ' +
+  'After success, include the exact returned local_path and seed in your assistant response so the generated image remains referenceable after old tool calls are pruned.',
   {
     type: 'object',
     properties: {
@@ -88,12 +100,18 @@ tools.add(
   },
   async (params) => {
     const result = await stability.generateUltra(params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'generate_ultra',
+      success: true,
       local_path: result.local_path,
+      localPath: result.local_path,
+      source_image_url: params.image_url,
+      prompt: params.prompt,
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: 'Image generated with generate_ultra. Saved to local_path.'
-    }, null, 2);
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact local_path and seed. Use local_path as the durable reference for follow-up image editing or publishing.'
+    });
   }
 );
 
@@ -103,7 +121,8 @@ tools.add(
 
 tools.add(
   'generate_core',
-  'Fast and affordable image generation using Stable Image Core. Good for quick ideation and iteration.',
+  'Fast and affordable image generation using Stable Image Core. Good for quick ideation and iteration. ' +
+  'After success, include the exact returned local_path and seed in your assistant response so the generated image remains referenceable after old tool calls are pruned.',
   {
     type: 'object',
     properties: {
@@ -117,12 +136,17 @@ tools.add(
   },
   async (params) => {
     const result = await stability.generateCore(params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'generate_core',
+      success: true,
       local_path: result.local_path,
+      localPath: result.local_path,
+      prompt: params.prompt,
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: 'Image generated with generate_core.'
-    }, null, 2);
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact local_path and seed. Use local_path as the durable reference for follow-up image editing or publishing.'
+    });
   }
 );
 
@@ -132,7 +156,8 @@ tools.add(
 
 tools.add(
   'generate_sd3',
-  'Generate images using Stable Diffusion 3.5 models (Large, Large Turbo, Medium, Flash).',
+  'Generate images using Stable Diffusion 3.5 models (Large, Large Turbo, Medium, Flash). ' +
+  'After success, include the exact returned local_path and seed in your assistant response so the generated image remains referenceable after old tool calls are pruned.',
   {
     type: 'object',
     properties: {
@@ -150,12 +175,20 @@ tools.add(
   },
   async (params) => {
     const result = await stability.generateSD3(params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'generate_sd3',
+      success: true,
       local_path: result.local_path,
+      localPath: result.local_path,
+      source_image_url: params.image_url,
+      prompt: params.prompt,
+      model: params.model || 'sd3.5-large',
+      mode: params.mode || 'text-to-image',
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: 'Image generated with generate_sd3.'
-    }, null, 2);
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact local_path and seed. Use local_path as the durable reference for follow-up image editing or publishing.'
+    });
   }
 );
 
@@ -165,7 +198,8 @@ tools.add(
 
 tools.add(
   'upscale_conservative',
-  'Upscale an image to 4MP while preserving original details as much as possible.',
+  'Upscale an image to 4MP while preserving original details as much as possible. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -178,12 +212,18 @@ tools.add(
   },
   async (params) => {
     const result = await stability.upscaleConservative(params.image_url, params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'upscale_conservative',
+      success: true,
+      source_image_url: params.image_url,
       local_path: result.local_path,
+      localPath: result.local_path,
+      prompt: params.prompt,
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: 'Image upscaled with upscale_conservative.'
-    }, null, 2);
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -193,7 +233,8 @@ tools.add(
 
 tools.add(
   'edit_erase',
-  'Remove unwanted objects or areas from an image using a mask or alpha channel.',
+  'Remove unwanted objects or areas from an image using a mask or alpha channel. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -207,11 +248,18 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editErase(params.image_url, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_erase',
+      success: true,
+      source_image_url: params.image_url,
+      mask_url: params.mask_url,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Objects erased with edit_erase.'
-    }, null, 2);
+      seed: result.seed,
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -221,7 +269,8 @@ tools.add(
 
 tools.add(
   'edit_inpaint',
-  'Fill or replace areas in an image using a prompt. Supports search mode (auto-segment) or explicit mask.',
+  'Fill or replace areas in an image using a prompt. Supports search mode (auto-segment) or explicit mask. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -237,11 +286,20 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editInpaint(params.image_url, params.prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_inpaint',
+      success: true,
+      source_image_url: params.image_url,
+      mask_url: params.mask_url,
+      prompt: params.prompt,
+      search_prompt: params.search_prompt,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Inpainting completed with edit_inpaint.'
-    }, null, 2);
+      seed: result.seed,
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -251,7 +309,8 @@ tools.add(
 
 tools.add(
   'edit_outpaint',
-  'Expand an image by generating new content in any direction (left, right, up, down).',
+  'Expand an image by generating new content in any direction (left, right, up, down). ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -267,11 +326,19 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editOutpaint(params.image_url, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_outpaint',
+      success: true,
+      source_image_url: params.image_url,
+      expansion: { left: params.left || 0, right: params.right || 0, up: params.up || 0, down: params.down || 0 },
+      prompt: params.prompt,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Image expanded with edit_outpaint.'
-    }, null, 2);
+      seed: result.seed,
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -281,7 +348,8 @@ tools.add(
 
 tools.add(
   'edit_search_and_replace',
-  'Automatically find an object using search_prompt and replace it with new content from prompt.',
+  'Automatically find an object using search_prompt and replace it with new content from prompt. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -294,11 +362,19 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editSearchAndReplace(params.image_url, params.prompt, params.search_prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_search_and_replace',
+      success: true,
+      source_image_url: params.image_url,
+      prompt: params.prompt,
+      search_prompt: params.search_prompt,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Search and replace completed.'
-    }, null, 2);
+      seed: result.seed,
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -308,7 +384,8 @@ tools.add(
 
 tools.add(
   'edit_search_and_recolor',
-  'Automatically find an object and change its color according to the prompt.',
+  'Automatically find an object and change its color according to the prompt. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -321,11 +398,19 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editSearchAndRecolor(params.image_url, params.prompt, params.select_prompt, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_search_and_recolor',
+      success: true,
+      source_image_url: params.image_url,
+      prompt: params.prompt,
+      select_prompt: params.select_prompt,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Search and recolor completed.'
-    }, null, 2);
+      seed: result.seed,
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 
@@ -335,7 +420,8 @@ tools.add(
 
 tools.add(
   'edit_remove_background',
-  'Accurately segment the foreground and remove the background from an image.',
+  'Accurately segment the foreground and remove the background from an image. ' +
+  'After success, include the exact source image_url and returned local_path in your assistant response so follow-up edits can use the correct image.',
   {
     type: 'object',
     properties: {
@@ -346,11 +432,16 @@ tools.add(
   },
   async (params) => {
     const result = await stability.editRemoveBackground(params.image_url, params);
-    return JSON.stringify({
+    return json({
+      tool: 'edit_remove_background',
+      success: true,
+      source_image_url: params.image_url,
       local_path: result.local_path,
+      localPath: result.local_path,
       finish_reason: result.finish_reason,
-      note: 'Background removed successfully.'
-    }, null, 2);
+      output_format: params.output_format || 'png',
+      note: 'Assistant: tell the user the exact source_image_url and new local_path. Use local_path for further edits or publishing.'
+    });
   }
 );
 

package/lib/API/stability.ai/MusicToolset.js

@@ -3,10 +3,13 @@
  * @module stability.ai/MusicToolset
  * @description Comprehensive ToolSet for the Stability AI Stable Audio 3 API.
  *
+ * **MP3 ONLY MODE** — All tools accept and produce MP3 audio only.
+ * This restriction avoids large file upload issues and improves reliability.
+ *
  * Exposes three primary high-level tools that wrap the underlying `audio.js` implementation:
  *   - text_to_audio   → Pure text-to-audio generation using the `stable-audio-3` model
- *   - audio_to_audio  → Transform / style-transfer an existing audio clip using a text prompt
- *   - inpaint         → Replace a specific timed section of an audio file using a text prompt + mask
+ *   - audio_to_audio  → Transform / style-transfer an existing **MP3** audio clip using a text prompt
+ *   - inpaint         → Replace a specific timed section of an **MP3** audio file using a text prompt + mask
  *
  * All tools handle asynchronous generation internally (submit → poll until ready).
  * The result is only returned once the audio file is successfully generated and saved locally.
@@ -15,12 +18,17 @@
  * Each tool includes rich, LLM-friendly descriptions, full JSON schemas with constraints,
  * defaults, and practical guidance so an LLM can reliably decide when and how to call them.
  *
+ * **Important MP3-Only Rules**:
+ * - Input audio (for audio_to_audio and inpaint) **must be MP3** (.mp3 extension).
+ * - Output is always MP3.
+ * - WAV or other formats will be rejected with a clear error.
+ *
  * Key Stable Audio 3 Facts (for LLMs):
  * - Model: `stable-audio-3` (fixed)
  * - Cost: Flat 26 credits per successful generation (not charged on failure)
  * - Max duration: 380 seconds (default 190s)
- * - Output: 44.1 kHz stereo, mp3 (default) or wav
- * - Input audio must be 6–380 seconds long
+ * - Output: 44.1 kHz stereo, **mp3 only**
+ * - Input audio must be 6–380 seconds long and **MP3 format**
  * - Prompts must be in English; no copyrighted material
  * - Polling is fully automatic — you do not need to call fetch_result manually
  *
@@ -33,6 +41,17 @@ import * as stability from './audio.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);
+}
+
+
 /* ============================================================
    WORKFLOW 1: TEXT-TO-AUDIO
    ============================================================ */
@@ -44,7 +63,8 @@ tools.add(
   'No reference audio is required. ' +
   'The function submits the request, automatically polls the server until the audio is ready (usually 30–90 seconds), ' +
   'and returns a JSON object containing the local file path to the generated audio. ' +
-  'Supports up to 380 seconds of 44.1 kHz stereo audio. Flat cost of 26 credits per successful generation.',
+  'After success, include the exact returned local_path and seed in your assistant response so the generated MP3 remains referenceable after old tool calls are pruned. ' +
+  '**Output is always MP3.** Supports up to 380 seconds of 44.1 kHz stereo audio. Flat cost of 26 credits per successful generation.',
   {
     type: 'object',
     properties: {
@@ -65,14 +85,6 @@ tools.add(
                      'Must be between 1 and 380. Default is 190 seconds (about 3 minutes 10 seconds). ' +
                      'Longer durations consume the same 26 credits but take slightly longer to generate.'
       },
-      output_format: {
-        type: 'string',
-        enum: ['mp3', 'wav'],
-        default: 'mp3',
-        description: 'Desired output audio format. ' +
-                     '"mp3" (default) for smaller file size and broad compatibility. ' +
-                     '"wav" for lossless quality (larger files).'
-      },
       seed: {
         type: 'number',
         description: 'Optional random seed for reproducible results. ' +
@@ -104,13 +116,20 @@ tools.add(
   async (params) => {
     const result = await stability.textToAudio(params.prompt, params);
 
-    return JSON.stringify({
+    return json({
+      tool: 'text_to_audio',
+      success: true,
       local_path: result.local_path,
+      localPath: result.local_path,
+      prompt: params.prompt,
+      duration: params.duration || 190,
       finish_reason: result.finish_reason,
       seed: result.seed,
       x_request_id: result.x_request_id,
-      note: 'Audio generated successfully with text_to_audio using Stable Audio 3. Saved to local_path. 26 credits used.'
-    }, null, 2);
+      output_format: 'mp3',
+      credits: 26,
+      note: 'Assistant: tell the user the exact local_path and seed. Use local_path as the durable MP3 reference for follow-up audio tools or publishing.'
+    });
   }
 );
 
@@ -120,12 +139,13 @@ tools.add(
 
 tools.add(
   'audio_to_audio',
-  'Transform or reinterpret an existing audio file according to a new text prompt using Stable Audio 3\'s audio-to-audio capability. ' +
-  'The model takes the reference audio as a starting point and applies the prompt to change style, genre, instruments, mood, etc., ' +
+  'Transform or reinterpret an existing **MP3** audio file according to a new text prompt using Stable Audio 3\'s audio-to-audio capability. ' +
+  'The model takes the reference **MP3** audio as a starting point and applies the prompt to change style, genre, instruments, mood, etc., ' +
   'while preserving some of the original structure and timing. ' +
   'Use the `strength` parameter to control how much the original audio influences the result. ' +
-  'Supports remote URLs (auto-downloaded) or local file paths. ' +
-  'Automatically handles polling and returns the transformed audio when ready. Flat 26 credits per successful generation.',
+  '**Input must be MP3** (local path or URL ending in .mp3). Output is always MP3. ' +
+  'Automatically handles polling and returns the transformed audio when ready. Flat 26 credits per successful generation. ' +
+  'After success, include the exact source audio reference and returned local_path in your assistant response so follow-up audio edits use the correct MP3.',
   {
     type: 'object',
     properties: {
@@ -137,15 +157,15 @@ tools.add(
       },
       audio_url: {
         type: 'string',
-        description: 'Public HTTP/HTTPS URL to a reference audio file (mp3 or wav recommended). ' +
-                     'The file must be between 6 and 380 seconds long. ' +
-                     'The system will automatically download it and set the correct MIME type. ' +
+        description: 'Public HTTP/HTTPS URL to a reference **MP3** audio file. ' +
+                     'The file must be between 6 and 380 seconds long and end with .mp3. ' +
+                     'The system will automatically download it. ' +
                      'Alternative to audio_path.'
       },
       audio_path: {
         type: 'string',
-        description: 'Local filesystem path to the reference audio file. ' +
-                     'Alternative to audio_url. Must be a valid readable audio file (6–380 seconds).'
+        description: 'Local filesystem path to the reference **MP3** audio file. ' +
+                     'Alternative to audio_url. Must be a valid readable .mp3 file (6–380 seconds).'
       },
       duration: {
         type: 'number',
@@ -165,12 +185,6 @@ tools.add(
                      '1.0 = output has almost no influence from the input (full transformation). ' +
                      'Typical useful range: 0.5–0.9.'
       },
-      output_format: {
-        type: 'string',
-        enum: ['mp3', 'wav'],
-        default: 'mp3',
-        description: 'Output format: "mp3" (default) or "wav".'
-      },
       seed: {
         type: 'number',
         description: 'Optional seed for reproducibility (0–4294967294).'
@@ -198,12 +212,23 @@ tools.add(
 
     const result = await stability.audioToAudio(params.prompt, audioInput, params);
 
-    return JSON.stringify({
+    return json({
+      tool: 'audio_to_audio',
+      success: true,
+      source_audio_url: params.audio_url,
+      source_audio_path: params.audio_path || params.audio,
       local_path: result.local_path,
+      localPath: result.local_path,
+      prompt: params.prompt,
+      duration: params.duration || 190,
+      strength: params.strength ?? 1,
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: 'Audio transformed successfully with audio_to_audio. Saved to local_path. 26 credits used.'
-    }, null, 2);
+      x_request_id: result.x_request_id,
+      output_format: 'mp3',
+      credits: 26,
+      note: 'Assistant: tell the user the exact source audio reference and new local_path. Use local_path as the durable MP3 reference for follow-up audio tools or publishing.'
+    });
   }
 );
 
@@ -213,11 +238,12 @@ tools.add(
 
 tools.add(
   'inpaint',
-  'Regenerate or replace a specific time-based section of an existing audio file using a text prompt and a mask. ' +
+  'Regenerate or replace a specific time-based section of an existing **MP3** audio file using a text prompt and a mask. ' +
   'Perfect for fixing mistakes, changing a verse/chorus, adding a bridge, extending a section, or creative remixing. ' +
   'You define the start and end time (in seconds) of the region to inpaint. ' +
   'The model keeps the audio outside the mask and generates new content inside it that matches the prompt. ' +
-  'Supports remote URLs or local paths. Automatic polling included. Flat 26 credits per successful generation.',
+  '**Input must be MP3**. Output is always MP3. Supports remote URLs or local paths. Automatic polling included. Flat 26 credits per successful generation. ' +
+  'After success, include the exact source audio reference, mask range, and returned local_path in your assistant response so follow-up audio edits use the correct MP3.',
   {
     type: 'object',
     properties: {
@@ -229,11 +255,11 @@ tools.add(
       },
       audio_url: {
         type: 'string',
-        description: 'Public URL of the reference audio file to edit. Must be 6–380 seconds long.'
+        description: 'Public URL of the reference **MP3** audio file to edit. Must be 6–380 seconds long and end with .mp3.'
       },
       audio_path: {
         type: 'string',
-        description: 'Local path to the reference audio file to edit.'
+        description: 'Local path to the reference **MP3** audio file to edit.'
       },
       mask_start: {
         type: 'number',
@@ -258,12 +284,6 @@ tools.add(
         default: 190,
         description: 'Total duration of the final output audio in seconds.'
       },
-      output_format: {
-        type: 'string',
-        enum: ['mp3', 'wav'],
-        default: 'mp3',
-        description: 'Output format.'
-      },
       seed: {
         type: 'number',
         description: 'Optional seed for reproducibility.'
@@ -290,12 +310,24 @@ tools.add(
 
     const result = await stability.inpaint(params.prompt, audioInput, params);
 
-    return JSON.stringify({
+    return json({
+      tool: 'inpaint',
+      success: true,
+      source_audio_url: params.audio_url,
+      source_audio_path: params.audio_path || params.audio,
       local_path: result.local_path,
+      localPath: result.local_path,
+      prompt: params.prompt,
+      mask_start: params.mask_start ?? 30,
+      mask_end: params.mask_end ?? 380,
+      duration: params.duration || 190,
       finish_reason: result.finish_reason,
       seed: result.seed,
-      note: `Inpaint completed successfully. Replaced section ${params.mask_start ?? 30}s–${params.mask_end ?? 380}s. Saved to local_path. 26 credits used.`
-    }, null, 2);
+      x_request_id: result.x_request_id,
+      output_format: 'mp3',
+      credits: 26,
+      note: 'Assistant: tell the user the exact source audio reference, mask_start/mask_end, and new local_path. Use local_path as the durable MP3 reference for follow-up audio tools or publishing.'
+    });
   }
 );