@x12i/ai-gateway 7.9.1

package/dist/request-report-generator.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Request Report Generator
+ *
+ * Generates comprehensive request reports with validation, examples, and structured text information
+ */
+import type { AIRequest } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+export interface RequestReport {
+    requestId: string;
+    timestamp: number;
+    validation: {
+        instructions?: string;
+        rules?: any[];
+        automatedCode?: string;
+        checklist?: string[];
+    };
+    examples: {
+        count: number;
+        normal?: number;
+        edge?: number;
+        error?: number;
+        samples?: Array<{
+            input: string;
+            output: string;
+            metadata?: Record<string, unknown>;
+        }>;
+    };
+    structuredText: {
+        available: boolean;
+        instructions?: string;
+        template?: string;
+        guidelines?: string[];
+    };
+    schema: {
+        format: 'simple-format' | 'json-schema';
+        fields: Array<{
+            name: string;
+            type: string;
+            required: boolean;
+            description?: string;
+        }>;
+    };
+    metadata?: {
+        category?: string;
+        tags?: string[];
+        version?: string;
+    };
+    integrationHints: {
+        useStandardType: boolean;
+        recommendedType?: string;
+        validationAvailable: boolean;
+        structuredTextAvailable: boolean;
+        examplesAvailable: boolean;
+    };
+}
+/**
+ * Generate comprehensive request report
+ */
+export declare function generateRequestReport(request: AIRequest, library: any, // ObjectTypesLibrary removed
+logger: Logxer): Promise<RequestReport>;

package/dist/request-report-generator.js

@@ -0,0 +1,169 @@
+/**
+ * Request Report Generator
+ *
+ * Generates comprehensive request reports with validation, examples, and structured text information
+ */
+/**
+ * Extract validation rules from markdown
+ */
+function extractValidationRules(markdown) {
+    if (!markdown)
+        return [];
+    const rules = [];
+    // Look for validation rules sections
+    const rulesMatch = markdown.match(/## Validation Rules?\n([\s\S]*?)(?=\n##|$)/i);
+    if (rulesMatch) {
+        const rulesText = rulesMatch[1];
+        // Extract list items
+        const ruleItems = rulesText.match(/[-*]\s+(.+)/g);
+        if (ruleItems) {
+            ruleItems.forEach(item => {
+                rules.push({ rule: item.replace(/[-*]\s+/, '').trim() });
+            });
+        }
+    }
+    return rules;
+}
+/**
+ * Extract validation code from markdown
+ */
+function extractValidationCode(markdown) {
+    if (!markdown)
+        return undefined;
+    // Look for TypeScript code blocks
+    const codeBlockMatch = markdown.match(/```typescript\n([\s\S]*?)\n```/);
+    if (codeBlockMatch) {
+        return codeBlockMatch[1];
+    }
+    // Also try JavaScript
+    const jsCodeBlockMatch = markdown.match(/```javascript\n([\s\S]*?)\n```/);
+    if (jsCodeBlockMatch) {
+        return jsCodeBlockMatch[1];
+    }
+    return undefined;
+}
+/**
+ * Extract checklist items from markdown
+ */
+function extractChecklist(markdown) {
+    if (!markdown)
+        return [];
+    const checklist = [];
+    // Look for checklist section
+    const checklistMatch = markdown.match(/## Manual Review Checklist\n([\s\S]*?)(?=\n##|$)/i);
+    if (checklistMatch) {
+        const checklistText = checklistMatch[1];
+        // Extract checklist items (both checked and unchecked)
+        const items = checklistText.match(/- \[[ x]\] (.+)/g);
+        if (items) {
+            items.forEach(item => {
+                checklist.push(item.replace(/- \[[ x]\] /, '').trim());
+            });
+        }
+    }
+    return checklist;
+}
+/**
+ * Extract schema fields from simple format schema
+ */
+function extractSchemaFields(schema) {
+    const fields = [];
+    for (const [key, value] of Object.entries(schema)) {
+        if (typeof value === 'string') {
+            // Simple format: "field: '<type> Description'"
+            const match = value.match(/^<(\w+)>(.*)$/);
+            if (match) {
+                fields.push({
+                    name: key,
+                    type: match[1],
+                    required: true, // Assume required unless marked optional
+                    description: match[2].trim() || undefined
+                });
+            }
+            else if (Array.isArray(value)) {
+                // Array field: "field: ['<type> Description']"
+                fields.push({
+                    name: key,
+                    type: 'array',
+                    required: true,
+                    description: 'Array field'
+                });
+            }
+            else if (typeof value === 'object' && value !== null) {
+                // Nested object
+                fields.push({
+                    name: key,
+                    type: 'object',
+                    required: true,
+                    description: 'Nested object'
+                });
+            }
+        }
+        else if (typeof value === 'object' && value !== null) {
+            // JSON Schema format
+            if (Array.isArray(value)) {
+                fields.push({
+                    name: key,
+                    type: 'array',
+                    required: true
+                });
+            }
+            else {
+                fields.push({
+                    name: key,
+                    type: 'object',
+                    required: true
+                });
+            }
+        }
+    }
+    return fields;
+}
+/**
+ * Find matching standard type for custom schema
+ */
+async function findMatchingStandardType(schema, library // ObjectTypesLibrary removed
+) {
+    // Since ObjectTypesLibrary is removed, we can't match against standard types
+    // Return null to indicate no matching standard type found
+    return null;
+}
+/**
+ * Compare two schemas for structural similarity
+ */
+function schemasMatch(schema1, schema2) {
+    // Simple structure comparison - compare field names
+    const keys1 = Object.keys(schema1).sort();
+    const keys2 = Object.keys(schema2).sort();
+    // Must have same number of fields
+    if (keys1.length !== keys2.length) {
+        return false;
+    }
+    // All field names must match
+    return JSON.stringify(keys1) === JSON.stringify(keys2);
+}
+/**
+ * Generate comprehensive request report
+ */
+export async function generateRequestReport(request, library, // ObjectTypesLibrary removed
+logger) {
+    const report = {
+        requestId: request.jobId || `req-${Date.now()}`,
+        timestamp: Date.now(),
+        validation: {},
+        examples: { count: 0 },
+        structuredText: { available: false },
+        schema: {
+            format: 'simple-format',
+            fields: []
+        },
+        integrationHints: {
+            useStandardType: false,
+            validationAvailable: false,
+            structuredTextAvailable: false,
+            examplesAvailable: false
+        }
+    };
+    // Always use flex-md parsing - no object type processing needed
+    return report;
+}

package/dist/response-analyzer/format-type-detector.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Format Type Detector
+ *
+ * Detects text format types by analyzing text characteristics:
+ * - Sentence length and count
+ * - Paragraph count
+ * - Bullet points / numbered lists
+ * - Technical terms
+ * - Word/character count
+ * - Structure patterns
+ */
+export interface DetectedFormatType {
+    formatType: string;
+    confidence: number;
+}
+/**
+ * Detects format type of text content
+ */
+export declare class FormatTypeDetector {
+    /**
+     * Detects format type from text
+     *
+     * @param text - Text content to analyze
+     * @returns Detected format type with confidence
+     */
+    detect(text: string): DetectedFormatType | null;
+    /**
+     * Analyzes text characteristics
+     */
+    private analyzeCharacteristics;
+    /**
+     * Applies heuristics to determine format type
+     */
+    private applyHeuristics;
+}

package/dist/response-analyzer/format-type-detector.js

@@ -0,0 +1,115 @@
+/**
+ * Format Type Detector
+ *
+ * Detects text format types by analyzing text characteristics:
+ * - Sentence length and count
+ * - Paragraph count
+ * - Bullet points / numbered lists
+ * - Technical terms
+ * - Word/character count
+ * - Structure patterns
+ */
+/**
+ * Detects format type of text content
+ */
+export class FormatTypeDetector {
+    /**
+     * Detects format type from text
+     *
+     * @param text - Text content to analyze
+     * @returns Detected format type with confidence
+     */
+    detect(text) {
+        if (!text || typeof text !== 'string' || text.trim().length === 0) {
+            return null;
+        }
+        const trimmed = text.trim();
+        const characteristics = this.analyzeCharacteristics(trimmed);
+        // Apply heuristics to determine format type
+        return this.applyHeuristics(characteristics);
+    }
+    /**
+     * Analyzes text characteristics
+     */
+    analyzeCharacteristics(text) {
+        const sentences = text.split(/[.!?]+/).filter(s => s.trim().length > 0);
+        const paragraphs = text.split(/\n\s*\n/).filter(p => p.trim().length > 0);
+        const words = text.split(/\s+/).filter(w => w.length > 0);
+        // Detect bullet points (•, -, *, etc.)
+        const bulletPattern = /^[\s]*[•\-\*\+]\s+/gm;
+        const bullets = text.match(bulletPattern) || [];
+        // Detect numbered lists (1., 2., etc.)
+        const numberedPattern = /^[\s]*\d+[\.\)]\s+/gm;
+        const numbered = text.match(numberedPattern) || [];
+        // Simple technical term detection (words with common technical suffixes/patterns)
+        const technicalPattern = /\b(api|sdk|json|xml|http|https|sql|regex|async|await|function|class|interface|type|config|param|return)\b/gi;
+        const hasTechnicalTerms = technicalPattern.test(text);
+        const totalSentenceLength = sentences.reduce((sum, s) => sum + s.length, 0);
+        const avgSentenceLength = sentences.length > 0 ? totalSentenceLength / sentences.length : 0;
+        return {
+            sentenceCount: sentences.length,
+            avgSentenceLength,
+            paragraphCount: paragraphs.length,
+            wordCount: words.length,
+            charCount: text.length,
+            hasBullets: bullets.length > 0,
+            hasNumbered: numbered.length > 0,
+            bulletCount: bullets.length,
+            numberedCount: numbered.length,
+            hasTechnicalTerms
+        };
+    }
+    /**
+     * Applies heuristics to determine format type
+     */
+    applyHeuristics(characteristics) {
+        const { sentenceCount, avgSentenceLength, paragraphCount, wordCount, hasBullets, hasNumbered, bulletCount, numberedCount, hasTechnicalTerms } = characteristics;
+        // Bulleted list format
+        if (hasBullets && bulletCount >= 2) {
+            return {
+                formatType: 'bulleted',
+                confidence: Math.min(0.9, 0.6 + (bulletCount * 0.05))
+            };
+        }
+        // Numbered list format
+        if (hasNumbered && numberedCount >= 2) {
+            return {
+                formatType: 'numbered',
+                confidence: Math.min(0.9, 0.6 + (numberedCount * 0.05))
+            };
+        }
+        // Concise format: short sentences, low word count, few paragraphs
+        if (avgSentenceLength < 50 && wordCount < 50 && paragraphCount <= 1) {
+            return {
+                formatType: 'concise',
+                confidence: 0.8
+            };
+        }
+        // Explanatory format: multiple paragraphs, longer sentences
+        if (paragraphCount >= 2 && avgSentenceLength > 80) {
+            return {
+                formatType: 'explanatory',
+                confidence: 0.75
+            };
+        }
+        // Technical format: technical terms + longer sentences
+        if (hasTechnicalTerms && avgSentenceLength > 60) {
+            return {
+                formatType: 'technical',
+                confidence: 0.7
+            };
+        }
+        // Narrative format: multiple sentences, moderate length
+        if (sentenceCount >= 3 && avgSentenceLength >= 40 && avgSentenceLength <= 100) {
+            return {
+                formatType: 'narrative',
+                confidence: 0.65
+            };
+        }
+        // Default: plain text
+        return {
+            formatType: 'plain',
+            confidence: 0.5
+        };
+    }
+}

package/dist/response-analyzer/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Response Analyzer Module
+ *
+ * Exports all public APIs for response analysis
+ */
+export { ResponseAnalyzer } from './response-analyzer.js';
+export { ObjectTypeDetector } from './object-type-detector.js';
+export { FormatTypeDetector } from './format-type-detector.js';
+export type { ObjectTypeDefinition, ResponseAnalyzerConfig, MatchedObjectType, DetectedFormatType, AnalysisResult } from './types.js';

package/dist/response-analyzer/index.js

@@ -0,0 +1,8 @@
+/**
+ * Response Analyzer Module
+ *
+ * Exports all public APIs for response analysis
+ */
+export { ResponseAnalyzer } from './response-analyzer.js';
+export { ObjectTypeDetector } from './object-type-detector.js';
+export { FormatTypeDetector } from './format-type-detector.js';

package/dist/response-analyzer/object-type-detector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Object Type Detector
+ *
+ * Matches objects against predefined type definitions based on properties.
+ * Uses a scoring algorithm to determine the best match.
+ */
+import type { ObjectTypeDefinition, MatchedObjectType } from './types.js';
+export interface ObjectTypeDetectorConfig {
+    objectTypeDefinitions: ObjectTypeDefinition[];
+    minConfidenceThreshold: number;
+}
+/**
+ * Detects object types by matching against definitions
+ */
+export declare class ObjectTypeDetector {
+    private definitions;
+    private minThreshold;
+    constructor(config: ObjectTypeDetectorConfig);
+    /**
+     * Detects object types in a parsed content object
+     *
+     * @param parsedContent - Parsed content (object, array, or null)
+     * @returns Array of matched types sorted by confidence
+     */
+    detect(parsedContent: any): MatchedObjectType[];
+    /**
+     * Calculates match confidence for an object against a type definition
+     *
+     * Algorithm:
+     * 1. Count required properties present
+     * 2. Count optional properties present
+     * 3. Calculate base confidence: (required + optional) / total
+     * 4. Boost if all required present: +0.2
+     * 5. Boost for optional properties: +0.1 * (optional/total)
+     * 6. Apply priority weight: confidence * (1 + (priority-1) * 0.1)
+     *
+     * @param obj - Object to match
+     * @param definition - Type definition to match against
+     * @returns Confidence score (0-1)
+     */
+    private calculateMatchConfidence;
+}

package/dist/response-analyzer/object-type-detector.js

@@ -0,0 +1,95 @@
+/**
+ * Object Type Detector
+ *
+ * Matches objects against predefined type definitions based on properties.
+ * Uses a scoring algorithm to determine the best match.
+ */
+/**
+ * Detects object types by matching against definitions
+ */
+export class ObjectTypeDetector {
+    definitions;
+    minThreshold;
+    constructor(config) {
+        this.definitions = config.objectTypeDefinitions;
+        this.minThreshold = config.minConfidenceThreshold;
+    }
+    /**
+     * Detects object types in a parsed content object
+     *
+     * @param parsedContent - Parsed content (object, array, or null)
+     * @returns Array of matched types sorted by confidence
+     */
+    detect(parsedContent) {
+        // Only process objects (not arrays or primitives)
+        if (!parsedContent || typeof parsedContent !== 'object' || Array.isArray(parsedContent)) {
+            return [];
+        }
+        const matches = [];
+        for (const definition of this.definitions) {
+            const confidence = this.calculateMatchConfidence(parsedContent, definition);
+            if (confidence >= this.minThreshold) {
+                matches.push({
+                    type: definition,
+                    confidence
+                });
+            }
+        }
+        // Sort by confidence (desc), then priority (desc)
+        matches.sort((a, b) => {
+            if (a.confidence !== b.confidence) {
+                return b.confidence - a.confidence;
+            }
+            const priorityA = a.type.priority || 1;
+            const priorityB = b.type.priority || 1;
+            return priorityB - priorityA;
+        });
+        return matches;
+    }
+    /**
+     * Calculates match confidence for an object against a type definition
+     *
+     * Algorithm:
+     * 1. Count required properties present
+     * 2. Count optional properties present
+     * 3. Calculate base confidence: (required + optional) / total
+     * 4. Boost if all required present: +0.2
+     * 5. Boost for optional properties: +0.1 * (optional/total)
+     * 6. Apply priority weight: confidence * (1 + (priority-1) * 0.1)
+     *
+     * @param obj - Object to match
+     * @param definition - Type definition to match against
+     * @returns Confidence score (0-1)
+     */
+    calculateMatchConfidence(obj, definition) {
+        const required = definition.requiredProperties || [];
+        const optional = definition.optionalProperties || [];
+        const totalProperties = required.length + optional.length;
+        if (totalProperties === 0) {
+            return 0; // No properties to match
+        }
+        // Count required properties present
+        const requiredPresent = required.filter((prop) => obj.hasOwnProperty(prop) && obj[prop] != null).length;
+        // Count optional properties present
+        const optionalPresent = optional.filter((prop) => obj.hasOwnProperty(prop) && obj[prop] != null).length;
+        // Base confidence: proportion of properties found
+        let confidence = (requiredPresent + optionalPresent) / totalProperties;
+        // Boost if all required properties are present
+        if (requiredPresent === required.length && required.length > 0) {
+            confidence += 0.2;
+        }
+        // Boost for optional properties (bonus for having extras)
+        if (optional.length > 0) {
+            confidence += 0.1 * (optionalPresent / optional.length);
+        }
+        // Cap at 1.0
+        confidence = Math.min(confidence, 1.0);
+        // Apply priority weight
+        const priority = definition.priority || 1;
+        if (priority > 1) {
+            confidence = confidence * (1 + (priority - 1) * 0.1);
+            confidence = Math.min(confidence, 1.0); // Cap again
+        }
+        return confidence;
+    }
+}

package/dist/response-analyzer/response-analyzer.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Response Analyzer
+ *
+ * Main class that orchestrates object type and format type detection.
+ * Analyzes normalized responses and provides enhanced metadata.
+ */
+import type { ResponseAnalyzerConfig, AnalysisResult, ObjectTypeDefinition } from './types.js';
+/**
+ * Analyzes AI responses to detect object types and format types
+ */
+export declare class ResponseAnalyzer {
+    private objectDetector?;
+    private formatDetector;
+    private enableFormatDetection;
+    constructor(config?: ResponseAnalyzerConfig);
+    /**
+     * Analyzes a response and returns enhanced metadata
+     *
+     * @param rawText - Raw text content from response
+     * @param parsedContent - Parsed content (object, array, or null)
+     * @returns Analysis result with detected types
+     */
+    analyze(rawText?: string, parsedContent?: any): AnalysisResult;
+    /**
+     * Determines the content type of the response
+     *
+     * @param rawText - Raw text content
+     * @param parsedContent - Parsed content
+     * @returns Content type classification
+     */
+    private determineContentType;
+    /**
+     * Updates object type definitions
+     *
+     * @param definitions - New object type definitions
+     */
+    updateObjectTypeDefinitions(definitions: ObjectTypeDefinition[]): void;
+}

package/dist/response-analyzer/response-analyzer.js

@@ -0,0 +1,97 @@
+/**
+ * Response Analyzer
+ *
+ * Main class that orchestrates object type and format type detection.
+ * Analyzes normalized responses and provides enhanced metadata.
+ */
+import { ObjectTypeDetector } from './object-type-detector.js';
+import { FormatTypeDetector } from './format-type-detector.js';
+/**
+ * Analyzes AI responses to detect object types and format types
+ */
+export class ResponseAnalyzer {
+    objectDetector;
+    formatDetector;
+    enableFormatDetection;
+    constructor(config = {}) {
+        this.enableFormatDetection = config.enableFormatDetection !== false;
+        // Initialize object type detector if definitions provided
+        if (config.objectTypeDefinitions && config.objectTypeDefinitions.length > 0) {
+            this.objectDetector = new ObjectTypeDetector({
+                objectTypeDefinitions: config.objectTypeDefinitions,
+                minConfidenceThreshold: config.minConfidenceThreshold || 0.5
+            });
+        }
+        // Initialize format type detector
+        this.formatDetector = new FormatTypeDetector();
+    }
+    /**
+     * Analyzes a response and returns enhanced metadata
+     *
+     * @param rawText - Raw text content from response
+     * @param parsedContent - Parsed content (object, array, or null)
+     * @returns Analysis result with detected types
+     */
+    analyze(rawText, parsedContent) {
+        // Determine content type
+        const contentType = this.determineContentType(rawText, parsedContent);
+        const result = {
+            contentType
+        };
+        // Detect object types if content is an object
+        if (contentType === 'object' && this.objectDetector && parsedContent) {
+            const objectTypes = this.objectDetector.detect(parsedContent);
+            if (objectTypes.length > 0) {
+                result.bestObjectType = objectTypes[0];
+                result.allObjectTypes = objectTypes;
+            }
+        }
+        // Detect format type if content is text and format detection is enabled
+        if (contentType === 'text' && this.enableFormatDetection && rawText) {
+            const formatType = this.formatDetector.detect(rawText);
+            if (formatType) {
+                result.formatType = formatType;
+            }
+        }
+        return result;
+    }
+    /**
+     * Determines the content type of the response
+     *
+     * @param rawText - Raw text content
+     * @param parsedContent - Parsed content
+     * @returns Content type classification
+     */
+    determineContentType(rawText, parsedContent) {
+        // Empty if no content at all
+        if (!rawText && (parsedContent == null || parsedContent === '')) {
+            return 'empty';
+        }
+        // Object if parsed content is a non-array object
+        if (parsedContent != null && typeof parsedContent === 'object' && !Array.isArray(parsedContent)) {
+            return 'object';
+        }
+        // Text if we have raw text (or parsed content is a string/array)
+        if (rawText && rawText.trim().length > 0) {
+            return 'text';
+        }
+        // Default to empty
+        return 'empty';
+    }
+    /**
+     * Updates object type definitions
+     *
+     * @param definitions - New object type definitions
+     */
+    updateObjectTypeDefinitions(definitions) {
+        if (definitions.length > 0) {
+            this.objectDetector = new ObjectTypeDetector({
+                objectTypeDefinitions: definitions,
+                minConfidenceThreshold: 0.5
+            });
+        }
+        else {
+            this.objectDetector = undefined;
+        }
+    }
+}