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

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

@@ -0,0 +1,376 @@
+/**
+ * @file lib/API/x.ai/imageToolset.js
+ * @module x.ai/imageToolset
+ * @description ToolSet wrapper for the xAI Grok Imagine image/video API.
+ *
+ * Exposes high-level tools for AI agents and LLMs:
+ * - generate_image_grok
+ * - edit_image_grok
+ * - generate_video_grok
+ * - poll_video_result_grok
+ *
+ * Tool responses are intentionally compact, structured JSON. They preserve
+ * durable references such as local_path, url, request_id, source_image_url, and
+ * revised_prompt so the assistant can repeat those exact values in normal
+ * assistant messages before raw function-call history is pruned.
+ *
+ * @see ./image.js for the underlying implementation and full JSDoc.
+ */
+
+import ToolSet from '../../ToolSet.js';
+import * as xai 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);
+}
+
+/**
+ * Normalizes image input that may arrive as a native array, JSON-stringified
+ * array, single string URL/path/data URI, or nullish value.
+ *
+ * @param {unknown} val Raw image input value.
+ * @returns {string[]} Clean array of non-empty image references.
+ */
+function normalizeImageList(val) {
+	if (!val) return [];
+
+	if (Array.isArray(val)) {
+		return val.filter(Boolean).map(String);
+	}
+
+	if (typeof val === 'string') {
+		const trimmed = val.trim();
+		if (trimmed.startsWith('[') && trimmed.endsWith(']')) {
+			try {
+				const parsed = JSON.parse(trimmed);
+				if (Array.isArray(parsed)) {
+					return parsed.filter(Boolean).map(String);
+				}
+			} catch (_) {
+				// Fall through and treat as a single image reference.
+			}
+		}
+		return trimmed ? [trimmed] : [];
+	}
+
+	return [String(val)];
+}
+
+/**
+ * Build a compact, self-describing image tool response.
+ *
+ * @param {string} tool Tool/function name.
+ * @param {Record<string, unknown>} result Wrapper result.
+ * @param {Record<string, unknown>} context Durable input/context fields to echo.
+ * @returns {string} JSON function response.
+ */
+function imageToolResponse(tool, result, context = {}) {
+	return json({
+		tool,
+		success: true,
+		...context,
+		local_path: result.local_path,
+		localPath: result.local_path,
+		url: result.url,
+		image_url: result.url,
+		base64_available: Boolean(result.base64),
+		revised_prompt: result.revised_prompt,
+		note: 'Assistant: tell the user the exact local_path and url/image_url when present. Preserve revised_prompt if it matters for follow-up edits or regeneration. Use image_url/url or local_path as durable references for later image/video tools.'
+	});
+}
+
+/**
+ * Build a compact, self-describing video tool response.
+ *
+ * @param {string} tool Tool/function name.
+ * @param {Record<string, unknown>} result Wrapper result.
+ * @param {Record<string, unknown>} context Durable input/context fields to echo.
+ * @returns {string} JSON function response.
+ */
+function videoToolResponse(tool, result, context = {}) {
+	return json({
+		tool,
+		success: true,
+		...context,
+		local_path: result.local_path,
+		localPath: result.local_path,
+		url: result.url,
+		video_url: result.url,
+		status: result.status,
+		note: 'Assistant: tell the user the exact local_path and video_url/url when present. If request_id is present, repeat it exactly because it is required for poll_video_result_grok. Preserve source_image_url for follow-up edits or regeneration.'
+	});
+}
+
+/* ============================================================
+   GENERATE IMAGE
+   ============================================================ */
+
+tools.add(
+	'generate_image_grok',
+	'Generate high-quality images from a text prompt using Grok Imagine models. ' +
+	'Default model is "grok-imagine-image-quality" (recommended). Alternative model: "grok-imagine-image". ' +
+	'Supports batch generation (n images), custom aspect ratios, resolutions (1k/2k), and response formats (url or b64_json). ' +
+	'Images are automatically saved locally. After success, include the exact local_path and url/image_url in your normal assistant response so those references remain available after raw function calls are pruned.',
+	{
+		type: 'object',
+		properties: {
+			prompt: {
+				type: 'string',
+				description: 'Detailed English prompt describing the desired image. Be specific about style, lighting, composition, subject, mood, camera angle, and artistic references for best results.'
+			},
+			n: {
+				type: 'integer',
+				minimum: 1,
+				maximum: 10,
+				default: 1,
+				description: 'Number of images to generate in a single request. Min: 1, Max: 10, Default: 1. Use higher values for variations.'
+			},
+			model: {
+				type: 'string',
+				default: 'grok-imagine-image-quality',
+				description: 'Model to use. Recommended: "grok-imagine-image-quality". Alternative: "grok-imagine-image".'
+			},
+			response_format: {
+				type: 'string',
+				enum: ['url', 'b64_json'],
+				default: 'url',
+				description: 'Output format. Prefer "url" when possible because it provides a durable image_url-style reference. "b64_json" returns base64 data for direct embedding.'
+			},
+			aspect_ratio: {
+				type: 'string',
+				description: 'Aspect ratio of the output image. Common values: "16:9", "9:16", "1:1", "4:3", "3:2", "auto".'
+			},
+			resolution: {
+				type: 'string',
+				enum: ['1k', '2k'],
+				description: 'Output resolution. "1k" (default) or "2k" for higher detail.'
+			}
+		},
+		required: ['prompt']
+	},
+	async (params) => {
+		const result = await xai.generateImage(params.prompt, params);
+
+		return imageToolResponse('generate_image_grok', result, {
+			prompt: params.prompt,
+			model: params.model || 'grok-imagine-image-quality',
+			n: params.n || 1,
+			response_format: params.response_format || 'url',
+			aspect_ratio: params.aspect_ratio,
+			resolution: params.resolution
+		});
+	}
+);
+
+/* ============================================================
+   EDIT IMAGE
+   ============================================================ */
+
+tools.add(
+	'edit_image_grok',
+	'Edit one or more images using natural language instructions with Grok Imagine. ' +
+	'Supports up to 3 reference images for compositing subjects, style transfer, multi-subject scenes, or iterative refinement. ' +
+	'Provide image URLs, local file paths, or base64 data URIs. Prefer image_url/image_urls where possible. ' +
+	'After success, include the exact output local_path and url/image_url plus the exact source_image_url/source_image_urls in your normal assistant response so references remain available after raw function calls are pruned.\n\n' +
+	'OFFICIAL API MAPPING:\n' +
+	'- Single image → uses the "image" field (object with url + type).\n' +
+	'- Multiple images (2-3) → uses the "images" array of objects.\n' +
+	'When using multiple images, refer to them in the prompt as <IMAGE_0>, <IMAGE_1>, <IMAGE_2> (etc.).\n\n' +
+	'IMPORTANT: Use either "image_url" (for a single image) OR "image_urls" (array of up to 3). Do not use both. ' +
+	'Note: image_urls may arrive as a JSON string; the handler normalizes it automatically.',
+	{
+		type: 'object',
+		properties: {
+			prompt: {
+				type: 'string',
+				description: 'Natural language description of the edit or transformation. For multi-image edits, refer to the inputs as <IMAGE_0>, <IMAGE_1>, etc.'
+			},
+			image_url: {
+				type: 'string',
+				description: 'Single source image URL, local path, or base64 data URI. Prefer public image_url where possible. Use this when editing exactly one image. Mutually exclusive with image_urls.'
+			},
+			image_urls: {
+				type: 'array',
+				items: { type: 'string' },
+				description: 'Array of up to 3 image URLs/paths for multi-image editing. Prefer public image_url values where possible. May be a native array or JSON string.'
+			},
+			model: {
+				type: 'string',
+				default: 'grok-imagine-image-quality',
+				description: 'Model to use. Recommended: "grok-imagine-image-quality". Alternative: "grok-imagine-image".'
+			},
+			n: {
+				type: 'integer',
+				minimum: 1,
+				maximum: 10,
+				default: 1,
+				description: 'Number of edited output images. Min: 1, Max: 10, Default: 1.'
+			},
+			response_format: {
+				type: 'string',
+				enum: ['url', 'b64_json'],
+				default: 'url',
+				description: 'Output format. Prefer "url" when possible because it gives an image_url-style reference for follow-up tools.'
+			},
+			aspect_ratio: {
+				type: 'string',
+				description: 'Desired aspect ratio for the output. Single-image edits generally respect the input.'
+			},
+			resolution: {
+				type: 'string',
+				enum: ['1k', '2k'],
+				description: 'Output resolution: "1k" or "2k".'
+			}
+		},
+		required: ['prompt']
+	},
+	async (params) => {
+		const normalizedUrls = normalizeImageList(params.image_urls);
+		const normalizedSingle = params.image_url ? [params.image_url] : [];
+		const images = normalizedUrls.length > 0 ? [...normalizedUrls] : [...normalizedSingle];
+
+		if (normalizedUrls.length > 0 && normalizedSingle.length > 0) {
+			const seen = new Set(normalizedUrls);
+			for (const url of normalizedSingle) {
+				if (!seen.has(url)) images.push(url);
+			}
+		}
+
+		if (images.length === 0) {
+			throw new Error('edit_image_grok requires at least one image via image_url or image_urls');
+		}
+		if (images.length > 3) {
+			throw new Error('edit_image_grok supports a maximum of 3 reference images');
+		}
+
+		const result = await xai.editImage(params.prompt, images, params);
+
+		return imageToolResponse('edit_image_grok', result, {
+			prompt: params.prompt,
+			source_image_url: images.length === 1 ? images[0] : undefined,
+			source_image_urls: images,
+			model: params.model || 'grok-imagine-image-quality',
+			n: params.n || 1,
+			response_format: params.response_format || 'url',
+			aspect_ratio: params.aspect_ratio,
+			resolution: params.resolution
+		});
+	}
+);
+
+/* ============================================================
+   GENERATE VIDEO (fully automatic)
+   ============================================================ */
+
+tools.add(
+	'generate_video_grok',
+	'Generate a video from a still image + text prompt using Grok Imagine Video. ' +
+	'Fully automatic: submits the request and polls internally until the video is ready. Model: grok-imagine-video. ' +
+	'The source image becomes the first frame; the prompt describes motion, camera movement, or animation. ' +
+	'Prefer public image_url where possible. Duration affects pricing and generation time. Max video length is 15 seconds. ' +
+	'After success, include the exact local_path, video_url/url, and source_image_url in your normal assistant response so references remain available after raw function calls are pruned. ' +
+	'If generation times out before returning a video, use poll_video_result_grok only when a request_id is available from the error/logs or a direct async call.',
+	{
+		type: 'object',
+		properties: {
+			prompt: {
+				type: 'string',
+				description: 'Description of the desired motion, camera movement, animation, or scene changes. Be specific.'
+			},
+			image_url: {
+				type: 'string',
+				description: 'Source still image. Prefer a public image_url where possible. Local paths and base64 data URIs are also accepted. This becomes the first frame.'
+			},
+			duration: {
+				type: 'number',
+				minimum: 1,
+				maximum: 15,
+				default: 8,
+				description: 'Video duration in seconds. Min: 1, Max: 15, Default: 8. Recommended: 8–12 seconds.'
+			},
+			model: {
+				type: 'string',
+				default: 'grok-imagine-video',
+				description: 'Video model. Currently only "grok-imagine-video" is supported.'
+			},
+			aspect_ratio: {
+				type: 'string',
+				default: '16:9',
+				description: 'Aspect ratio of the output video. Common values: "16:9", "9:16", "1:1".'
+			},
+			resolution: {
+				type: 'string',
+				default: '720p',
+				description: 'Output resolution. Common values: "720p", "480p".'
+			}
+		},
+		required: ['prompt', 'image_url']
+	},
+	async (params) => {
+		const result = await xai.generateVideo(params.prompt, params.image_url, params);
+
+		return videoToolResponse('generate_video_grok', result, {
+			prompt: params.prompt,
+			source_image_url: params.image_url,
+			duration: params.duration || 8,
+			model: params.model || 'grok-imagine-video',
+			aspect_ratio: params.aspect_ratio || '16:9',
+			resolution: params.resolution || '720p'
+		});
+	}
+);
+
+/* ============================================================
+   POLL VIDEO RESULT (manual / emergency polling)
+   ============================================================ */
+
+tools.add(
+	'poll_video_result_grok',
+	'Manually poll the status of an asynchronous video generation request. ' +
+	'Use this tool when a request_id from a previous video generation is available and you need recovery/manual polling. ' +
+	'After success, include the exact request_id, local_path, video_url/url, and status in your normal assistant response so references remain available after raw function calls are pruned.',
+	{
+		type: 'object',
+		properties: {
+			request_id: {
+				type: 'string',
+				description: 'The exact request_id returned by the video generation endpoint. Required for polling; repeat it exactly in follow-up references.'
+			},
+			maxAttempts: {
+				type: 'integer',
+				minimum: 1,
+				default: 60,
+				description: 'Maximum number of polling attempts. Min: 1, Default: 60. Increase for longer videos or slower generations.'
+			},
+			intervalMs: {
+				type: 'integer',
+				default: 15000,
+				description: 'Delay between polling attempts in milliseconds. Default: 15000. Recommended range: 5000–30000.'
+			}
+		},
+		required: ['request_id']
+	},
+	async (params) => {
+		const result = await xai.pollVideoResult(
+			params.request_id,
+			params.maxAttempts,
+			params.intervalMs
+		);
+
+		return videoToolResponse('poll_video_result_grok', result, {
+			request_id: params.request_id,
+			maxAttempts: params.maxAttempts || 60,
+			intervalMs: params.intervalMs || 15000
+		});
+	}
+);
+
+export default tools;

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

@@ -1,5 +1,5 @@
 import * as image from './image.js';
-import imageToolset from './ImageToolset.js'
+import imageToolset from './imageToolset.js'
 
 export default {
 	image,

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

@@ -1,6 +1,6 @@
 /*
-Allthough we can use store = true and previous_response_id: response.id,
-Stil all tokens are billed.
+Although we can use store = true and previous_response_id: response.id,
+Still all tokens are billed.
 */
 import { GLOBAL } from '../../fafs.js'
 import { request as doRequest } from '@j-o-r/apiserver';
@@ -20,7 +20,7 @@ import { sleep } from '@j-o-r/sh';
 * @property {number} [max_output_tokens=4000] - Maximum number of output tokens.
 * @property {number} [max_tool_calls=10] - Maximum number of tool calls allowed.
 * @property {?Object} [metadata=null] - Optional metadata object.
-* @property {'grok-4-1-fast-reasoning'|'grok-4-1-fast-non-reasoning'|'grok-code-fast-1'|'grok-4-fast-reasoning'|'grok-4-fast-non-reasoning'} [model='grok-4-fast-non-reasoning'] - Model version to use.
+* @property {'grok-build-0.1'|'grok-4.3'|'grok-4.20'|'grok-4.20-multi-agent'|'grok-4.20-non-reasoning'} [model='grok-4.3'] - Model version to use.
 * @property {?string} [prompt=null] - Reusable prompt string.
 * @property {Object} [reasoning={effort: 'medium', summary: 'auto'}] - Reasoning configuration.
 * @property {'low'|'medium'|'high'|null} reasoning.effort - Effort level for reasoning.
@@ -37,7 +37,7 @@ import { sleep } from '@j-o-r/sh';
 * @property {Array<XSearchTool|XAIFunctionTool|MCPTool|CodeInterpreterTool|FileSearchTool|XAIWebSearchTool>} [tools=[]] Array of tool call objects.
 * @property {?number } [top_logprobs=null] -  An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
 * @property {?number } [top_p] Top-p sampling value between 0 and 1.
-* @property {?string} [previous_response_id] - Needed reponse_id to validate tool calls on the next request
+* @property {?string} [previous_response_id] - Needed response_id to validate tool calls on the next request
 */
 /// [start] ----- tools ----
 /**
@@ -267,7 +267,7 @@ const webSearch = [
 
 /** @type {XAIOptions} */
 const defaultSettings = {
-	model: 'grok-4-fast-reasoning',
+	model: 'grok-4.3',
 	input: [
 		{
 			role: 'system',
@@ -304,6 +304,9 @@ function getBody(prompt, toolset, options) {
 	const body = { ...defaultSettings, ...(options || {}) };
 	// const body = options ? mergeOptions(DEFAULT_OPTIONS, options) : DEFAULT_OPTIONS;
 	body.instructions = prompt.hasSystemprompt ? prompt.system_prompt : '';
+  // All previous resolved funtioncalls are deleted
+  // except for the last one
+	prompt.pruneResolvedFunctionCallsExceptLast();
 	// the last messages should be a role tool or user else the model cannot handle the request
 	const messages = prompt.messages;
 	if (!['user', 'tool'].includes(messages[messages.length - 1].role)) {
@@ -318,18 +321,6 @@ function getBody(prompt, toolset, options) {
 		body.parallel_tool_calls = true;
 		// parallel_tool_calls
 	}
-	// Add OPENAI SEARCH
-	// in the toolset
-	// if (body.search) {
-	// 	if (!body.tools) {
-	// 		body.tools = [];
-	// 	}
-	// 	body.tools.push({
-	// 		type: 'web_search_preview',
-	// 		// @ts-ignore
-	// 		search_context_size: body.search
-	// 	})
-	// }
 	delete body.search;
 	return body;
 }
@@ -477,7 +468,7 @@ async function request(prompt, toolset = null, options = {}, counter = 0) {
 	const lastMessage = prompt.getLastMessage();
 	if (!lastMessage) throw new Error('No message found');
 	if (lastMessage.role === 'tool') {
-		// need to do another roundtrip to include the funtion_responses
+		// need to do another roundtrip to include the function_responses
 		// And add the previousId for toolsets to work
 		if (!options) {
 			options = {};