@x12i/ai-gateway 7.9.1

package/dist/flex-md-loader.js

@@ -0,0 +1,940 @@
+/**
+ * @x12i/flex-md Loader
+ *
+ * Handles ES Module loading and provides unified API for flex-md operations.
+ * @x12i/flex-md is an ES Module, so we use dynamic import() instead of require().
+ *
+ * Features:
+ * - extractJsonFromFlexMd: Extract and parse JSON from flex-md content
+ * - buildDynamicInstructions: Build output format instructions from schema objects (3.1+)
+ * - Embedded nx-md-parser: flex-md 4.x includes nx-md-parser functionality (no separate package needed)
+ * - Utilizes latest flex-md 4.x APIs: extractFromMarkdown, transformWithOfs, processResponseMarkdown
+ * - Memory/caching: flex-md 4.x functions may utilize internal memory/caching for performance
+ * - Native output format support: Extracts and uses flex-md native output formats from instructions
+ *   based on compliance level when no explicit format is provided
+ */
+import * as path from 'path';
+import { pathToFileURL } from 'url';
+let flexMdModule = null;
+let flexMdLoadError = null;
+let flexMdLoading = null;
+let hasLoggedFlexMdLoadWarning = false;
+// Preserve native dynamic import in both ESM and transpiled CJS output.
+// TypeScript can rewrite direct `import()` to `require()` in CJS builds.
+const importModule = new Function('specifier', 'return import(specifier)');
+async function importFlexMdModule() {
+    try {
+        return await importModule('@x12i/flex-md');
+    }
+    catch (esmImportError) {
+        // If package import condition is broken, import explicit CJS entry via file URL.
+        const { createRequire } = await importModule('module');
+        const requireFn = typeof require === 'function' ? require : createRequire(path.join(process.cwd(), 'noop.cjs'));
+        const cjsEntryPath = requireFn.resolve('@x12i/flex-md');
+        const cjsEntryUrl = pathToFileURL(cjsEntryPath).href;
+        try {
+            return await importModule(cjsEntryUrl);
+        }
+        catch (cjsImportError) {
+            const details = [
+                `import condition failed: ${esmImportError instanceof Error ? esmImportError.message : String(esmImportError)}`,
+                `cjs entry fallback failed: ${cjsImportError instanceof Error ? cjsImportError.message : String(cjsImportError)}`
+            ].join('\n');
+            throw new Error(details);
+        }
+    }
+}
+// nx-md-parser functionality is now embedded in flex-md, no separate loading needed
+/**
+ * Load flex-md module (ES Module) asynchronously
+ * Caches the result to avoid multiple imports
+ */
+export async function loadFlexMd() {
+    // Return cached module if available
+    if (flexMdModule) {
+        return flexMdModule;
+    }
+    // Return cached error if loading previously failed
+    if (flexMdLoadError) {
+        throw flexMdLoadError;
+    }
+    // If already loading, wait for that promise
+    if (flexMdLoading) {
+        return await flexMdLoading;
+    }
+    // Start loading
+    flexMdLoading = (async () => {
+        try {
+            // Always load through preserved dynamic import to avoid CJS require() rewrites.
+            const imported = await importFlexMdModule();
+            flexMdModule = imported.default || imported;
+            return flexMdModule;
+        }
+        catch (esImportError) {
+            const errorMsg = [
+                '@x12i/flex-md failed to load via dynamic import',
+                `reason: ${esImportError instanceof Error ? esImportError.message : String(esImportError)}`
+            ].join('\n');
+            flexMdLoadError = new Error(errorMsg);
+            throw flexMdLoadError;
+        }
+        finally {
+            flexMdLoading = null;
+        }
+    })();
+    return await flexMdLoading;
+}
+/**
+ * Transform markdown to JSON using flex-md's embedded nx-md-parser functionality
+ * flex-md 4.x includes nx-md-parser functionality, so we use flex-md's APIs directly
+ */
+async function transformWithFlexMdNxParser(content, schema, flexMd) {
+    try {
+        // flex-md 4.x includes nx-md-parser functionality
+        // Check if flex-md has JSONTransformer and Schema (from embedded nx-md-parser)
+        if (flexMd.JSONTransformer && flexMd.Schema) {
+            const { JSONTransformer, Schema } = flexMd;
+            // Convert schema to nx-md-parser Schema format
+            let nxSchema;
+            // If schema is already a Schema object (from Schema.object()), use it directly
+            if (schema && typeof schema === 'object' && 'toJSON' in schema) {
+                nxSchema = schema;
+            }
+            else if (schema && typeof schema === 'object' && schema.type === 'object' && schema.properties) {
+                // Convert JSON Schema to Schema builder format
+                nxSchema = convertJsonSchemaToSchemaBuilder(schema, Schema);
+            }
+            else if (schema && typeof schema === 'object') {
+                // Plain object - try to convert to Schema builder format
+                nxSchema = convertPlainObjectToSchemaBuilder(schema, Schema);
+            }
+            else {
+                return null; // Invalid schema format
+            }
+            const transformer = new JSONTransformer(nxSchema);
+            const result = transformer.transformMarkdown(content);
+            if (result && result.status !== 'failed' && result.result) {
+                return {
+                    json: result.result,
+                    method: `flex-md-nx-parser-${result.status || 'validated'}`
+                };
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        // Transformation failed, return null to fall back to other methods
+        return null;
+    }
+}
+/**
+ * Convert JSON Schema to nx-md-parser Schema format
+ * Supports both JSON Schema format and nx-md-parser Schema builder format
+ */
+function convertJsonSchemaToNxMdSchema(schema) {
+    // If it's already a nx-md-parser Schema object (has methods like toJSON), return as-is
+    if (schema && typeof schema === 'object' && 'toJSON' in schema) {
+        return schema;
+    }
+    // If it's a JSON Schema-like object, convert it
+    if (schema && typeof schema === 'object' && schema.type === 'object' && schema.properties) {
+        // We'll need to convert JSON Schema to nx-md-parser Schema format
+        // For now, return the schema as-is and let nx-md-parser handle it
+        // nx-md-parser supports JSON Schema format via createTransformerFromSchemaFile
+        return schema;
+    }
+    // If it's a plain object (simple format), try to infer structure
+    if (schema && typeof schema === 'object' && !Array.isArray(schema)) {
+        return schema;
+    }
+    return schema;
+}
+/**
+ * Convert JSON Schema properties to nx-md-parser Schema builder format
+ */
+function convertJsonSchemaToSchemaBuilder(jsonSchema, Schema) {
+    if (!jsonSchema.properties || typeof jsonSchema.properties !== 'object') {
+        throw new Error('Invalid JSON Schema: missing properties');
+    }
+    const schemaProps = {};
+    for (const [key, prop] of Object.entries(jsonSchema.properties)) {
+        const propObj = prop;
+        const propType = propObj.type;
+        if (propType === 'string') {
+            schemaProps[key] = Schema.string();
+        }
+        else if (propType === 'number' || propType === 'integer') {
+            schemaProps[key] = Schema.number();
+        }
+        else if (propType === 'boolean') {
+            schemaProps[key] = Schema.boolean();
+        }
+        else if (propType === 'array') {
+            const items = propObj.items;
+            if (items && items.type === 'string') {
+                schemaProps[key] = Schema.array(Schema.string());
+            }
+            else if (items && items.type === 'number') {
+                schemaProps[key] = Schema.array(Schema.number());
+            }
+            else if (items && items.type === 'boolean') {
+                schemaProps[key] = Schema.array(Schema.boolean());
+            }
+            else if (items && items.type === 'object') {
+                schemaProps[key] = Schema.array(convertJsonSchemaToSchemaBuilder(items, Schema));
+            }
+            else {
+                schemaProps[key] = Schema.array(Schema.string()); // Default to string array
+            }
+        }
+        else if (propType === 'object') {
+            schemaProps[key] = convertJsonSchemaToSchemaBuilder(propObj, Schema);
+        }
+        else {
+            // Default to string for unknown types
+            schemaProps[key] = Schema.string();
+        }
+    }
+    return Schema.object(schemaProps);
+}
+/**
+ * Convert plain object to nx-md-parser Schema builder format
+ * Infers types from example values
+ */
+function convertPlainObjectToSchemaBuilder(obj, Schema) {
+    const schemaProps = {};
+    for (const [key, value] of Object.entries(obj)) {
+        if (typeof value === 'string') {
+            schemaProps[key] = Schema.string();
+        }
+        else if (typeof value === 'number') {
+            schemaProps[key] = Schema.number();
+        }
+        else if (typeof value === 'boolean') {
+            schemaProps[key] = Schema.boolean();
+        }
+        else if (Array.isArray(value)) {
+            if (value.length > 0) {
+                const firstItem = value[0];
+                if (typeof firstItem === 'string') {
+                    schemaProps[key] = Schema.array(Schema.string());
+                }
+                else if (typeof firstItem === 'number') {
+                    schemaProps[key] = Schema.array(Schema.number());
+                }
+                else if (typeof firstItem === 'boolean') {
+                    schemaProps[key] = Schema.array(Schema.boolean());
+                }
+                else if (typeof firstItem === 'object') {
+                    schemaProps[key] = Schema.array(convertPlainObjectToSchemaBuilder(firstItem, Schema));
+                }
+                else {
+                    schemaProps[key] = Schema.array(Schema.string());
+                }
+            }
+            else {
+                schemaProps[key] = Schema.array(Schema.string()); // Empty array defaults to string array
+            }
+        }
+        else if (value && typeof value === 'object') {
+            schemaProps[key] = convertPlainObjectToSchemaBuilder(value, Schema);
+        }
+        else {
+            schemaProps[key] = Schema.string(); // Default to string
+        }
+    }
+    return Schema.object(schemaProps);
+}
+/**
+ * Extract flex-md native output format from instructions text
+ * Uses flex-md's parseOutputFormatSpec to parse format specifications
+ */
+async function extractFlexMdOutputFormatFromInstructions(instructions, complianceLevel) {
+    try {
+        const flexMd = await loadFlexMd();
+        // Use flex-md's parseOutputFormatSpec if available
+        if (flexMd.parseOutputFormatSpec && typeof flexMd.parseOutputFormatSpec === 'function') {
+            try {
+                const parsedSpec = flexMd.parseOutputFormatSpec(instructions);
+                if (parsedSpec && typeof parsedSpec === 'object' && parsedSpec !== null) {
+                    // Add compliance level if provided
+                    if (complianceLevel) {
+                        parsedSpec.strictness = complianceLevel;
+                    }
+                    return parsedSpec;
+                }
+            }
+            catch (e) {
+                // parseOutputFormatSpec failed, try manual extraction
+            }
+        }
+        // Fallback: Try to extract OUTPUT FORMAT section manually
+        const formatPatterns = [
+            /OUTPUT\s+FORMAT[:\s]*(?:\([^)]*\))?[:\s]*\n([\s\S]*?)$/im,
+            /OUTPUT\s+FORMAT[:\s]*(?:\([^)]*\))?[:\s]*\n([\s\S]*?)(?=\n\n(?:##|#|OUTPUT|$|\n[A-Z]{2,})|$)/i,
+            /^##+\s+Output\s+Format[:\s]*\n([\s\S]*?)(?=^##+\s+|$)/im,
+        ];
+        for (const pattern of formatPatterns) {
+            const match = instructions.match(pattern);
+            if (match && match[1]) {
+                const formatSpec = match[1].trim();
+                if (formatSpec.length >= 30) {
+                    // Try to parse with flex-md if available
+                    if (flexMd.parseOutputFormatSpec) {
+                        try {
+                            const parsedSpec = flexMd.parseOutputFormatSpec(formatSpec);
+                            if (parsedSpec && typeof parsedSpec === 'object' && parsedSpec !== null) {
+                                if (complianceLevel) {
+                                    parsedSpec.strictness = complianceLevel;
+                                }
+                                return parsedSpec;
+                            }
+                        }
+                        catch (e) {
+                            // Continue to next pattern
+                        }
+                    }
+                    // Return raw format spec as fallback
+                    return {
+                        format: formatSpec,
+                        strictness: complianceLevel || 'L0'
+                    };
+                }
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Extract and parse JSON from flex-md content (unstructured parsing only)
+ * Uses flex-md 4.2.0 APIs with latest features for unstructured markdown conversion
+ *
+ * ARCHITECTURE: This function only handles unstructured parsing at ai-gateway layer
+ * Schema-driven parsing happens at skills layer with nx-md-parser
+ *
+ * Supports flex-md native output formats from instructions:
+ * - Extracts flex-md output format from instructions when provided
+ * - Uses the extracted format based on compliance level for parsing
+ * - Falls back to simple markdown parsing when flex-md is unavailable
+ *
+ * @param content - The markdown content to parse (unstructured)
+ * @param options - Optional flex-md options:
+ *   - instructions: Instruction text to guide unstructured parsing
+ *   - complianceLevel: Compliance level ('L0' | 'L1' | 'L2' | 'L3') for format extraction
+ *   - spec: Pre-parsed flex-md output format spec
+ *   - Other flex-md options
+ * @returns Parsed JSON object and method used, or null if parsing fails
+ */
+export async function extractJsonFromFlexMd(content) {
+    // ARCHITECTURE: ai-gateway layer only handles unstructured parsing
+    // Schema-driven parsing is handled at skills layer with nx-md-parser
+    // No schema parameter - this layer doesn't know about schemas
+    try {
+        const flexMd = await loadFlexMd();
+        // Primary approach: Use markdownToJson() for simple markdown → JSON conversion
+        if (flexMd.markdownToJson && typeof flexMd.markdownToJson === 'function') {
+            try {
+                const json = flexMd.markdownToJson(content);
+                if (json && typeof json === 'object' && Object.keys(json).length > 0) {
+                    return {
+                        json,
+                        method: 'markdownToJson'
+                    };
+                }
+            }
+            catch (error) {
+                // markdownToJson failed, continue to other methods
+                console.warn('markdownToJson failed:', error instanceof Error ? error.message : String(error));
+            }
+        }
+        // Secondary approach: Use extractFromMarkdown for low-level section extraction
+        if (flexMd.extractFromMarkdown && typeof flexMd.extractFromMarkdown === 'function') {
+            try {
+                const result = flexMd.extractFromMarkdown(content);
+                if (result && typeof result === 'object' && result !== null) {
+                    const json = result.json || result.data || result.result || result;
+                    if (json && typeof json === 'object' && json !== null) {
+                        console.debug('extractJsonFromFlexMd: using extractFromMarkdown');
+                        console.debug('extractJsonFromFlexMd: json:', json);
+                        return { json, method: 'extractFromMarkdown' };
+                    }
+                }
+            }
+            catch (error) {
+                // extractFromMarkdown failed, continue
+                console.warn('extractFromMarkdown failed:', error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    catch (error) {
+        // flex-md loading failed, log once and continue to fallback.
+        if (!hasLoggedFlexMdLoadWarning) {
+            hasLoggedFlexMdLoadWarning = true;
+            console.warn('extractJsonFromFlexMd: flex-md library failed to load, using markdown parser fallback:', error instanceof Error ? error.message : String(error));
+        }
+    }
+    console.debug('extractJsonFromFlexMd: using markdown parser fallback');
+    console.debug('extractJsonFromFlexMd: content:', content);
+    // Final fallback: Parse markdown sections
+    return fallbackMarkdownParser(content);
+}
+/**
+ * Helper function to detect and parse markdown lists into arrays
+ */
+function parseMarkdownList(content) {
+    if (content.length === 0)
+        return '';
+    // Check if content contains actual list markers
+    const hasBulletPoints = content.some(line => line.trim().startsWith('- '));
+    const hasNumberedItems = content.some(line => /^\d+\.\s/.test(line.trim()));
+    // If no list markers found, return as joined string
+    if (!hasBulletPoints && !hasNumberedItems) {
+        return content.join('\n').trim();
+    }
+    // Parse list items
+    const listItems = [];
+    let currentItem = '';
+    for (const line of content) {
+        const trimmed = line.trim();
+        // Check for bullet points (- item)
+        if (trimmed.startsWith('- ')) {
+            // Save previous item if exists
+            if (currentItem) {
+                listItems.push(currentItem.trim());
+            }
+            // Start new item
+            currentItem = trimmed.substring(2).trim();
+        }
+        // Check for numbered items (1. item, 2. item, etc.)
+        else if (/^\d+\.\s/.test(trimmed)) {
+            // Save previous item if exists
+            if (currentItem) {
+                listItems.push(currentItem.trim());
+            }
+            // Start new item
+            const match = trimmed.match(/^\d+\.\s(.+)$/);
+            currentItem = match ? match[1].trim() : trimmed;
+        }
+        // Continuation of current item
+        else if (currentItem && trimmed) {
+            currentItem += ' ' + trimmed;
+        }
+        // If we haven't started an item yet and this is content
+        else if (!currentItem && trimmed) {
+            currentItem = trimmed;
+        }
+    }
+    // Add final item
+    if (currentItem) {
+        listItems.push(currentItem.trim());
+    }
+    // Return array if we have multiple items or explicit list markers, otherwise string
+    return listItems.length > 1 || hasBulletPoints || hasNumberedItems ? listItems : content.join('\n').trim();
+}
+/**
+ * Simple markdown parser for unstructured content (fallback when flex-md unavailable)
+ */
+function fallbackMarkdownParser(content) {
+    const result = {};
+    const detectedHeaders = [];
+    // Simple section extraction based on markdown headers
+    const lines = content.split('\n');
+    let currentSection = '';
+    let currentContent = [];
+    for (const line of lines) {
+        // Check for markdown headers (# ## ###) - improved regex
+        const headerMatch = line.match(/^(#{1,6})\s*(.+?)\s*$/);
+        if (headerMatch) {
+            // Save previous section if exists
+            if (currentSection && currentContent.length > 0) {
+                // Convert header to camelCase key
+                const key = currentSection
+                    .toLowerCase()
+                    .replace(/[^a-zA-Z0-9\s]/g, '') // Remove special chars
+                    .replace(/\s+/g, ' ') // Normalize spaces
+                    .trim()
+                    .replace(/\s+(\w)/g, (_, letter) => letter.toUpperCase()); // camelCase
+                result[key] = parseMarkdownList(currentContent);
+                detectedHeaders.push(key);
+            }
+            // Start new section
+            currentSection = headerMatch[2].trim();
+            currentContent = [];
+        }
+        else if (currentSection) {
+            // Add line to current section
+            currentContent.push(line);
+        }
+    }
+    // Save last section
+    if (currentSection && currentContent.length > 0) {
+        const key = currentSection
+            .toLowerCase()
+            .replace(/[^a-zA-Z0-9\s]/g, '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .replace(/\s+(\w)/g, (_, letter) => letter.toUpperCase());
+        result[key] = parseMarkdownList(currentContent);
+        detectedHeaders.push(key);
+    }
+    // Debug logging for incomplete parsing
+    console.log('Fallback parser detected headers:', detectedHeaders);
+    const expectedHeaders = ['shortAnswer', 'fullAnswer', 'assumptions', 'unknowns', 'evidence'];
+    const missingHeaders = expectedHeaders.filter(h => !detectedHeaders.includes(h));
+    if (missingHeaders.length > 0) {
+        console.log('Fallback parser missing expected headers:', missingHeaders);
+    }
+    // If we extracted some structure, return it
+    if (Object.keys(result).length > 0) {
+        return {
+            json: result,
+            method: 'fallback-markdown-parser'
+        };
+    }
+    // No structure found, return raw text
+    return {
+        json: { rawText: content },
+        method: 'fallback-raw-text'
+    };
+}
+/**
+ * Fallback JSON extraction when flex-md is not available
+ */
+function extractJsonFallback(content) {
+    // Look for fenced JSON blocks
+    const jsonBlockRegex = /```(?:json)?\s*\n?([\s\S]*?)\n?```/g;
+    let match;
+    while ((match = jsonBlockRegex.exec(content)) !== null) {
+        try {
+            const jsonContent = match[1].trim();
+            const parsed = JSON.parse(jsonContent);
+            if (parsed !== null && typeof parsed === 'object') {
+                return {
+                    json: parsed,
+                    method: 'fallback-json-block'
+                };
+            }
+        }
+        catch (e) {
+            // Continue to next block
+        }
+    }
+    // No structured data found, return raw text wrapper
+    return {
+        json: { rawText: content },
+        method: 'fallback-raw-text'
+    };
+}
+/**
+ * Check if flex-md module is available
+ */
+export function isFlexMdAvailable() {
+    return flexMdModule !== null;
+}
+/**
+ * Get maxTokens for a model from flex-md if available
+ * Tries various flex-md APIs to get model information and maxTokens
+ *
+ * @param provider - Provider name (e.g., 'openai', 'anthropic')
+ * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
+ * @returns maxTokens if found, null otherwise
+ */
+export async function getModelMaxTokensFromFlexMd(provider, model) {
+    try {
+        const flexMd = await loadFlexMd();
+        if (!flexMd || typeof flexMd !== 'object') {
+            return null;
+        }
+        // Try various possible function names that flex-md might export
+        const possibleFunctions = [
+            'getModel',
+            'getModelInfo',
+            'getModelContext',
+            'getMaxTokens',
+            'modelRegistry',
+            'getModelMaxTokens'
+        ];
+        for (const funcName of possibleFunctions) {
+            if (flexMd[funcName] && typeof flexMd[funcName] === 'function') {
+                try {
+                    const result = flexMd[funcName](provider, model);
+                    // Handle different possible return formats
+                    if (result) {
+                        // Case 1: Direct number
+                        if (typeof result === 'number') {
+                            return result;
+                        }
+                        // Case 2: Object with maxTokens or maxOutputTokens property
+                        if (typeof result === 'object') {
+                            if (typeof result.maxTokens === 'number') {
+                                return result.maxTokens;
+                            }
+                            if (typeof result.maxOutputTokens === 'number') {
+                                return result.maxOutputTokens;
+                            }
+                            // Case 3: Nested context object
+                            if (result.context) {
+                                if (typeof result.context.maxTokens === 'number') {
+                                    return result.context.maxTokens;
+                                }
+                                if (typeof result.context.maxOutputTokens === 'number') {
+                                    return result.context.maxOutputTokens;
+                                }
+                            }
+                        }
+                    }
+                }
+                catch (e) {
+                    // Function exists but call failed, continue to next
+                    continue;
+                }
+            }
+        }
+        // Try registry pattern if available
+        if (flexMd.modelRegistry && typeof flexMd.modelRegistry === 'object') {
+            const registry = flexMd.modelRegistry;
+            const key = `${provider}/${model}`;
+            const altKey = `${provider}:${model}`;
+            const modelInfo = registry[key] || registry[altKey] || registry[model];
+            if (modelInfo) {
+                if (typeof modelInfo.maxTokens === 'number') {
+                    return modelInfo.maxTokens;
+                }
+                if (typeof modelInfo.maxOutputTokens === 'number') {
+                    return modelInfo.maxOutputTokens;
+                }
+                if (modelInfo.context && typeof modelInfo.context.maxOutputTokens === 'number') {
+                    return modelInfo.context.maxOutputTokens;
+                }
+            }
+        }
+        return null;
+    }
+    catch (error) {
+        // flex-md not available or doesn't have model info functionality
+        return null;
+    }
+}
+/**
+ * Get flex-md module directly (must call loadFlexMd() first)
+ */
+export function getFlexMdModule() {
+    if (!flexMdModule) {
+        throw new Error('flex-md module not loaded. Call loadFlexMd() first.');
+    }
+    return flexMdModule;
+}
+/**
+ * Build dynamic instructions from an object/schema (flex-md 3.1+ feature)
+ * Takes an object (like a JSON schema) and generates flex-md format instructions
+ *
+ * @param schemaObject - The object/schema to generate instructions from
+ * @param options - Optional configuration for instruction generation
+ * @returns Generated flex-md format instructions as string
+ */
+/**
+ * Manually generates OUTPUT FORMAT instructions from JSON Schema
+ * This is a fallback when flex-md's buildDynamicInstructions doesn't exist
+ */
+function generateFormatInstructionsFromSchema(schema, options) {
+    const parts = [];
+    if (options?.title || options?.description) {
+        parts.push(`Output Format: ${options.title || 'Structured Data'}`);
+        if (options.description) {
+            parts.push(options.description);
+        }
+    }
+    // Extract properties from JSON Schema
+    if (schema.type === 'object' && schema.properties) {
+        parts.push('\nReturn a JSON object with the following structure:');
+        parts.push('\n```json');
+        parts.push(JSON.stringify(schema, null, 2));
+        parts.push('```');
+        // Add property descriptions if available
+        const propertyDescriptions = [];
+        for (const [key, prop] of Object.entries(schema.properties)) {
+            if (typeof prop === 'object' && prop !== null) {
+                const propObj = prop;
+                const desc = propObj.description || '';
+                const type = propObj.type || 'unknown';
+                const enumVals = propObj.enum ? ` (one of: ${propObj.enum.join(', ')})` : '';
+                if (desc || enumVals) {
+                    propertyDescriptions.push(`- \`${key}\` (${type})${enumVals}: ${desc || 'No description'}`);
+                }
+                else {
+                    propertyDescriptions.push(`- \`${key}\` (${type})`);
+                }
+            }
+        }
+        if (propertyDescriptions.length > 0) {
+            parts.push('\nProperties:');
+            parts.push(...propertyDescriptions);
+        }
+        // Add required fields note
+        if (schema.required && Array.isArray(schema.required) && schema.required.length > 0) {
+            parts.push(`\nRequired fields: ${schema.required.join(', ')}`);
+        }
+    }
+    else {
+        // Not a standard JSON Schema object, just show the schema
+        parts.push('\nReturn a JSON object matching this schema:');
+        parts.push('\n```json');
+        parts.push(JSON.stringify(schema, null, 2));
+        parts.push('```');
+    }
+    parts.push('\n\nIMPORTANT: Return your answer as JSON inside the markdown fenced block. The JSON must match the schema above exactly.');
+    return parts.join('\n');
+}
+export async function buildDynamicInstructions(schemaObject, options) {
+    try {
+        const flexMd = await loadFlexMd();
+        // Check if dynamic instruction feature is available (flex-md 3.1+)
+        if (flexMd.buildDynamicInstructions && typeof flexMd.buildDynamicInstructions === 'function') {
+            const result = flexMd.buildDynamicInstructions(schemaObject, options);
+            const finalResult = typeof result === 'string' ? result : (result?.instructions || result?.format || null);
+            return finalResult;
+        }
+        // Fallback: Generate format instructions manually from JSON Schema
+        const manualInstructions = generateFormatInstructionsFromSchema(schemaObject, options);
+        return manualInstructions;
+    }
+    catch (error) {
+        // On error, try manual fallback
+        try {
+            const manualInstructions = generateFormatInstructionsFromSchema(schemaObject, options);
+            return manualInstructions;
+        }
+        catch (fallbackError) {
+            return null;
+        }
+    }
+}
+/**
+ * Enrich instructions with flex-md compliance guidance (flex-md 3.0+ feature)
+ * Adds appropriate flex-md format instructions based on strictness level
+ *
+ * @param instructions - Base instructions text
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Enriched instructions with flex-md guidance
+ */
+export async function enrichInstructionsWithFlexMd(instructions, strictnessLevel = 'L0') {
+    try {
+        const flexMd = await loadFlexMd();
+        // Use native flex-md function if available (flex-md 3.2+)
+        if (flexMd.enrichInstructionsWithFlexMd && typeof flexMd.enrichInstructionsWithFlexMd === 'function') {
+            const result = flexMd.enrichInstructionsWithFlexMd(instructions, strictnessLevel);
+            return typeof result === 'string' ? result : instructions;
+        }
+        // Fallback to enrichInstructions if native function not available
+        if (flexMd.enrichInstructions && typeof flexMd.enrichInstructions === 'function') {
+            const result = flexMd.enrichInstructions(instructions, { strictness: strictnessLevel });
+            return typeof result === 'string' ? result : instructions;
+        }
+        // Fallback: return original instructions if function not available
+        return instructions;
+    }
+    catch (error) {
+        // On error, return original instructions
+        return instructions;
+    }
+}
+/**
+ * Get strictness defaults for a compliance level (flex-md 3.0+ feature)
+ * Returns configuration object for the specified compliance level
+ *
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Configuration object with level-specific defaults
+ */
+export async function getStrictnessDefaults(strictnessLevel = 'L0') {
+    try {
+        const flexMd = await loadFlexMd();
+        if (flexMd.strictnessDefaults && typeof flexMd.strictnessDefaults === 'function') {
+            return flexMd.strictnessDefaults(strictnessLevel);
+        }
+        return null;
+    }
+    catch (error) {
+        return null;
+    }
+}
+/**
+ * Enforce flex-md format in instructions (flex-md 3.0+ feature)
+ * Adds enforcement rules based on output format spec and strictness level
+ *
+ * @param instructions - Base instructions text
+ * @param outputFormatSpec - Output format specification (optional)
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Instructions with flex-md enforcement rules
+ */
+export async function enforceFlexMdFormat(instructions, outputFormatSpec, strictnessLevel = 'L0') {
+    try {
+        const flexMd = await loadFlexMd();
+        if (flexMd.enforceFlexMd && typeof flexMd.enforceFlexMd === 'function') {
+            const spec = outputFormatSpec || { strictness: strictnessLevel };
+            if (!spec.strictness) {
+                spec.strictness = strictnessLevel;
+            }
+            const result = flexMd.enforceFlexMd(instructions, spec);
+            return typeof result === 'string' ? result : instructions;
+        }
+        // Fallback: return original instructions if function not available
+        return instructions;
+    }
+    catch (error) {
+        // On error, return original instructions
+        return instructions;
+    }
+}
+/**
+ * Check if instructions meet a specific flex-md compliance level
+ *
+ * @param instructions - Instructions text to check
+ * @param complianceLevel - Required compliance level
+ * @returns true if instructions meet the compliance level
+ */
+export async function hasFlexMdContract(instructions, complianceLevel = 'L0') {
+    if (!instructions || instructions.trim() === '') {
+        return false;
+    }
+    try {
+        const flexMd = await loadFlexMd();
+        // Use native flex-md function if available (flex-md 3.2+)
+        if (flexMd.hasFlexMdContract && typeof flexMd.hasFlexMdContract === 'function') {
+            try {
+                const result = flexMd.hasFlexMdContract(instructions, complianceLevel);
+                return typeof result === 'boolean' ? result : false;
+            }
+            catch (e) {
+                // Native function might have different signature, fall through
+            }
+        }
+        // Fallback: Check if validateMarkdownAgainstOfs is available
+        if (flexMd.validateMarkdownAgainstOfs && typeof flexMd.validateMarkdownAgainstOfs === 'function') {
+            try {
+                // Try to validate - this might require a spec, so we catch errors
+                const result = flexMd.validateMarkdownAgainstOfs(instructions, { strictness: complianceLevel });
+                // If validation passes, instructions meet compliance
+                if (result && result.valid !== false) {
+                    return true;
+                }
+            }
+            catch (e) {
+                // Validation function might need more parameters, fall through to pattern matching
+            }
+        }
+    }
+    catch (error) {
+        // flex-md SDK not available or error - fall through to pattern matching
+    }
+    // Fallback: Pattern-based checking
+    const text = instructions.toLowerCase();
+    // Check for key flex-md enforcement phrases
+    const flexMdIndicators = [
+        'markdown',
+        'fenced block',
+        '```markdown',
+        '```json',
+        'reply in markdown',
+        'return your entire answer'
+    ];
+    // Check for enforcement language based on compliance level
+    const enforcementIndicators = [];
+    if (complianceLevel === 'L2' || complianceLevel === 'L3') {
+        // L2/L3 require fenced block container
+        enforcementIndicators.push('fenced block', '```markdown', 'single ```markdown', 'entire answer inside', 'nothing else');
+    }
+    if (complianceLevel === 'L1' || complianceLevel === 'L2' || complianceLevel === 'L3') {
+        // L1+ requires section headings
+        enforcementIndicators.push('section', 'heading', 'include these');
+    }
+    // Must have at least one flex-md indicator AND appropriate enforcement indicators
+    const hasFlexMd = flexMdIndicators.some(indicator => text.includes(indicator));
+    const hasEnforcement = enforcementIndicators.length === 0 ||
+        enforcementIndicators.some(indicator => text.includes(indicator));
+    return hasFlexMd && hasEnforcement;
+}
+/**
+ * Detect the actual compliance level that instructions meet
+ * Checks from highest (L3) to lowest (L0) to find the highest level met
+ *
+ * @param instructions - Instructions text to check
+ * @returns The highest compliance level met ('L0' | 'L1' | 'L2' | 'L3' | null if none)
+ */
+export async function detectComplianceLevel(instructions) {
+    if (!instructions || instructions.trim() === '') {
+        return null;
+    }
+    try {
+        const flexMd = await loadFlexMd();
+        // Check from highest to lowest level using native hasFlexMdContract
+        const levels = ['L3', 'L2', 'L1', 'L0'];
+        // Use native hasFlexMdContract if available (flex-md 3.2+)
+        if (flexMd.hasFlexMdContract && typeof flexMd.hasFlexMdContract === 'function') {
+            for (const level of levels) {
+                try {
+                    const meetsLevel = flexMd.hasFlexMdContract(instructions, level);
+                    if (meetsLevel === true) {
+                        return level;
+                    }
+                }
+                catch (e) {
+                    // Continue to next level
+                }
+            }
+        }
+        else {
+            // Fallback: Use our wrapper function
+            for (const level of levels) {
+                const meetsLevel = await hasFlexMdContract(instructions, level);
+                if (meetsLevel) {
+                    return level;
+                }
+            }
+        }
+        // If flex-md SDK is available, try using validateMarkdownAgainstOfs directly
+        if (flexMd.validateMarkdownAgainstOfs && typeof flexMd.validateMarkdownAgainstOfs === 'function') {
+            // Try L3 first (highest)
+            for (const level of levels) {
+                try {
+                    const result = flexMd.validateMarkdownAgainstOfs(instructions, { strictness: level });
+                    if (result && result.valid !== false) {
+                        return level;
+                    }
+                }
+                catch (e) {
+                    // Continue to next level
+                }
+            }
+        }
+        // Fallback: Pattern-based detection
+        const text = instructions.toLowerCase();
+        // Check for L3 indicators (strictest)
+        const hasL3Indicators = text.includes('fenced block') &&
+            text.includes('section') &&
+            (text.includes('required') || text.includes('must'));
+        // Check for L2 indicators (container + sections)
+        const hasL2Indicators = (text.includes('```markdown') || text.includes('fenced block')) &&
+            (text.includes('section') || text.includes('heading'));
+        // Check for L1 indicators (sections only)
+        const hasL1Indicators = (text.includes('section') || text.includes('heading')) &&
+            text.includes('markdown');
+        // Check for L0 indicators (basic markdown)
+        const hasL0Indicators = text.includes('markdown');
+        if (hasL3Indicators)
+            return 'L3';
+        if (hasL2Indicators)
+            return 'L2';
+        if (hasL1Indicators)
+            return 'L1';
+        if (hasL0Indicators)
+            return 'L0';
+        return null;
+    }
+    catch (error) {
+        // On error, return null (unknown)
+        return null;
+    }
+}