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

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

@@ -0,0 +1,165 @@
+/**
+ * @file lib/API/x.ai/ImageToolset.js
+ * @module x.ai/ImageToolset
+ * @description Comprehensive ToolSet for the xAI Grok Imagine API.
+ *
+ * Exposes high-level tools for:
+ *   - generate_image     → Text-to-image generation
+ *   - edit_image         → Natural language image editing (supports up to 3 reference images)
+ *   - generate_video     → Image-to-video generation (fully automatic)
+ *
+ * Designed for AI agents and LLMs. Each tool includes rich descriptions and JSON schemas.
+ *
+ * @see ./image.js for the underlying implementation
+ * @see ./image.md for the full API specification
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as xai from './image.js';
+
+const tools = new ToolSet('auto');
+
+/* ============================================================
+   GENERATE IMAGE
+   ============================================================ */
+
+tools.add(
+  'generate_image',
+  'Generate high-quality images from a text prompt using Grok Imagine. ' +
+  'Supports configurable number of images and output format. ' +
+  'Returns the local file path of the generated image(s).',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Detailed English prompt describing the desired image. ' +
+                     'Be specific about style, lighting, composition, and subject.'
+      },
+      n: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 10,
+        default: 1,
+        description: 'Number of images to generate in one request.'
+      },
+      output_format: {
+        type: 'string',
+        enum: ['png', 'jpeg', 'webp'],
+        default: 'png',
+        description: 'Preferred output format.'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const result = await xai.generateImage(params.prompt, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      url: result.url,
+      revised_prompt: result.revised_prompt,
+      note: 'Image generated successfully with generate_image.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   EDIT IMAGE
+   ============================================================ */
+
+tools.add(
+  'edit_image',
+  'Edit one or more images using natural language instructions. ' +
+  'Supports up to 3 reference images for compositing, style transfer, or multi-subject editing. ' +
+  'Provide image URLs, local paths, or base64 data.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Natural language description of the edit you want to apply.'
+      },
+      image_url: {
+        type: 'string',
+        description: 'Single image URL or path to edit.'
+      },
+      image_urls: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Array of up to 3 image URLs or paths for multi-image editing.'
+      },
+      output_format: {
+        type: 'string',
+        enum: ['png', 'jpeg', 'webp'],
+        default: 'png'
+      }
+    },
+    required: ['prompt']
+  },
+  async (params) => {
+    const images = params.image_urls || (params.image_url ? [params.image_url] : []);
+
+    const result = await xai.editImage(params.prompt, images, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      url: result.url,
+      revised_prompt: result.revised_prompt,
+      note: 'Image edited successfully with edit_image.'
+    }, null, 2);
+  }
+);
+
+/* ============================================================
+   GENERATE VIDEO
+   ============================================================ */
+
+tools.add(
+  'generate_video',
+  'Generate a video from a still image and text prompt using Grok Imagine Video. ' +
+  'This tool is fully automatic — it submits the request and waits internally until the video is ready. ' +
+  'Returns the local file path of the generated video.',
+  {
+    type: 'object',
+    properties: {
+      prompt: {
+        type: 'string',
+        description: 'Description of the desired motion, camera movement, or animation.'
+      },
+      image_url: {
+        type: 'string',
+        description: 'Source image URL or local path.'
+      },
+      duration: {
+        type: 'number',
+        minimum: 1,
+        maximum: 15,
+        default: 8,
+        description: 'Video duration in seconds.'
+      },
+      aspect_ratio: {
+        type: 'string',
+        default: '16:9',
+        description: 'Aspect ratio of the output video.'
+      },
+      resolution: {
+        type: 'string',
+        default: '720p',
+        description: 'Output resolution.'
+      }
+    },
+    required: ['prompt', 'image_url']
+  },
+  async (params) => {
+    const result = await xai.generateVideo(params.prompt, params.image_url, params);
+
+    return JSON.stringify({
+      local_path: result.local_path,
+      url: result.url,
+      note: 'Video generated successfully with generate_video.'
+    }, null, 2);
+  }
+);
+
+export default tools;

package/lib/API/x.ai/image.editing.md

@@ -0,0 +1,86 @@
+#### Model Capabilities
+
+# Image Editing
+
+Edit an existing image by providing a source image along with your prompt. The model understands the image content and applies your requested changes.
+
+> [!WARNING]
+>
+> The OpenAI SDK's `images.edit()` method is not supported for image editing because it uses `multipart/form-data`, while the xAI API requires `application/json`. Use the xAI SDK, Vercel AI SDK, or direct HTTP requests instead.
+
+With the xAI SDK, use the same `sample()` method; just add the `image_url` parameter:
+
+```python customLanguage="pythonXAI"
+import base64
+import xai_sdk
+
+client = xai_sdk.Client()
+
+# Load image from file and encode as base64
+with open("photo.png", "rb") as f:
+    image_data = base64.b64encode(f.read()).decode("utf-8")
+
+response = client.image.sample(
+    prompt="Render this as a pencil sketch with detailed shading",
+    model="grok-imagine-image-quality",
+    image_url=f"data:image/png;base64,{image_data}",
+)
+
+print(response.url)
+```
+
+```bash
+# Using a public URL as the source image
+curl -X POST https://api.x.ai/v1/images/edits \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "model": "grok-imagine-image-quality",
+    "prompt": "Render this as a pencil sketch with detailed shading",
+    "image": {
+      "url": "https://docs.x.ai/assets/api-examples/images/style-realistic.png",
+      "type": "image_url"
+    }
+  }'
+```
+
+```javascript customLanguage="javascriptAISDK"
+import { xai } from "@ai-sdk/xai";
+import { generateImage } from "ai";
+import fs from "fs";
+
+// Load image and encode as base64
+const imageBuffer = fs.readFileSync("photo.png");
+const base64Image = imageBuffer.toString("base64");
+
+const { image } = await generateImage({
+    model: xai.image("grok-imagine-image-quality"),
+    prompt: {
+        text: "Render this as a pencil sketch with detailed shading",
+        images: [`data:image/png;base64,${base64Image}`],
+    },
+});
+
+console.log(image.base64);
+```
+
+You can provide the source image as:
+
+* A **public URL** pointing to an image
+* A **base64-encoded data URI** (e.g., `data:image/jpeg;base64,...`)
+
+## Multi-turn editing
+
+Chain multiple edits together by using each output as the input for the next. This enables iterative refinement; start with a base image and progressively add details, adjust styles, or make corrections.
+
+## Style transfer
+
+The `grok-imagine-image-quality` model supports a wide range of visual styles, from ultra-realistic photography to anime, oil paintings, and pencil sketches. Transform existing images by describing the desired aesthetic in your prompt.
+
+## Related
+
+* [Image Generation](/developers/model-capabilities/images/generation) — Generate images from text prompts
+* [Multi-Image Editing](/developers/model-capabilities/images/multi-image-editing) — Edit with multiple source images
+* [API Reference](/developers/rest-api-reference) — Full endpoint documentation
+* [Imagine API Landing Page](https://x.ai/api/imagine) — Showcase of the Imagine API in action
+

package/lib/API/x.ai/image.js

@@ -0,0 +1,393 @@
+/**
+ * @file lib/API/x.ai/image.js
+ * @module x.ai/image
+ * @description Pure HTTP wrapper for the xAI Grok Imagine API.
+ *
+ * Provides a clean, minimal interface for:
+ * - Text-to-image generation
+ * - Natural language image editing (supports up to 3 reference images)
+ * - Image-to-video generation (fully automatic with internal polling)
+ *
+ * All functions handle authentication, request formatting, local file saving,
+ * and error handling. Video generation waits internally until the result is ready.
+ *
+ * @see ./image.md for the full API specification and examples
+ */
+
+/**
+ * @constant {string} BASE_URL
+ * @description Base URL for the xAI API.
+ */
+const BASE_URL = 'https://api.x.ai/v1';
+
+/**
+ * @constant {string} TMP_DIR
+ * @description Local directory where generated images and videos are saved.
+ */
+const TMP_DIR = path.join(process.cwd(), '.cache', 'xai');
+
+import { request as doRequest } from '@j-o-r/apiserver';
+import fs from 'fs/promises';
+import path from 'path';
+
+/**
+ * Builds authenticated headers for xAI requests.
+ *
+ * @returns {Object} Headers containing Authorization Bearer token.
+ * @throws {Error} If `XAI_API_KEY` environment variable is not set.
+ */
+const getHeaders = () => {
+  if (!process.env.XAIKEY) {
+    throw new Error('Missing XAIKEY! Please export XAIKEY=your_key');
+  }
+  return {
+    'Authorization': `Bearer ${process.env.XAIKEY}`,
+    'Content-Type': 'application/json'
+  };
+};
+
+/**
+ * Ensures the temporary directory for media files exists.
+ *
+ * @async
+ * @returns {Promise<void>}
+ */
+async function ensureTmpDir() {
+  await fs.mkdir(TMP_DIR, { recursive: true });
+}
+
+/**
+ * Saves image or video data (URL, base64, Buffer, etc.) to a local file.
+ *
+ * @async
+ * @param {string|Buffer|Blob|ArrayBuffer} data - Media content to save.
+ * @param {string} [filenamePrefix='xai-media'] - Prefix for the saved file.
+ * @param {string} [ext='png'] - File extension.
+ * @returns {Promise<string>} Absolute path to the saved file.
+ */
+async function saveMediaToLocal(data, filenamePrefix = 'xai-media', ext = 'png') {
+  await ensureTmpDir();
+
+  const filename = `${filenamePrefix}-${Date.now()}.${ext}`;
+  const localPath = path.join(TMP_DIR, filename);
+
+  let buffer;
+  if (typeof data === 'string') {
+    if (data.startsWith('http')) {
+      const response = await fetch(data);
+      if (!response.ok) throw new Error(`Failed to download: ${response.status}`);
+      buffer = Buffer.from(await response.arrayBuffer());
+    } else if (data.match(/^[A-Za-z0-9+/=]+$/)) {
+      buffer = Buffer.from(data, 'base64');
+    } else {
+      throw new Error('Unsupported string format');
+    }
+  } else if (data instanceof Buffer) {
+    buffer = data;
+  } else if (data instanceof Blob || data instanceof ArrayBuffer) {
+    buffer = Buffer.from(await (data instanceof Blob ? data.arrayBuffer() : data));
+  } else {
+    throw new Error('Unsupported media data type');
+  }
+
+  await fs.writeFile(localPath, buffer);
+  return localPath;
+}
+
+/**
+ * Prepares an image input into the format expected by xAI.
+ * Accepts URLs, base64 data URIs, local file paths, Buffers, or Blobs.
+ *
+ * @async
+ * @param {string|Buffer|Blob} imageInput - Image source.
+ * @returns {Promise<Object>} Object with `url` and `type`.
+ */
+async function prepareImageInput(imageInput) {
+  if (!imageInput) throw new Error('Image input is required');
+
+  if (typeof imageInput === 'string') {
+    if (imageInput.startsWith('http://') || imageInput.startsWith('https://')) {
+      return { url: imageInput, type: 'image_url' };
+    }
+    if (imageInput.startsWith('data:')) {
+      return { url: imageInput, type: 'image_url' };
+    }
+    // Local file → base64 data URI
+    const buffer = await fs.readFile(imageInput);
+    const ext = path.extname(imageInput).toLowerCase().replace('.', '');
+    const mime = ext === 'jpg' ? 'jpeg' : ext;
+    return {
+      url: `data:image/${mime};base64,${buffer.toString('base64')}`,
+      type: 'image_url'
+    };
+  }
+
+  if (imageInput instanceof Buffer) {
+    return {
+      url: `data:image/png;base64,${imageInput.toString('base64')}`,
+      type: 'image_url'
+    };
+  }
+
+  if (imageInput instanceof Blob) {
+    const buffer = Buffer.from(await imageInput.arrayBuffer());
+    return {
+      url: `data:image/png;base64,${buffer.toString('base64')}`,
+      type: 'image_url'
+    };
+  }
+
+  throw new Error('Unsupported image input type');
+}
+
+/* ============================================================
+   PUBLIC: IMAGE GENERATION
+   ============================================================ */
+
+/**
+ * Generates one or more images from a text prompt using Grok Imagine.
+ *
+ * @async
+ * @function generateImage
+ * @param {string} prompt - Detailed text prompt describing the desired image.
+ * @param {Object} [options={}] - Optional generation parameters.
+ * @param {string} [options.model='grok-imagine-image-quality'] - Model to use.
+ * @param {number} [options.n=1] - Number of images to generate (1–10).
+ * @param {string} [options.response_format='url'] - `'url'` or `'b64_json'`.
+ * @returns {Promise<Object>} Result containing `local_path`, `url` (or `base64`), and metadata.
+ * @throws {Error} On missing prompt or API errors.
+ *
+ * @example
+ * const result = await generateImage("A futuristic city at night");
+ * console.log(result.local_path);
+ */
+async function generateImage(prompt, options = {}) {
+  if (!prompt || typeof prompt !== 'string') {
+    throw new Error('generateImage() requires a prompt string');
+  }
+
+  const body = {
+    model: options.model || 'grok-imagine-image-quality',
+    prompt,
+    n: options.n || 1,
+    response_format: options.response_format || 'url'
+    // Note: "size" is not supported by the xAI Grok Imagine API
+  };
+
+  const headers = getHeaders();
+  const res = await doRequest(`${BASE_URL}/images/generations`, 'POST', headers, body);
+
+  if (res.status !== 200) {
+    throw new Error(`xAI API error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  const data = res.response;
+  const result = data.data?.[0];
+
+  if (result?.url) {
+    const localPath = await saveMediaToLocal(result.url, 'xai-generated', 'png');
+    return {
+      local_path: localPath,
+      url: result.url,
+      revised_prompt: result.revised_prompt,
+      raw: data
+    };
+  }
+
+  if (result?.b64_json) {
+    const localPath = await saveMediaToLocal(result.b64_json, 'xai-generated', 'png');
+    return {
+      local_path: localPath,
+      base64: result.b64_json,
+      revised_prompt: result.revised_prompt,
+      raw: data
+    };
+  }
+
+  return { raw: data };
+}
+
+/* ============================================================
+   PUBLIC: IMAGE EDITING
+   ============================================================ */
+
+/**
+ * Edits one or more images using a natural language prompt.
+ * Supports up to 3 reference images for compositing, style transfer, or multi-subject scenes.
+ *
+ * @async
+ * @function editImage
+ * @param {string} prompt - Description of the desired edit.
+ * @param {string|Buffer|Blob|Array<string|Buffer|Blob>} imageInputs - One or more images (URL, path, base64, Buffer, or Blob).
+ * @param {Object} [options={}] - Optional parameters.
+ * @param {string} [options.model='grok-imagine-image-quality']
+ * @param {number} [options.n=1]
+ * @param {string} [options.response_format='url']
+ * @returns {Promise<Object>} Result with edited image.
+ * @throws {Error} If more than 3 images are provided or on API error.
+ *
+ * @example
+ * // Single image edit
+ * const result = await editImage("Make this a pencil sketch", "./photo.png");
+ *
+ * @example
+ * // Multi-image editing (up to 3)
+ * const result = await editImage(
+ *   "Combine these two people into one scene",
+ *   ["./person1.png", "./person2.png"]
+ * );
+ */
+async function editImage(prompt, imageInputs, options = {}) {
+  if (!prompt) throw new Error('editImage() requires a prompt');
+  if (!imageInputs) throw new Error('editImage() requires at least one image');
+
+  const images = Array.isArray(imageInputs) ? imageInputs : [imageInputs];
+
+  if (images.length > 3) {
+    throw new Error('editImage() supports a maximum of 3 reference images');
+  }
+
+  const preparedImages = await Promise.all(images.map(prepareImageInput));
+
+  const body = {
+    model: options.model || 'grok-imagine-image-quality',
+    prompt,
+    image: preparedImages.length === 1 ? preparedImages[0] : preparedImages,
+    n: options.n || 1,
+    response_format: options.response_format || 'url'
+  };
+
+  const headers = getHeaders();
+  const res = await doRequest(`${BASE_URL}/images/edits`, 'POST', headers, body);
+
+  if (res.status !== 200) {
+    throw new Error(`xAI API error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  const data = res.response;
+  const result = data.data?.[0];
+
+  if (result?.url) {
+    const localPath = await saveMediaToLocal(result.url, 'xai-edited', 'png');
+    return {
+      local_path: localPath,
+      url: result.url,
+      revised_prompt: result.revised_prompt,
+      raw: data
+    };
+  }
+
+  if (result?.b64_json) {
+    const localPath = await saveMediaToLocal(result.b64_json, 'xai-edited', 'png');
+    return {
+      local_path: localPath,
+      base64: result.b64_json,
+      revised_prompt: result.revised_prompt,
+      raw: data
+    };
+  }
+
+  return { raw: data };
+}
+
+/* ============================================================
+   INTERNAL: Poll video result
+   ============================================================ */
+
+async function _pollVideoResult(requestId, maxAttempts = 60, intervalMs = 5000) {
+  if (!requestId) throw new Error('Video request_id is required');
+
+  const headers = getHeaders();
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    const res = await doRequest(`${BASE_URL}/videos/${requestId}`, 'GET', headers);
+
+    if (res.status === 200) {
+      const data = res.response;
+
+      if (data.status === 'done' && data.video?.url) {
+        const localPath = await saveMediaToLocal(data.video.url, 'xai-video', 'mp4');
+        return {
+          local_path: localPath,
+          url: data.video.url,
+          status: 'done',
+          raw: data
+        };
+      }
+
+      if (data.status === 'failed' || data.status === 'expired') {
+        throw new Error(`Video generation ${data.status}: ${JSON.stringify(data)}`);
+      }
+    }
+
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+
+  throw new Error(`Timeout polling video request ${requestId}`);
+}
+
+/* ============================================================
+   PUBLIC: IMAGE-TO-VIDEO (fully automatic)
+   ============================================================ */
+
+/**
+ * Generates a video from a still image and text prompt.
+ * This function is fully automatic — it submits the request and polls internally
+ * until the video is ready before returning.
+ *
+ * @async
+ * @function generateVideo
+ * @param {string} prompt - Description of the desired motion or animation.
+ * @param {string|Buffer|Blob} imageInput - Source image (URL, path, base64, Buffer, or Blob).
+ * @param {Object} [options={}] - Optional video parameters.
+ * @param {number} [options.duration=8] - Video duration in seconds.
+ * @param {string} [options.aspect_ratio='16:9'] - Aspect ratio.
+ * @param {string} [options.resolution='720p'] - Output resolution.
+ * @returns {Promise<Object>} Result containing `local_path` and `url` of the generated video.
+ * @throws {Error} On missing inputs or generation failure.
+ *
+ * @example
+ * const result = await generateVideo(
+ *   "Make the water crash down and slowly pan out",
+ *   "https://example.com/waterfall.png",
+ *   { duration: 12 }
+ * );
+ * console.log(result.local_path);
+ */
+async function generateVideo(prompt, imageInput, options = {}) {
+  if (!prompt) throw new Error('generateVideo() requires a prompt');
+  if (!imageInput) throw new Error('generateVideo() requires an image');
+
+  const preparedImage = await prepareImageInput(imageInput);
+
+  const body = {
+    model: options.model || 'grok-imagine-video',
+    prompt,
+    image: preparedImage,
+    duration: options.duration || 8,
+    aspect_ratio: options.aspect_ratio || '16:9',
+    resolution: options.resolution || '720p'
+  };
+
+  const headers = getHeaders();
+  const res = await doRequest(`${BASE_URL}/videos/generations`, 'POST', headers, body);
+
+  if (res.status !== 200) {
+    throw new Error(`xAI API error ${res.status}: ${JSON.stringify(res.response)}`);
+  }
+
+  const { request_id } = res.response;
+
+  if (!request_id) {
+    throw new Error('No request_id returned from video generation');
+  }
+
+  // Automatically poll until ready
+  return await _pollVideoResult(request_id);
+}
+
+export {
+  generateImage,
+  editImage,
+  generateVideo
+};