@x12i/ai-gateway 7.9.1

package/dist/troubleshooting-helper.js

@@ -0,0 +1,596 @@
+/**
+ * Troubleshooting Helper Toolbox
+ *
+ * Utility functions to diagnose and test AI Gateway issues
+ * Based on TROUBLESHOOTING.md guide
+ */
+/**
+ * Converts JSON Schema to simple, human-readable format for LLM instructions
+ *
+ * Supports both formats:
+ * - JSON Schema format: { "type": "object", "properties": {...} }
+ * - Simple format: { "emails": ["<string> description"] }
+ *
+ * If schema is already in simple format, returns it as-is.
+ * If schema is in JSON Schema format, converts it to simple format.
+ *
+ * Simple format example:
+ * {
+ *   "emails": [
+ *     "<string> A valid email address extracted from the input text"
+ *   ]
+ * }
+ *
+ * Format rules:
+ * - Arrays: Show as array with single example item containing type hint + description
+ * - Objects: Show nested structure recursively
+ * - Primitives: Show as type hint with description
+ * - Required fields: Implicit (just present in structure)
+ *
+ * @param schema - Schema object (JSON Schema or simple format)
+ * @returns Schema in simple format
+ */
+export function convertSchemaToSimpleFormat(schema) {
+    if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        return {};
+    }
+    // Check if schema is already in simple format (no "type" or "properties" keys)
+    // Simple format: { "emails": ["<string> description"] }
+    // JSON Schema: { "type": "object", "properties": {...} }
+    const hasJsonSchemaStructure = schema.type !== undefined || schema.properties !== undefined;
+    if (!hasJsonSchemaStructure) {
+        // Already in simple format - return as-is
+        return schema;
+    }
+    // Convert from JSON Schema to simple format
+    const simpleSchema = {};
+    const properties = schema.properties || {};
+    const required = schema.required || [];
+    for (const [fieldName, fieldDef] of Object.entries(properties)) {
+        const field = fieldDef;
+        const fieldType = field.type || 'any';
+        const fieldDesc = field.description || '';
+        // Handle different field types
+        if (fieldType === 'array') {
+            const items = field.items || {};
+            const itemType = items.type || 'any';
+            const itemDesc = items.description || '';
+            // Build array item example: "<type> description"
+            let itemExample;
+            if (itemType === 'string') {
+                itemExample = `<string>${itemDesc ? ' ' + itemDesc : ''}`;
+            }
+            else if (itemType === 'number' || itemType === 'integer') {
+                itemExample = `<${itemType}>${itemDesc ? ' ' + itemDesc : ''}`;
+            }
+            else if (itemType === 'boolean') {
+                itemExample = `<boolean>${itemDesc ? ' ' + itemDesc : ''}`;
+            }
+            else if (itemType === 'object' && items.properties) {
+                // For object arrays, show nested structure as string representation
+                const nestedSimple = convertSchemaToSimpleFormat(items);
+                const nestedJson = JSON.stringify(nestedSimple, null, 2);
+                itemExample = `<object> ${itemDesc || 'Object with structure:'}\n${nestedJson}`;
+            }
+            else {
+                itemExample = `<${itemType}>${itemDesc ? ' ' + itemDesc : ''}`;
+            }
+            // Array format: [ "<type> description" ]
+            simpleSchema[fieldName] = [itemExample];
+        }
+        else if (fieldType === 'object' && field.properties) {
+            // Recursively convert nested objects
+            simpleSchema[fieldName] = convertSchemaToSimpleFormat(field);
+        }
+        else {
+            // For primitive types, show as type hint with description
+            // Format: "<type> description" or just "<type>" if no description
+            let value;
+            if (fieldType === 'string') {
+                value = `<string>${fieldDesc ? ' ' + fieldDesc : ''}`;
+            }
+            else if (fieldType === 'number' || fieldType === 'integer') {
+                value = `<${fieldType}>${fieldDesc ? ' ' + fieldDesc : ''}`;
+            }
+            else if (fieldType === 'boolean') {
+                value = `<boolean>${fieldDesc ? ' ' + fieldDesc : ''}`;
+            }
+            else {
+                value = `<${fieldType}>${fieldDesc ? ' ' + fieldDesc : ''}`;
+            }
+            simpleSchema[fieldName] = value;
+        }
+    }
+    return simpleSchema;
+}
+/**
+ * Validates a single object type structure
+ * Handles both string (standard type) and object (custom type) formats
+ */
+function validateSingleObjectType(objType, context, index) {
+    const errors = [];
+    const warnings = [];
+    const indexLabel = index !== undefined ? `[${index}]` : '';
+    const fullContext = `${context}${indexLabel}`;
+    // If it's a string (standard type), validation passes
+    if (typeof objType === 'string') {
+        if (!objType.trim()) {
+            errors.push(`${fullContext} must be a non-empty string`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings
+        };
+    }
+    // Validate type field
+    if (!objType.type || typeof objType.type !== 'string' || objType.type.trim().length === 0) {
+        errors.push(`${fullContext}.type is required and must be a non-empty string`);
+    }
+    // Validate whenToUse field
+    if (!objType.whenToUse || typeof objType.whenToUse !== 'string' || objType.whenToUse.trim().length === 0) {
+        errors.push(`${fullContext}.whenToUse is required and must be a non-empty string`);
+    }
+    // Validate schema if provided (supports both JSON Schema and simple format)
+    if (objType.schema !== undefined) {
+        if (typeof objType.schema !== 'object' || objType.schema === null || Array.isArray(objType.schema)) {
+            errors.push(`${fullContext}.schema must be an object (JSON Schema or simple format)`);
+        }
+        else {
+            const schema = objType.schema;
+            // Validate properties if present (JSON Schema format)
+            if (schema.properties !== undefined) {
+                if (typeof schema.properties !== 'object' || schema.properties === null || Array.isArray(schema.properties)) {
+                    errors.push(`${fullContext}.schema.properties must be an object`);
+                }
+            }
+            // Validate required if present (JSON Schema format)
+            if (schema.required !== undefined) {
+                if (!Array.isArray(schema.required)) {
+                    errors.push(`${fullContext}.schema.required must be an array`);
+                }
+            }
+            // Warn about missing type in JSON Schema format
+            if (schema.type === undefined && schema.properties !== undefined) {
+                warnings.push(`${fullContext}.schema.type is recommended for JSON Schema format (should be 'object')`);
+            }
+        }
+    }
+    else {
+        warnings.push(`${fullContext}.schema is optional but recommended for better validation`);
+    }
+    // Validate description if provided
+    if (objType.description !== undefined && typeof objType.description !== 'string') {
+        errors.push(`${fullContext}.description must be a string`);
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Validates AIRequest structure
+ */
+export function validateAIRequest(request) {
+    const errors = [];
+    const warnings = [];
+    // Validate base fields
+    if (!request.jobId) {
+        errors.push('jobId is required');
+    }
+    if (!request.agentId) {
+        errors.push('agentId is required');
+    }
+    if (!request.instructions) {
+        warnings.push('instructions is optional (system-context will be used as fallback)');
+    }
+    if (!request.prompt) {
+        errors.push('Prompt is required (input field has been removed - use workingMemory.input instead)');
+    }
+    // Validate config
+    if (!request.config) {
+        errors.push('config is required');
+    }
+    else {
+        if (!request.config.model) {
+            errors.push('config.model is required (no default models allowed)');
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Validates JSON string
+ */
+export function validateJSON(jsonString) {
+    const errors = [];
+    const warnings = [];
+    if (!jsonString || typeof jsonString !== 'string') {
+        errors.push('Input must be a non-empty string');
+        return { valid: false, errors, warnings };
+    }
+    try {
+        const parsed = JSON.parse(jsonString);
+        if (typeof parsed !== 'object' || parsed === null) {
+            warnings.push('Parsed JSON is not an object (might be a primitive value)');
+        }
+        return { valid: true, errors, warnings };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        errors.push(`Invalid JSON: ${errorMessage}`);
+        // Try to extract JSON from string
+        const jsonMatch = jsonString.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            warnings.push('JSON object found in string - consider extracting it');
+            try {
+                JSON.parse(jsonMatch[0]);
+                warnings.push('Extracted JSON is valid');
+            }
+            catch {
+                warnings.push('Extracted JSON is also invalid');
+            }
+        }
+        return { valid: false, errors, warnings };
+    }
+}
+/**
+ * Extracts JSON from text (handles markdown code blocks, etc.)
+ */
+export function extractJSON(text) {
+    if (!text || typeof text !== 'string') {
+        return { json: null, method: 'none' };
+    }
+    // Try direct parse first
+    try {
+        JSON.parse(text);
+        return { json: text, method: 'direct' };
+    }
+    catch {
+        // Continue to extraction
+    }
+    // Try extracting from markdown code block
+    const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+    if (codeBlockMatch) {
+        try {
+            const extracted = codeBlockMatch[1].trim();
+            JSON.parse(extracted);
+            return { json: extracted, method: 'markdown-code-block' };
+        }
+        catch {
+            // Continue
+        }
+    }
+    // Try extracting JSON object
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (jsonMatch) {
+        try {
+            const extracted = jsonMatch[0];
+            JSON.parse(extracted);
+            return { json: extracted, method: 'regex-extraction' };
+        }
+        catch {
+            // Continue
+        }
+    }
+    return { json: null, method: 'none' };
+}
+/**
+ * Validates response structure
+ */
+export function validateResponse(response) {
+    const errors = [];
+    const warnings = [];
+    if (!response.content) {
+        errors.push('Response content is missing');
+    }
+    else {
+        // Check for "[object Object]" string
+        if (response.content === '[object Object]') {
+            errors.push('Response content is "[object Object]" string - content normalization failed');
+        }
+        // Validate JSON if it's supposed to be JSON
+        if (response.metadata?.contentType === 'object' || response.metadata?.contentType === 'array') {
+            const jsonResult = validateJSON(response.content);
+            if (!jsonResult.valid) {
+                errors.push(...jsonResult.errors);
+                warnings.push(...jsonResult.warnings);
+            }
+        }
+    }
+    // Check parsedContent
+    if (response.metadata?.contentType === 'object' || response.metadata?.contentType === 'array') {
+        if (!response.parsedContent) {
+            warnings.push('parsedContent is undefined but contentType suggests it should be parsed');
+        }
+    }
+    // Check validation results if schema validation was enabled
+    if (response.metadata?.outputValidationPassed !== undefined) {
+        if (!response.metadata.outputValidationPassed) {
+            const validationErrors = response.metadata.outputValidationErrors || [];
+            if (validationErrors.length > 0) {
+                warnings.push(`Schema validation failed: ${validationErrors.join(', ')}`);
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings
+    };
+}
+/**
+ * Collects comprehensive diagnostic information
+ */
+export function diagnoseRequest(request) {
+    // AIRequest is distinguished by having primaryObjectType, objectTypes, or other AIRequest-specific fields
+    const isAIRequest = 'primaryObjectType' in request ||
+        ('objectTypes' in request && Array.isArray(request.objectTypes)) ||
+        'skillId' in request ||
+        'masterSkillId' in request ||
+        'reasoningEncrypted' in request;
+    const diagnostic = {
+        request: {
+            hasJobId: !!request.jobId,
+            hasAgentId: !!request.agentId,
+            hasInstructions: !!request.instructions,
+            hasPrompt: !!request.prompt,
+            hasWorkingMemory: !!request.workingMemory,
+            hasConfig: !!request.config,
+            hasModel: !!request.config?.model,
+            hasProvider: !!request.config?.provider
+        }
+    };
+    return diagnostic;
+}
+/**
+ * Diagnoses response issues
+ */
+export function diagnoseResponse(response) {
+    if (!response) {
+        return {
+            hasContent: false,
+            isJSON: false,
+            hasParsedContent: false,
+            contentType: 'unknown'
+        };
+    }
+    const hasContent = !!response.content;
+    let isJSON = false;
+    let contentType = 'unknown';
+    if (hasContent && typeof response.content === 'string') {
+        try {
+            JSON.parse(response.content);
+            isJSON = true;
+            contentType = 'object';
+        }
+        catch {
+            isJSON = false;
+            contentType = 'string';
+        }
+    }
+    return {
+        hasContent,
+        isJSON,
+        hasParsedContent: !!response.parsedContent,
+        contentType: response.metadata?.contentType || contentType,
+        validationPassed: response.metadata?.outputValidationPassed,
+        validationErrors: response.metadata?.outputValidationErrors
+    };
+}
+/**
+ * Tests if a provider/model combination supports JSON mode
+ */
+export function supportsJSONMode(provider, model) {
+    if (!provider || !model) {
+        return { supported: false, notes: 'Provider and model must be specified' };
+    }
+    const providerLower = provider.toLowerCase();
+    const modelLower = model.toLowerCase();
+    // OpenAI models that support JSON mode
+    if (providerLower === 'openai') {
+        const supportedModels = [
+            'gpt-4',
+            'gpt-4-turbo',
+            'gpt-4o',
+            'gpt-3.5-turbo'
+        ];
+        const isSupported = supportedModels.some(supported => modelLower.includes(supported));
+        // Check for specific version requirements
+        if (modelLower.includes('gpt-3.5-turbo')) {
+            // Only 1106+ supports JSON mode
+            const versionMatch = model.match(/gpt-3\.5-turbo-(\d+)/);
+            if (versionMatch) {
+                const version = parseInt(versionMatch[1], 10);
+                if (version < 1106) {
+                    return { supported: false, notes: 'gpt-3.5-turbo versions before 1106 do not support JSON mode' };
+                }
+            }
+        }
+        return {
+            supported: isSupported,
+            notes: isSupported
+                ? 'OpenAI supports response_format: { type: "json_object" }'
+                : 'Model may not support JSON mode - gateway will attempt to extract JSON from response'
+        };
+    }
+    // Anthropic doesn't support response_format
+    if (providerLower === 'anthropic') {
+        return {
+            supported: false,
+            notes: 'Anthropic does not support response_format - gateway will attempt to extract JSON from response'
+        };
+    }
+    return {
+        supported: false,
+        notes: 'Unknown provider - check provider documentation for JSON mode support'
+    };
+}
+/**
+ * Creates a test AIRequest with minimal valid structure
+ */
+export function createTestAIRequest(overrides) {
+    return {
+        jobId: 'test-job-' + Date.now(),
+        agentId: 'test-agent',
+        instructions: 'Test instructions',
+        input: 'Test input',
+        config: {
+            model: 'gpt-4o',
+            provider: 'openai'
+        },
+        primaryObjectType: {
+            type: 'test-result',
+            whenToUse: 'For testing purposes',
+            schema: {
+                type: 'object',
+                properties: {
+                    result: { type: 'string' }
+                }
+            }
+        },
+        ...overrides
+    };
+}
+/**
+ * Creates test cases for validation
+ */
+export function createValidationTestCases() {
+    return [
+        {
+            name: 'Valid minimal request',
+            request: {
+                jobId: 'test',
+                agentId: 'agent-1',
+                instructions: 'Test',
+                prompt: 'test.prompt',
+                workingMemory: { input: 'Test' }
+            },
+            shouldFail: false,
+            expectedErrors: []
+        },
+        {
+            name: 'Valid request with config',
+            request: {
+                jobId: 'test',
+                agentId: 'agent-1',
+                instructions: 'Test',
+                prompt: 'test.prompt',
+                workingMemory: { input: 'Test' },
+                config: {
+                    model: 'gpt-4o',
+                    provider: 'openai'
+                }
+            },
+            shouldFail: false,
+            expectedErrors: []
+        },
+        {
+            name: 'Missing jobId',
+            request: {
+                agentId: 'agent-1',
+                instructions: 'Test',
+                prompt: 'test.prompt',
+                workingMemory: { input: 'Test' }
+            },
+            shouldFail: true,
+            expectedErrors: ['jobId is required']
+        },
+        {
+            name: 'Missing agentId',
+            request: {
+                jobId: 'test',
+                instructions: 'Test',
+                prompt: 'test.prompt',
+                workingMemory: { input: 'Test' }
+            },
+            shouldFail: true,
+            expectedErrors: ['agentId is required']
+        },
+        {
+            name: 'Missing instructions',
+            request: {
+                jobId: 'test',
+                agentId: 'agent-1',
+                prompt: 'test.prompt',
+                workingMemory: { input: 'Test' }
+            },
+            shouldFail: true,
+            expectedErrors: ['instructions is required']
+        },
+        {
+            name: 'Missing prompt',
+            request: {
+                jobId: 'test',
+                agentId: 'agent-1',
+                instructions: 'Test'
+            },
+            shouldFail: true,
+            expectedErrors: ['input is required']
+        }
+    ];
+}
+/**
+ * Runs all validation tests and returns results
+ */
+export function runValidationTests() {
+    const testCases = createValidationTestCases();
+    const results = testCases.map(testCase => {
+        const validation = validateAIRequest(testCase.request);
+        const passed = testCase.shouldFail
+            ? !validation.valid
+            : validation.valid;
+        return {
+            name: testCase.name,
+            passed,
+            errors: validation.errors,
+            warnings: validation.warnings
+        };
+    });
+    return results;
+}
+/**
+ * Formats diagnostic information for display
+ */
+export function formatDiagnostic(diagnostic) {
+    const lines = [];
+    lines.push('=== Request Diagnostics ===');
+    lines.push(`Job ID: ${diagnostic.request.hasJobId ? '✓' : '✗'}`);
+    lines.push(`Agent ID: ${diagnostic.request.hasAgentId ? '✓' : '✗'}`);
+    lines.push(`Instructions: ${diagnostic.request.hasInstructions ? '✓' : '⚠ (optional)'}`);
+    lines.push(`Input (via workingMemory): ${diagnostic.request.hasWorkingMemory ? '✓' : '✗'}`);
+    lines.push(`Prompt: ${diagnostic.request.hasPrompt ? '✓' : '✗ (required)'}`);
+    lines.push(`Config: ${diagnostic.request.hasConfig ? '✓' : '✗'}`);
+    lines.push(`Model: ${diagnostic.request.hasModel ? '✓' : '✗'}`);
+    lines.push(`Provider: ${diagnostic.request.hasProvider ? '✓' : '⚠ (optional)'}`);
+    if (diagnostic.response) {
+        lines.push('\n=== Response Diagnostics ===');
+        lines.push(`Has Content: ${diagnostic.response.hasContent ? '✓' : '✗'}`);
+        lines.push(`Is JSON: ${diagnostic.response.isJSON ? '✓' : '✗'}`);
+        lines.push(`Has Parsed Content: ${diagnostic.response.hasParsedContent ? '✓' : '⚠'}`);
+        lines.push(`Content Type: ${diagnostic.response.contentType}`);
+        if (diagnostic.response.validationPassed !== undefined) {
+            lines.push(`Schema Validation: ${diagnostic.response.validationPassed ? '✓' : '✗'}`);
+            if (diagnostic.response.validationErrors && diagnostic.response.validationErrors.length > 0) {
+                lines.push(`Validation Errors: ${diagnostic.response.validationErrors.join(', ')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Quick validation helper - throws if invalid
+ */
+export function assertValidAIRequest(request) {
+    const validation = validateAIRequest(request);
+    if (!validation.valid) {
+        throw new Error(`AIRequest validation failed:\n${validation.errors.join('\n')}`);
+    }
+    if (validation.warnings.length > 0) {
+        console.warn('AIRequest validation warnings:', validation.warnings);
+    }
+}