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

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

@@ -0,0 +1,357 @@
+/**
+ * @file lib/API/stability.ai/ImageToolset.js
+ * @module stability.ai/ImageToolset
+ * @description Comprehensive ToolSet for the Stability AI Stable Image API (v2beta).
+ *
+ * Exposes high-level tools that wrap the underlying `image.js` implementation:
+ *   - generate_ultra
+ *   - generate_core
+ *   - generate_sd3
+ *   - upscale_conservative
+ *   - edit_erase
+ *   - edit_inpaint
+ *   - edit_outpaint
+ *   - edit_search_and_replace
+ *   - edit_search_and_recolor
+ *   - edit_remove_background
+ *
+ * All tools handle asynchronous generation internally (submit → poll until ready).
+ * The result is only returned once the image file is successfully generated and saved locally.
+ *
+ * Designed specifically for AI agents, LLMs, and function-calling systems.
+ * Each tool includes rich, LLM-friendly descriptions, full JSON schemas with constraints,
+ * defaults, and practical guidance.
+ *
+ * Key Stable Image Facts (for LLMs):
+ * - Output formats: png (default), jpeg, webp
+ * - Max image size: ~9.4 million pixels total
+ * - Content moderation is strict (public figures, copyrighted material, etc.)
+ * - Many operations cost between 2–60 credits
+ *
+ * @see ./image.js for the underlying implementation
+ * @see ./image.md for the full API specification
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as stability from './image.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   GENERATE: ULTRA
+   ============================================================ */
+
+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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Detailed English prompt describing the desired image. Max 10,000 characters.'
+      },
+      negative_prompt: {
+        type: 'string',
+        description: 'What you do NOT want to see in the image.'
+      },
+      aspect_ratio: {
+        type: 'string',
+        enum: ['1:1', '16:9', '9:16', '21:9', '9:21', '2:3', '3:2', '4:5', '5:4'],
+        default: '1:1',
+        description: 'Aspect ratio of the output image.'
+      },
+      image_url: {
+        type: 'string',
+        description: 'Optional reference image URL for image-to-image generation.'
+      },
+      strength: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        description: 'Denoising strength for image-to-image (required when using image_url).'
+      },
+      output_format: {
+        type: 'string',
+        enum: ['png', 'jpeg', 'webp'],
+        default: 'png',
+        description: 'Output image format.'
+      },
+      seed: {
+        type: 'number',
+        description: 'Optional seed for reproducibility.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await stability.generateUltra(params.prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      seed: result.seed,
+      note: 'Image generated with generate_ultra. Saved to local_path.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   GENERATE: CORE
+   ============================================================ */
+
+tools.add(
+  'generate_core',
+  'Fast and affordable image generation using Stable Image Core. Good for quick ideation and iteration.',
+  {
+    type: 'object',
+    properties: {
+      prompt: { type: 'string', description: 'Detailed English prompt.' },
+      negative_prompt: { type: 'string' },
+      aspect_ratio: { type: 'string', enum: ['1:1', '16:9', '9:16', '21:9', '9:21', '2:3', '3:2', '4:5', '5:4'], default: '1:1' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' },
+      seed: { type: 'number' }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await stability.generateCore(params.prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      seed: result.seed,
+      note: 'Image generated with generate_core.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   GENERATE: SD3
+   ============================================================ */
+
+tools.add(
+  'generate_sd3',
+  'Generate images using Stable Diffusion 3.5 models (Large, Large Turbo, Medium, Flash).',
+  {
+    type: 'object',
+    properties: {
+      prompt: { type: 'string', description: 'Detailed English prompt.' },
+      mode: { type: 'string', enum: ['text-to-image', 'image-to-image'], default: 'text-to-image' },
+      model: { type: 'string', enum: ['sd3.5-large', 'sd3.5-large-turbo', 'sd3.5-medium', 'sd3.5-flash'], default: 'sd3.5-large' },
+      image_url: { type: 'string' },
+      strength: { type: 'number', minimum: 0, maximum: 1 },
+      aspect_ratio: { type: 'string', enum: ['1:1', '16:9', '9:16', '21:9', '9:21', '2:3', '3:2', '4:5', '5:4'], default: '1:1' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' },
+      cfg_scale: { type: 'number' },
+      seed: { type: 'number' }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await stability.generateSD3(params.prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      seed: result.seed,
+      note: 'Image generated with generate_sd3.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   UPSCALE: CONSERVATIVE
+   ============================================================ */
+
+tools.add(
+  'upscale_conservative',
+  'Upscale an image to 4MP while preserving original details as much as possible.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string', description: 'URL of the image to upscale.' },
+      prompt: { type: 'string', description: 'Description of the desired output.' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' },
+      creativity: { type: 'number', minimum: 0.2, maximum: 0.5, default: 0.35 }
+    },
+    required: ['image_url', 'prompt']
+  },
+  async (params) => {
+    const result = await stability.upscaleConservative(params.image_url, params.prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      seed: result.seed,
+      note: 'Image upscaled with upscale_conservative.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: ERASE
+   ============================================================ */
+
+tools.add(
+  'edit_erase',
+  'Remove unwanted objects or areas from an image using a mask or alpha channel.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      mask_url: { type: 'string' },
+      grow_mask: { type: 'number', default: 5 },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' },
+      seed: { type: 'number' }
+    },
+    required: ['image_url']
+  },
+  async (params) => {
+    const result = await stability.editErase(params.image_url, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Objects erased with edit_erase.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: INPAINT
+   ============================================================ */
+
+tools.add(
+  'edit_inpaint',
+  'Fill or replace areas in an image using a prompt. Supports search mode (auto-segment) or explicit mask.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      prompt: { type: 'string', description: 'What the replaced area should become.' },
+      mode: { type: 'string', enum: ['mask', 'search'], default: 'search' },
+      search_prompt: { type: 'string', description: 'Object to find and replace (when mode=search).' },
+      mask_url: { type: 'string' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' },
+      seed: { type: 'number' }
+    },
+    required: ['image_url', 'prompt']
+  },
+  async (params) => {
+    const result = await stability.editInpaint(params.image_url, params.prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Inpainting completed with edit_inpaint.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: OUTPAINT
+   ============================================================ */
+
+tools.add(
+  'edit_outpaint',
+  'Expand an image by generating new content in any direction (left, right, up, down).',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      left: { type: 'number', default: 0 },
+      right: { type: 'number', default: 0 },
+      up: { type: 'number', default: 0 },
+      down: { type: 'number', default: 0 },
+      prompt: { type: 'string' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' }
+    },
+    required: ['image_url']
+  },
+  async (params) => {
+    const result = await stability.editOutpaint(params.image_url, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Image expanded with edit_outpaint.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: SEARCH AND REPLACE
+   ============================================================ */
+
+tools.add(
+  'edit_search_and_replace',
+  'Automatically find an object using search_prompt and replace it with new content from prompt.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      prompt: { type: 'string' },
+      search_prompt: { type: 'string', description: 'Short description of the object to replace.' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' }
+    },
+    required: ['image_url', 'prompt', 'search_prompt']
+  },
+  async (params) => {
+    const result = await stability.editSearchAndReplace(params.image_url, params.prompt, params.search_prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Search and replace completed.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: SEARCH AND RECOLOR
+   ============================================================ */
+
+tools.add(
+  'edit_search_and_recolor',
+  'Automatically find an object and change its color according to the prompt.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      prompt: { type: 'string', description: 'Desired new color description.' },
+      select_prompt: { type: 'string', description: 'Object to recolor.' },
+      output_format: { type: 'string', enum: ['png', 'jpeg', 'webp'], default: 'png' }
+    },
+    required: ['image_url', 'prompt', 'select_prompt']
+  },
+  async (params) => {
+    const result = await stability.editSearchAndRecolor(params.image_url, params.prompt, params.select_prompt, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Search and recolor completed.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT: REMOVE BACKGROUND
+   ============================================================ */
+
+tools.add(
+  'edit_remove_background',
+  'Accurately segment the foreground and remove the background from an image.',
+  {
+    type: 'object',
+    properties: {
+      image_url: { type: 'string' },
+      output_format: { type: 'string', enum: ['png', 'webp'], default: 'png' }
+    },
+    required: ['image_url']
+  },
+  async (params) => {
+    const result = await stability.editRemoveBackground(params.image_url, params);
+    return JSON.stringify({
+      local_path: result.local_path,
+      finish_reason: result.finish_reason,
+      note: 'Background removed successfully.'
+    }, null, 2);
+  }
+);
+
+export default tools;

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

@@ -0,0 +1,302 @@
+/**
+ * @file lib/API/stability.ai/MusicToolset.js
+ * @module stability.ai/MusicToolset
+ * @description Comprehensive ToolSet for the Stability AI Stable Audio 3 API.
+ *
+ * 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
+ *
+ * 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.
+ *
+ * Designed specifically for AI agents, LLMs, and function-calling systems.
+ * 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.
+ *
+ * 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
+ * - Prompts must be in English; no copyrighted material
+ * - Polling is fully automatic — you do not need to call fetch_result manually
+ *
+ * @see ./audio.js for the underlying implementation
+ * @see ./audio-3.md for the full API specification
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as stability from './audio.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   WORKFLOW 1: TEXT-TO-AUDIO
+   ============================================================ */
+
+tools.add(
+  'text_to_audio',
+  'Generate original high-quality music or audio directly from a descriptive text prompt using Stability AI\'s Stable Audio 3 model. ' +
+  'This is the primary tool for creating new tracks, soundscapes, cinematic scores, or sound design from scratch. ' +
+  '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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Strong, detailed, and descriptive English-language prompt that defines the desired audio. ' +
+                     'Include instruments, mood, genre, tempo, structure, and style. ' +
+                     'Maximum 10,000 characters. ' +
+                     'Good example: "epic orchestral cinematic trailer music, powerful brass and strings, building tension, 120 BPM, dramatic and emotional". ' +
+                     'Avoid copyrighted material or non-English text.'
+      },
+      duration: {
+        type: 'number',
+        minimum: 1,
+        maximum: 380,
+        default: 190,
+        description: 'Target duration of the generated audio in seconds. ' +
+                     '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. ' +
+                     'Use 0 (or omit) for a random seed. ' +
+                     'Any integer between 0 and 4,294,967,294. ' +
+                     'Same seed + same prompt usually produces similar output.'
+      },
+      steps: {
+        type: 'integer',
+        minimum: 4,
+        maximum: 8,
+        default: 8,
+        description: 'Number of diffusion/sampling steps. ' +
+                     'Higher values (up to 8) generally produce better quality at the cost of longer generation time. ' +
+                     'Default 8 is recommended for most cases.'
+      },
+      cfg_scale: {
+        type: 'number',
+        minimum: 1,
+        maximum: 25,
+        default: 1,
+        description: 'Classifier-Free Guidance scale controlling how strictly the model follows the prompt. ' +
+                     'Higher values (e.g. 5–15) increase prompt adherence but can reduce creativity. ' +
+                     'Default 1 is a good starting point; increase for more literal interpretations.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await stability.textToAudio(params.prompt, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      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);
+  }
+);
+
+/* ============================================================
+   WORKFLOW 2: AUDIO-TO-AUDIO
+   ============================================================ */
+
+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., ' +
+  '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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of the desired transformation or new style. ' +
+                     'Example: "turn this into a lush orchestral version with strings, choir, and cinematic atmosphere". ' +
+                     'Must be in English. Max 10,000 characters.'
+      },
+      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. ' +
+                     '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).'
+      },
+      duration: {
+        type: 'number',
+        minimum: 1,
+        maximum: 380,
+        default: 190,
+        description: 'Desired output duration in seconds (1–380). ' +
+                     'Can be shorter or longer than the input audio.'
+      },
+      strength: {
+        type: 'number',
+        minimum: 0,
+        maximum: 1,
+        default: 1,
+        description: 'Denoising strength / influence of the original audio. ' +
+                     '0.0 = output is almost identical to input (minimal change). ' +
+                     '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).'
+      },
+      steps: {
+        type: 'integer',
+        minimum: 4,
+        maximum: 8,
+        default: 8,
+        description: 'Sampling steps (4–8). Higher = better quality.'
+      },
+      cfg_scale: {
+        type: 'number',
+        minimum: 1,
+        maximum: 25,
+        default: 1,
+        description: 'Prompt adherence scale (1–25).'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    // Support both audio_url and audio_path for flexibility (and legacy 'audio' field)
+    const audioInput = params.audio_path || params.audio_url || params.audio;
+
+    const result = await stability.audioToAudio(params.prompt, audioInput, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      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);
+  }
+);
+
+/* ============================================================
+   WORKFLOW 3: INPAINT
+   ============================================================ */
+
+tools.add(
+  'inpaint',
+  'Regenerate or replace a specific time-based section of an existing 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.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of the new content that should replace the masked section. ' +
+                     'Example: "add a soaring electric guitar solo with reverb and delay". ' +
+                     'English only, max 10,000 characters.'
+      },
+      audio_url: {
+        type: 'string',
+        description: 'Public URL of the reference audio file to edit. Must be 6–380 seconds long.'
+      },
+      audio_path: {
+        type: 'string',
+        description: 'Local path to the reference audio file to edit.'
+      },
+      mask_start: {
+        type: 'number',
+        minimum: 0,
+        maximum: 380,
+        default: 30,
+        description: 'Start time in seconds of the section to replace/inpaint. ' +
+                     'Must be less than mask_end. Default: 30 seconds.'
+      },
+      mask_end: {
+        type: 'number',
+        minimum: 0,
+        maximum: 380,
+        default: 380,
+        description: 'End time in seconds of the section to replace. ' +
+                     'Must be greater than mask_start. Default: 380 (end of track).'
+      },
+      duration: {
+        type: 'number',
+        minimum: 1,
+        maximum: 380,
+        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.'
+      },
+      steps: {
+        type: 'integer',
+        minimum: 4,
+        maximum: 8,
+        default: 8,
+        description: 'Sampling steps (4–8).'
+      },
+      cfg_scale: {
+        type: 'number',
+        minimum: 1,
+        maximum: 25,
+        default: 1,
+        description: 'Prompt adherence (1–25).'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const audioInput = params.audio_path || params.audio_url || params.audio;
+
+    const result = await stability.inpaint(params.prompt, audioInput, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      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);
+  }
+);
+
+export default tools;