@probelabs/probe 0.6.0-rc162 → 0.6.0-rc164

package/build/agent/ProbeAgent.js

@@ -48,6 +48,7 @@ import {
   isJsonSchema,
   validateJsonResponse,
   createJsonCorrectionPrompt,
+  generateSchemaInstructions,
   isJsonSchemaDefinition,
   createSchemaDefinitionCorrectionPrompt,
   validateAndFixMermaidResponse
@@ -1455,11 +1456,18 @@ When troubleshooting:
 
       // Create user message with optional image support
       let userMessage = { role: 'user', content: message.trim() };
-      
+
+      // If schema is provided, prepend JSON format requirement to user message
+      if (options.schema && !options._schemaFormatted) {
+        const schemaInstructions = generateSchemaInstructions(options.schema, { debug: this.debug });
+        userMessage.content = message.trim() + schemaInstructions;
+      }
+
       // If images are provided, use multi-modal message format
       if (images && images.length > 0) {
+        const textContent = userMessage.content;
         userMessage.content = [
-          { type: 'text', text: message.trim() },
+          { type: 'text', text: textContent },
           ...images.map(image => ({
             type: 'image',
             image: image
@@ -2001,29 +2009,8 @@ When troubleshooting:
           // Add assistant response and ask for tool usage
           currentMessages.push({ role: 'assistant', content: assistantResponseContent });
 
-          // Build appropriate reminder message based on whether schema is provided
-          let reminderContent;
-          if (options.schema) {  // Apply for ANY schema, not just JSON schemas
-            // When schema is provided, AI must use attempt_completion to trigger schema formatting
-            reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
-
-Remember: Use proper XML format with BOTH opening and closing tags:
-
-<tool_name>
-<parameter>value</parameter>
-</tool_name>
-
-IMPORTANT: A schema was provided for the final output format.
-
-You MUST use attempt_completion to provide your answer:
-<attempt_completion>
-[Your complete answer here - provide in natural language, it will be automatically formatted to match the schema]
-</attempt_completion>
-
-Your response will be automatically formatted to JSON. You can provide your answer in natural language or as JSON - either will work.`;
-          } else {
-            // Standard reminder without schema
-            reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
+          // Standard reminder - schema was already provided in initial message
+          const reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
 
 Remember: Use proper XML format with BOTH opening and closing tags:
 
@@ -2035,7 +2022,6 @@ Or for quick completion if your previous response was already correct and comple
 <attempt_complete>
 
 IMPORTANT: When using <attempt_complete>, this must be the ONLY content in your response. No additional text, explanations, or other content should be included. This tag signals to reuse your previous response as the final answer.`;
-          }
 
           currentMessages.push({
             role: 'user',

package/build/agent/index.js

@@ -54264,6 +54264,8 @@ __export(schemaUtils_exports, {
   createSchemaDefinitionCorrectionPrompt: () => createSchemaDefinitionCorrectionPrompt,
   decodeHtmlEntities: () => decodeHtmlEntities,
   extractMermaidFromMarkdown: () => extractMermaidFromMarkdown,
+  generateExampleFromSchema: () => generateExampleFromSchema,
+  generateSchemaInstructions: () => generateSchemaInstructions,
   isJsonSchema: () => isJsonSchema,
   isJsonSchemaDefinition: () => isJsonSchemaDefinition,
   isMermaidSchema: () => isMermaidSchema,
@@ -54276,6 +54278,54 @@ __export(schemaUtils_exports, {
   validateMermaidResponse: () => validateMermaidResponse,
   validateXmlResponse: () => validateXmlResponse
 });
+function generateExampleFromSchema(schema, options = {}) {
+  const { debug = false } = options;
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    if (parsedSchema.type !== "object" || !parsedSchema.properties) {
+      return null;
+    }
+    const exampleObj = {};
+    for (const [key, value] of Object.entries(parsedSchema.properties)) {
+      if (value.type === "boolean") {
+        exampleObj[key] = false;
+      } else if (value.type === "number") {
+        exampleObj[key] = 0;
+      } else if (value.type === "string") {
+        exampleObj[key] = value.description || "your answer here";
+      } else if (value.type === "array") {
+        exampleObj[key] = [];
+      } else {
+        exampleObj[key] = {};
+      }
+    }
+    return exampleObj;
+  } catch (e) {
+    if (debug) {
+      console.error("[DEBUG] generateExampleFromSchema: Failed to parse schema:", e.message);
+    }
+    return null;
+  }
+}
+function generateSchemaInstructions(schema, options = {}) {
+  const { debug = false } = options;
+  let instructions = "\n\nIMPORTANT: When you provide your final answer using attempt_completion, you MUST format it as valid JSON matching this schema:\n\n";
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    instructions += `${JSON.stringify(parsedSchema, null, 2)}
+
+`;
+  } catch (e) {
+    if (debug) {
+      console.error("[DEBUG] generateSchemaInstructions: Failed to parse schema:", e.message);
+    }
+    instructions += `${schema}
+
+`;
+  }
+  instructions += "Your response inside attempt_completion must be ONLY valid JSON - no plain text, no explanations, no markdown.\n\nIMPORTANT: First complete the requested analysis/task thoroughly, then provide your final answer in the JSON format above.";
+  return instructions;
+}
 function enforceNoAdditionalProperties(schema) {
   if (!schema || typeof schema !== "object") {
     return schema;
@@ -58305,9 +58355,14 @@ You are working with a repository located at: ${searchDirectory}
           });
           const systemMessage = await this.getSystemMessage();
           let userMessage = { role: "user", content: message.trim() };
+          if (options.schema && !options._schemaFormatted) {
+            const schemaInstructions = generateSchemaInstructions(options.schema, { debug: this.debug });
+            userMessage.content = message.trim() + schemaInstructions;
+          }
           if (images && images.length > 0) {
+            const textContent = userMessage.content;
             userMessage.content = [
-              { type: "text", text: message.trim() },
+              { type: "text", text: textContent },
               ...images.map((image) => ({
                 type: "image",
                 image
@@ -58727,26 +58782,7 @@ Error: Unknown tool '${toolName}'. Available tools: ${allAvailableTools.join(",
                 break;
               }
               currentMessages.push({ role: "assistant", content: assistantResponseContent });
-              let reminderContent;
-              if (options.schema) {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
-
-Remember: Use proper XML format with BOTH opening and closing tags:
-
-<tool_name>
-<parameter>value</parameter>
-</tool_name>
-
-IMPORTANT: A schema was provided for the final output format.
-
-You MUST use attempt_completion to provide your answer:
-<attempt_completion>
-[Your complete answer here - provide in natural language, it will be automatically formatted to match the schema]
-</attempt_completion>
-
-Your response will be automatically formatted to JSON. You can provide your answer in natural language or as JSON - either will work.`;
-              } else {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
+              const reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
 
 Remember: Use proper XML format with BOTH opening and closing tags:
 
@@ -58758,7 +58794,6 @@ Or for quick completion if your previous response was already correct and comple
 <attempt_complete>
 
 IMPORTANT: When using <attempt_complete>, this must be the ONLY content in your response. No additional text, explanations, or other content should be included. This tag signals to reuse your previous response as the final answer.`;
-              }
               currentMessages.push({
                 role: "user",
                 content: reminderContent

package/build/agent/schemaUtils.js

@@ -7,6 +7,74 @@ import { createMessagePreview } from '../tools/common.js';
 import { validate, fixText, extractMermaidBlocks } from '@probelabs/maid';
 import Ajv from 'ajv';
 
+/**
+ * Generate an example JSON object from a JSON schema
+ * @param {Object|string} schema - JSON schema object or string
+ * @param {Object} options - Options for generation
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Object|null} - Example object, or null if schema cannot be processed
+ */
+export function generateExampleFromSchema(schema, options = {}) {
+  const { debug = false } = options;
+
+  try {
+    const parsedSchema = typeof schema === 'string' ? JSON.parse(schema) : schema;
+
+    if (parsedSchema.type !== 'object' || !parsedSchema.properties) {
+      return null;
+    }
+
+    const exampleObj = {};
+    for (const [key, value] of Object.entries(parsedSchema.properties)) {
+      if (value.type === 'boolean') {
+        exampleObj[key] = false;
+      } else if (value.type === 'number') {
+        exampleObj[key] = 0;
+      } else if (value.type === 'string') {
+        exampleObj[key] = value.description || 'your answer here';
+      } else if (value.type === 'array') {
+        exampleObj[key] = [];
+      } else {
+        exampleObj[key] = {};
+      }
+    }
+
+    return exampleObj;
+  } catch (e) {
+    if (debug) {
+      console.error('[DEBUG] generateExampleFromSchema: Failed to parse schema:', e.message);
+    }
+    return null;
+  }
+}
+
+/**
+ * Generate schema instructions for AI to follow
+ * @param {Object|string} schema - JSON schema object or string
+ * @param {Object} options - Options for generation
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {string} - Formatted schema instructions
+ */
+export function generateSchemaInstructions(schema, options = {}) {
+  const { debug = false } = options;
+
+  let instructions = '\n\nIMPORTANT: When you provide your final answer using attempt_completion, you MUST format it as valid JSON matching this schema:\n\n';
+
+  try {
+    const parsedSchema = typeof schema === 'string' ? JSON.parse(schema) : schema;
+    instructions += `${JSON.stringify(parsedSchema, null, 2)}\n\n`;
+  } catch (e) {
+    if (debug) {
+      console.error('[DEBUG] generateSchemaInstructions: Failed to parse schema:', e.message);
+    }
+    instructions += `${schema}\n\n`;
+  }
+
+  instructions += 'Your response inside attempt_completion must be ONLY valid JSON - no plain text, no explanations, no markdown.\n\nIMPORTANT: First complete the requested analysis/task thoroughly, then provide your final answer in the JSON format above.';
+
+  return instructions;
+}
+
 /**
  * Recursively apply additionalProperties: false to all object schemas
  * This ensures strict validation at all nesting levels

package/cjs/agent/ProbeAgent.cjs

@@ -79944,6 +79944,8 @@ __export(schemaUtils_exports, {
   createSchemaDefinitionCorrectionPrompt: () => createSchemaDefinitionCorrectionPrompt,
   decodeHtmlEntities: () => decodeHtmlEntities,
   extractMermaidFromMarkdown: () => extractMermaidFromMarkdown,
+  generateExampleFromSchema: () => generateExampleFromSchema,
+  generateSchemaInstructions: () => generateSchemaInstructions,
   isJsonSchema: () => isJsonSchema,
   isJsonSchemaDefinition: () => isJsonSchemaDefinition,
   isMermaidSchema: () => isMermaidSchema,
@@ -79956,6 +79958,54 @@ __export(schemaUtils_exports, {
   validateMermaidResponse: () => validateMermaidResponse,
   validateXmlResponse: () => validateXmlResponse
 });
+function generateExampleFromSchema(schema, options = {}) {
+  const { debug = false } = options;
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    if (parsedSchema.type !== "object" || !parsedSchema.properties) {
+      return null;
+    }
+    const exampleObj = {};
+    for (const [key, value] of Object.entries(parsedSchema.properties)) {
+      if (value.type === "boolean") {
+        exampleObj[key] = false;
+      } else if (value.type === "number") {
+        exampleObj[key] = 0;
+      } else if (value.type === "string") {
+        exampleObj[key] = value.description || "your answer here";
+      } else if (value.type === "array") {
+        exampleObj[key] = [];
+      } else {
+        exampleObj[key] = {};
+      }
+    }
+    return exampleObj;
+  } catch (e3) {
+    if (debug) {
+      console.error("[DEBUG] generateExampleFromSchema: Failed to parse schema:", e3.message);
+    }
+    return null;
+  }
+}
+function generateSchemaInstructions(schema, options = {}) {
+  const { debug = false } = options;
+  let instructions = "\n\nIMPORTANT: When you provide your final answer using attempt_completion, you MUST format it as valid JSON matching this schema:\n\n";
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    instructions += `${JSON.stringify(parsedSchema, null, 2)}
+
+`;
+  } catch (e3) {
+    if (debug) {
+      console.error("[DEBUG] generateSchemaInstructions: Failed to parse schema:", e3.message);
+    }
+    instructions += `${schema}
+
+`;
+  }
+  instructions += "Your response inside attempt_completion must be ONLY valid JSON - no plain text, no explanations, no markdown.\n\nIMPORTANT: First complete the requested analysis/task thoroughly, then provide your final answer in the JSON format above.";
+  return instructions;
+}
 function enforceNoAdditionalProperties(schema) {
   if (!schema || typeof schema !== "object") {
     return schema;
@@ -83985,9 +84035,14 @@ You are working with a repository located at: ${searchDirectory}
           });
           const systemMessage = await this.getSystemMessage();
           let userMessage = { role: "user", content: message.trim() };
+          if (options.schema && !options._schemaFormatted) {
+            const schemaInstructions = generateSchemaInstructions(options.schema, { debug: this.debug });
+            userMessage.content = message.trim() + schemaInstructions;
+          }
           if (images && images.length > 0) {
+            const textContent = userMessage.content;
             userMessage.content = [
-              { type: "text", text: message.trim() },
+              { type: "text", text: textContent },
               ...images.map((image) => ({
                 type: "image",
                 image
@@ -84407,26 +84462,7 @@ Error: Unknown tool '${toolName}'. Available tools: ${allAvailableTools.join(",
                 break;
               }
               currentMessages.push({ role: "assistant", content: assistantResponseContent });
-              let reminderContent;
-              if (options.schema) {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
-
-Remember: Use proper XML format with BOTH opening and closing tags:
-
-<tool_name>
-<parameter>value</parameter>
-</tool_name>
-
-IMPORTANT: A schema was provided for the final output format.
-
-You MUST use attempt_completion to provide your answer:
-<attempt_completion>
-[Your complete answer here - provide in natural language, it will be automatically formatted to match the schema]
-</attempt_completion>
-
-Your response will be automatically formatted to JSON. You can provide your answer in natural language or as JSON - either will work.`;
-              } else {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
+              const reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
 
 Remember: Use proper XML format with BOTH opening and closing tags:
 
@@ -84438,7 +84474,6 @@ Or for quick completion if your previous response was already correct and comple
 <attempt_complete>
 
 IMPORTANT: When using <attempt_complete>, this must be the ONLY content in your response. No additional text, explanations, or other content should be included. This tag signals to reuse your previous response as the final answer.`;
-              }
               currentMessages.push({
                 role: "user",
                 content: reminderContent

package/cjs/index.cjs

@@ -77686,6 +77686,8 @@ __export(schemaUtils_exports, {
   createSchemaDefinitionCorrectionPrompt: () => createSchemaDefinitionCorrectionPrompt,
   decodeHtmlEntities: () => decodeHtmlEntities,
   extractMermaidFromMarkdown: () => extractMermaidFromMarkdown,
+  generateExampleFromSchema: () => generateExampleFromSchema,
+  generateSchemaInstructions: () => generateSchemaInstructions,
   isJsonSchema: () => isJsonSchema,
   isJsonSchemaDefinition: () => isJsonSchemaDefinition,
   isMermaidSchema: () => isMermaidSchema,
@@ -77698,6 +77700,54 @@ __export(schemaUtils_exports, {
   validateMermaidResponse: () => validateMermaidResponse,
   validateXmlResponse: () => validateXmlResponse
 });
+function generateExampleFromSchema(schema, options = {}) {
+  const { debug = false } = options;
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    if (parsedSchema.type !== "object" || !parsedSchema.properties) {
+      return null;
+    }
+    const exampleObj = {};
+    for (const [key, value] of Object.entries(parsedSchema.properties)) {
+      if (value.type === "boolean") {
+        exampleObj[key] = false;
+      } else if (value.type === "number") {
+        exampleObj[key] = 0;
+      } else if (value.type === "string") {
+        exampleObj[key] = value.description || "your answer here";
+      } else if (value.type === "array") {
+        exampleObj[key] = [];
+      } else {
+        exampleObj[key] = {};
+      }
+    }
+    return exampleObj;
+  } catch (e3) {
+    if (debug) {
+      console.error("[DEBUG] generateExampleFromSchema: Failed to parse schema:", e3.message);
+    }
+    return null;
+  }
+}
+function generateSchemaInstructions(schema, options = {}) {
+  const { debug = false } = options;
+  let instructions = "\n\nIMPORTANT: When you provide your final answer using attempt_completion, you MUST format it as valid JSON matching this schema:\n\n";
+  try {
+    const parsedSchema = typeof schema === "string" ? JSON.parse(schema) : schema;
+    instructions += `${JSON.stringify(parsedSchema, null, 2)}
+
+`;
+  } catch (e3) {
+    if (debug) {
+      console.error("[DEBUG] generateSchemaInstructions: Failed to parse schema:", e3.message);
+    }
+    instructions += `${schema}
+
+`;
+  }
+  instructions += "Your response inside attempt_completion must be ONLY valid JSON - no plain text, no explanations, no markdown.\n\nIMPORTANT: First complete the requested analysis/task thoroughly, then provide your final answer in the JSON format above.";
+  return instructions;
+}
 function enforceNoAdditionalProperties(schema) {
   if (!schema || typeof schema !== "object") {
     return schema;
@@ -81727,9 +81777,14 @@ You are working with a repository located at: ${searchDirectory}
           });
           const systemMessage = await this.getSystemMessage();
           let userMessage = { role: "user", content: message.trim() };
+          if (options.schema && !options._schemaFormatted) {
+            const schemaInstructions = generateSchemaInstructions(options.schema, { debug: this.debug });
+            userMessage.content = message.trim() + schemaInstructions;
+          }
           if (images && images.length > 0) {
+            const textContent = userMessage.content;
             userMessage.content = [
-              { type: "text", text: message.trim() },
+              { type: "text", text: textContent },
               ...images.map((image) => ({
                 type: "image",
                 image
@@ -82149,26 +82204,7 @@ Error: Unknown tool '${toolName}'. Available tools: ${allAvailableTools.join(",
                 break;
               }
               currentMessages.push({ role: "assistant", content: assistantResponseContent });
-              let reminderContent;
-              if (options.schema) {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
-
-Remember: Use proper XML format with BOTH opening and closing tags:
-
-<tool_name>
-<parameter>value</parameter>
-</tool_name>
-
-IMPORTANT: A schema was provided for the final output format.
-
-You MUST use attempt_completion to provide your answer:
-<attempt_completion>
-[Your complete answer here - provide in natural language, it will be automatically formatted to match the schema]
-</attempt_completion>
-
-Your response will be automatically formatted to JSON. You can provide your answer in natural language or as JSON - either will work.`;
-              } else {
-                reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
+              const reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
 
 Remember: Use proper XML format with BOTH opening and closing tags:
 
@@ -82180,7 +82216,6 @@ Or for quick completion if your previous response was already correct and comple
 <attempt_complete>
 
 IMPORTANT: When using <attempt_complete>, this must be the ONLY content in your response. No additional text, explanations, or other content should be included. This tag signals to reuse your previous response as the final answer.`;
-              }
               currentMessages.push({
                 role: "user",
                 content: reminderContent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc162",
+  "version": "0.6.0-rc164",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/agent/ProbeAgent.js

@@ -48,6 +48,7 @@ import {
   isJsonSchema,
   validateJsonResponse,
   createJsonCorrectionPrompt,
+  generateSchemaInstructions,
   isJsonSchemaDefinition,
   createSchemaDefinitionCorrectionPrompt,
   validateAndFixMermaidResponse
@@ -1455,11 +1456,18 @@ When troubleshooting:
 
       // Create user message with optional image support
       let userMessage = { role: 'user', content: message.trim() };
-      
+
+      // If schema is provided, prepend JSON format requirement to user message
+      if (options.schema && !options._schemaFormatted) {
+        const schemaInstructions = generateSchemaInstructions(options.schema, { debug: this.debug });
+        userMessage.content = message.trim() + schemaInstructions;
+      }
+
       // If images are provided, use multi-modal message format
       if (images && images.length > 0) {
+        const textContent = userMessage.content;
         userMessage.content = [
-          { type: 'text', text: message.trim() },
+          { type: 'text', text: textContent },
           ...images.map(image => ({
             type: 'image',
             image: image
@@ -2001,29 +2009,8 @@ When troubleshooting:
           // Add assistant response and ask for tool usage
           currentMessages.push({ role: 'assistant', content: assistantResponseContent });
 
-          // Build appropriate reminder message based on whether schema is provided
-          let reminderContent;
-          if (options.schema) {  // Apply for ANY schema, not just JSON schemas
-            // When schema is provided, AI must use attempt_completion to trigger schema formatting
-            reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
-
-Remember: Use proper XML format with BOTH opening and closing tags:
-
-<tool_name>
-<parameter>value</parameter>
-</tool_name>
-
-IMPORTANT: A schema was provided for the final output format.
-
-You MUST use attempt_completion to provide your answer:
-<attempt_completion>
-[Your complete answer here - provide in natural language, it will be automatically formatted to match the schema]
-</attempt_completion>
-
-Your response will be automatically formatted to JSON. You can provide your answer in natural language or as JSON - either will work.`;
-          } else {
-            // Standard reminder without schema
-            reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
+          // Standard reminder - schema was already provided in initial message
+          const reminderContent = `Please use one of the available tools to help answer the question, or use attempt_completion if you have enough information to provide a final answer.
 
 Remember: Use proper XML format with BOTH opening and closing tags:
 
@@ -2035,7 +2022,6 @@ Or for quick completion if your previous response was already correct and comple
 <attempt_complete>
 
 IMPORTANT: When using <attempt_complete>, this must be the ONLY content in your response. No additional text, explanations, or other content should be included. This tag signals to reuse your previous response as the final answer.`;
-          }
 
           currentMessages.push({
             role: 'user',

package/src/agent/schemaUtils.js

@@ -7,6 +7,74 @@ import { createMessagePreview } from '../tools/common.js';
 import { validate, fixText, extractMermaidBlocks } from '@probelabs/maid';
 import Ajv from 'ajv';
 
+/**
+ * Generate an example JSON object from a JSON schema
+ * @param {Object|string} schema - JSON schema object or string
+ * @param {Object} options - Options for generation
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {Object|null} - Example object, or null if schema cannot be processed
+ */
+export function generateExampleFromSchema(schema, options = {}) {
+  const { debug = false } = options;
+
+  try {
+    const parsedSchema = typeof schema === 'string' ? JSON.parse(schema) : schema;
+
+    if (parsedSchema.type !== 'object' || !parsedSchema.properties) {
+      return null;
+    }
+
+    const exampleObj = {};
+    for (const [key, value] of Object.entries(parsedSchema.properties)) {
+      if (value.type === 'boolean') {
+        exampleObj[key] = false;
+      } else if (value.type === 'number') {
+        exampleObj[key] = 0;
+      } else if (value.type === 'string') {
+        exampleObj[key] = value.description || 'your answer here';
+      } else if (value.type === 'array') {
+        exampleObj[key] = [];
+      } else {
+        exampleObj[key] = {};
+      }
+    }
+
+    return exampleObj;
+  } catch (e) {
+    if (debug) {
+      console.error('[DEBUG] generateExampleFromSchema: Failed to parse schema:', e.message);
+    }
+    return null;
+  }
+}
+
+/**
+ * Generate schema instructions for AI to follow
+ * @param {Object|string} schema - JSON schema object or string
+ * @param {Object} options - Options for generation
+ * @param {boolean} [options.debug=false] - Enable debug logging
+ * @returns {string} - Formatted schema instructions
+ */
+export function generateSchemaInstructions(schema, options = {}) {
+  const { debug = false } = options;
+
+  let instructions = '\n\nIMPORTANT: When you provide your final answer using attempt_completion, you MUST format it as valid JSON matching this schema:\n\n';
+
+  try {
+    const parsedSchema = typeof schema === 'string' ? JSON.parse(schema) : schema;
+    instructions += `${JSON.stringify(parsedSchema, null, 2)}\n\n`;
+  } catch (e) {
+    if (debug) {
+      console.error('[DEBUG] generateSchemaInstructions: Failed to parse schema:', e.message);
+    }
+    instructions += `${schema}\n\n`;
+  }
+
+  instructions += 'Your response inside attempt_completion must be ONLY valid JSON - no plain text, no explanations, no markdown.\n\nIMPORTANT: First complete the requested analysis/task thoroughly, then provide your final answer in the JSON format above.';
+
+  return instructions;
+}
+
 /**
  * Recursively apply additionalProperties: false to all object schemas
  * This ensures strict validation at all nesting levels