ai.matey.utils 0.2.0

package/dist/cjs/warnings.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Warning Utilities
+ *
+ * Helpers for creating, formatting, and managing semantic drift warnings.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWarning = createWarning;
+exports.createNormalizationWarning = createNormalizationWarning;
+exports.createClampingWarning = createClampingWarning;
+exports.createUnsupportedParameterWarning = createUnsupportedParameterWarning;
+exports.createUnsupportedCapabilityWarning = createUnsupportedCapabilityWarning;
+exports.createTokenLimitWarning = createTokenLimitWarning;
+exports.createStopSequencesTruncatedWarning = createStopSequencesTruncatedWarning;
+exports.mergeWarnings = mergeWarnings;
+exports.filterWarningsBySeverity = filterWarningsBySeverity;
+exports.filterWarningsByCategory = filterWarningsByCategory;
+exports.groupWarningsByCategory = groupWarningsByCategory;
+exports.hasWarning = hasWarning;
+exports.formatWarning = formatWarning;
+exports.formatWarnings = formatWarnings;
+exports.getWarningSummary = getWarningSummary;
+// ============================================================================
+// Warning Creation
+// ============================================================================
+/**
+ * Create a warning object.
+ *
+ * @param category Warning category
+ * @param message Human-readable message
+ * @param options Additional warning options
+ * @returns Warning object
+ */
+function createWarning(category, message, options = {}) {
+    return {
+        category,
+        severity: options.severity ?? 'warning',
+        message,
+        field: options.field,
+        originalValue: options.originalValue,
+        transformedValue: options.transformedValue,
+        source: options.source,
+        details: options.details,
+    };
+}
+/**
+ * Create a parameter normalization warning.
+ *
+ * @param field Parameter field name
+ * @param originalValue Original value
+ * @param transformedValue Transformed value
+ * @param message Optional custom message
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createNormalizationWarning(field, originalValue, transformedValue, message, source) {
+    return createWarning('parameter-normalized', message ||
+        `Parameter '${field}' normalized from ${String(originalValue)} to ${String(transformedValue)}`, {
+        severity: 'info',
+        field,
+        originalValue,
+        transformedValue,
+        source,
+    });
+}
+/**
+ * Create a parameter clamping warning.
+ *
+ * @param field Parameter field name
+ * @param originalValue Original value
+ * @param clampedValue Clamped value
+ * @param min Minimum allowed value
+ * @param max Maximum allowed value
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createClampingWarning(field, originalValue, clampedValue, min, max, source) {
+    return createWarning('parameter-clamped', `Parameter '${field}' clamped from ${String(originalValue)} to ${String(clampedValue)} (valid range: ${min}-${max})`, {
+        severity: 'warning',
+        field,
+        originalValue,
+        transformedValue: clampedValue,
+        source,
+        details: { min, max },
+    });
+}
+/**
+ * Create an unsupported parameter warning.
+ *
+ * @param field Parameter field name
+ * @param value Parameter value
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createUnsupportedParameterWarning(field, value, source) {
+    return createWarning('parameter-unsupported', `Parameter '${field}' is not supported by provider (value: ${String(value)})`, {
+        severity: 'warning',
+        field,
+        originalValue: value,
+        source,
+    });
+}
+/**
+ * Create a capability unsupported warning.
+ *
+ * @param capability Capability name
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createUnsupportedCapabilityWarning(capability, source) {
+    return createWarning('capability-unsupported', `Capability '${capability}' is not supported by provider`, {
+        severity: 'warning',
+        field: capability,
+        source,
+    });
+}
+/**
+ * Create a token limit exceeded warning.
+ *
+ * @param estimatedTokens Estimated token count
+ * @param maxTokens Maximum tokens allowed
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createTokenLimitWarning(estimatedTokens, maxTokens, source) {
+    return createWarning('token-limit-exceeded', `Estimated tokens (${estimatedTokens}) may exceed provider limit (${maxTokens})`, {
+        severity: 'warning',
+        source,
+        details: { estimatedTokens, maxTokens },
+    });
+}
+/**
+ * Create a stop sequences truncated warning.
+ *
+ * @param originalCount Original number of stop sequences
+ * @param maxCount Maximum allowed
+ * @param source Source adapter
+ * @returns Warning object
+ */
+function createStopSequencesTruncatedWarning(originalCount, maxCount, source) {
+    return createWarning('stop-sequences-truncated', `Stop sequences truncated from ${originalCount} to ${maxCount} (provider limit)`, {
+        severity: 'warning',
+        field: 'stopSequences',
+        originalValue: originalCount,
+        transformedValue: maxCount,
+        source,
+    });
+}
+// ============================================================================
+// Warning Manipulation
+// ============================================================================
+/**
+ * Merge warning arrays, removing duplicates.
+ *
+ * @param warningArrays Arrays of warnings to merge
+ * @returns Merged and deduplicated warnings
+ */
+function mergeWarnings(...warningArrays) {
+    const warnings = [];
+    const seen = new Set();
+    for (const array of warningArrays) {
+        if (!array) {
+            continue;
+        }
+        for (const warning of array) {
+            // Create a key for deduplication
+            const key = `${warning.category}:${warning.field}:${warning.message}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                warnings.push(warning);
+            }
+        }
+    }
+    return warnings;
+}
+/**
+ * Filter warnings by severity.
+ *
+ * @param warnings Warnings to filter
+ * @param minSeverity Minimum severity level
+ * @returns Filtered warnings
+ */
+function filterWarningsBySeverity(warnings, minSeverity) {
+    const severityOrder = {
+        info: 0,
+        warning: 1,
+        error: 2,
+    };
+    const minLevel = severityOrder[minSeverity];
+    return warnings.filter((w) => severityOrder[w.severity] >= minLevel);
+}
+/**
+ * Filter warnings by category.
+ *
+ * @param warnings Warnings to filter
+ * @param categories Categories to include
+ * @returns Filtered warnings
+ */
+function filterWarningsByCategory(warnings, categories) {
+    const categorySet = new Set(categories);
+    return warnings.filter((w) => categorySet.has(w.category));
+}
+/**
+ * Group warnings by category.
+ *
+ * @param warnings Warnings to group
+ * @returns Map of category to warnings
+ */
+function groupWarningsByCategory(warnings) {
+    const groups = new Map();
+    for (const warning of warnings) {
+        const group = groups.get(warning.category) || [];
+        group.push(warning);
+        groups.set(warning.category, group);
+    }
+    return groups;
+}
+/**
+ * Check if warnings array contains a specific warning type.
+ *
+ * @param warnings Warnings to check
+ * @param category Warning category to look for
+ * @param field Optional field name to match
+ * @returns true if warning exists
+ */
+function hasWarning(warnings, category, field) {
+    if (!warnings) {
+        return false;
+    }
+    return warnings.some((w) => w.category === category && (field === undefined || w.field === field));
+}
+// ============================================================================
+// Warning Formatting
+// ============================================================================
+/**
+ * Format a single warning as a string.
+ *
+ * @param warning Warning to format
+ * @param includeDetails Include full details
+ * @returns Formatted warning string
+ */
+function formatWarning(warning, includeDetails = false) {
+    const prefix = `[${warning.severity.toUpperCase()}]`;
+    const source = warning.source ? ` (${warning.source})` : '';
+    if (!includeDetails) {
+        return `${prefix} ${warning.message}${source}`;
+    }
+    const parts = [
+        `${prefix} ${warning.message}${source}`,
+        warning.field ? `  Field: ${warning.field}` : null,
+        warning.originalValue !== undefined
+            ? `  Original: ${JSON.stringify(warning.originalValue)}`
+            : null,
+        warning.transformedValue !== undefined
+            ? `  Transformed: ${JSON.stringify(warning.transformedValue)}`
+            : null,
+        warning.details ? `  Details: ${JSON.stringify(warning.details)}` : null,
+    ].filter(Boolean);
+    return parts.join('\n');
+}
+/**
+ * Format multiple warnings as a string.
+ *
+ * @param warnings Warnings to format
+ * @param includeDetails Include full details
+ * @returns Formatted warnings string
+ */
+function formatWarnings(warnings, includeDetails = false) {
+    if (warnings.length === 0) {
+        return 'No warnings';
+    }
+    const formatted = warnings.map((w) => formatWarning(w, includeDetails));
+    return formatted.join('\n');
+}
+/**
+ * Get a summary of warnings by category.
+ *
+ * @param warnings Warnings to summarize
+ * @returns Summary object with counts
+ */
+function getWarningSummary(warnings) {
+    const summary = {
+        total: warnings.length,
+        byCategory: {},
+        bySeverity: {
+            info: 0,
+            warning: 0,
+            error: 0,
+        },
+    };
+    for (const warning of warnings) {
+        // Count by category
+        summary.byCategory[warning.category] = (summary.byCategory[warning.category] || 0) + 1;
+        // Count by severity
+        summary.bySeverity[warning.severity]++;
+    }
+    return summary;
+}
+//# sourceMappingURL=warnings.js.map

package/dist/cjs/warnings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warnings.js","sourceRoot":"","sources":["../../src/warnings.ts"],"names":[],"mappings":"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"}

package/dist/esm/conversation-history.js

@@ -0,0 +1,134 @@
+/**
+ * Conversation History Management Utilities
+ *
+ * Utilities for managing conversation history with configurable trimming strategies.
+ * Used by both middleware and wrappers for consistent history management.
+ *
+ * @module
+ */
+/**
+ * Trim conversation history to keep only the most recent messages.
+ *
+ * @param history - Current conversation history
+ * @param maxHistorySize - Maximum number of message pairs to keep
+ *                         - 0: Return empty array (no history)
+ *                         - -1: Return full history (no trimming)
+ *                         - N > 0: Keep last N user/assistant pairs
+ * @param strategy - Trimming strategy
+ *                   - 'fifo': First-in-first-out, remove oldest messages
+ *                   - 'smart': Preserve system messages, trim user/assistant pairs
+ * @returns Trimmed history
+ *
+ * @example
+ * ```typescript
+ * const history = [
+ *   { role: 'system', content: 'You are helpful' },
+ *   { role: 'user', content: 'Hi' },
+ *   { role: 'assistant', content: 'Hello!' },
+ *   { role: 'user', content: 'How are you?' },
+ *   { role: 'assistant', content: 'I am well!' },
+ * ];
+ *
+ * // Keep last 1 pair + system message
+ * const trimmed = trimHistory(history, 1, 'smart');
+ * // Result: system message + last user/assistant pair
+ * ```
+ */
+export function trimHistory(history, maxHistorySize, strategy = 'fifo') {
+    // No history
+    if (maxHistorySize === 0) {
+        return [];
+    }
+    // Unlimited history
+    if (maxHistorySize < 0) {
+        return Array.from(history);
+    }
+    // No trimming needed
+    if (history.length === 0) {
+        return [];
+    }
+    if (strategy === 'smart') {
+        return trimHistorySmart(history, maxHistorySize);
+    }
+    // FIFO strategy: keep last N pairs (2N messages)
+    return trimHistoryFifo(history, maxHistorySize);
+}
+/**
+ * FIFO trimming: Keep last N message pairs
+ */
+function trimHistoryFifo(history, maxPairs) {
+    const maxMessages = maxPairs * 2;
+    if (history.length <= maxMessages) {
+        return Array.from(history);
+    }
+    // Keep last 2N messages
+    return Array.from(history.slice(-maxMessages));
+}
+/**
+ * Smart trimming: Preserve system messages, trim user/assistant pairs
+ */
+function trimHistorySmart(history, maxPairs) {
+    // Separate system messages from conversation
+    const systemMessages = [];
+    const conversationMessages = [];
+    for (const message of history) {
+        if (message.role === 'system') {
+            systemMessages.push(message);
+        }
+        else {
+            conversationMessages.push(message);
+        }
+    }
+    // Trim conversation to last N pairs
+    const maxConversationMessages = maxPairs * 2;
+    const trimmedConversation = conversationMessages.length <= maxConversationMessages
+        ? conversationMessages
+        : conversationMessages.slice(-maxConversationMessages);
+    // Combine: system messages first, then conversation
+    return [...systemMessages, ...trimmedConversation];
+}
+/**
+ * Count message pairs in history (excluding system messages)
+ *
+ * @param history - Conversation history
+ * @returns Number of user/assistant pairs
+ *
+ * @example
+ * ```typescript
+ * const history = [
+ *   { role: 'system', content: 'You are helpful' },
+ *   { role: 'user', content: 'Hi' },
+ *   { role: 'assistant', content: 'Hello!' },
+ * ];
+ *
+ * countMessagePairs(history); // 1
+ * ```
+ */
+export function countMessagePairs(history) {
+    const nonSystemMessages = history.filter((m) => m.role !== 'system');
+    return Math.floor(nonSystemMessages.length / 2);
+}
+/**
+ * Check if history needs trimming
+ *
+ * @param history - Current history
+ * @param maxHistorySize - Maximum pairs to keep
+ * @param strategy - Trimming strategy
+ * @returns True if history exceeds limit
+ */
+export function shouldTrimHistory(history, maxHistorySize, strategy = 'fifo') {
+    if (maxHistorySize === 0) {
+        return history.length > 0;
+    }
+    if (maxHistorySize < 0) {
+        return false;
+    }
+    if (strategy === 'smart') {
+        const pairs = countMessagePairs(history);
+        return pairs > maxHistorySize;
+    }
+    // FIFO: check total message count
+    const maxMessages = maxHistorySize * 2;
+    return history.length > maxMessages;
+}
+//# sourceMappingURL=conversation-history.js.map

package/dist/esm/conversation-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-history.js","sourceRoot":"","sources":["../../src/conversation-history.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -0,0 +1,26 @@
+/**
+ * Utility Functions
+ *
+ * Collection of utility functions for validation, normalization, and streaming.
+ *
+ * @module
+ */
+// Validation utilities
+export * from './validation.js';
+// System message utilities
+export * from './system-message.js';
+// Parameter normalization utilities
+export * from './parameter-normalizer.js';
+// Streaming utilities
+export * from './streaming.js';
+// Streaming mode conversion utilities
+export * from './streaming-modes.js';
+// Warning utilities
+export * from './warnings.js';
+// Conversation history utilities
+export * from './conversation-history.js';
+// Model cache utilities
+export * from './model-cache.js';
+// Structured output utilities (Zod integration)
+export * from './structured-output.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,uBAAuB;AACvB,cAAc,iBAAiB,CAAC;AAEhC,2BAA2B;AAC3B,cAAc,qBAAqB,CAAC;AAEpC,oCAAoC;AACpC,cAAc,2BAA2B,CAAC;AAE1C,sBAAsB;AACtB,cAAc,gBAAgB,CAAC;AAE/B,sCAAsC;AACtC,cAAc,sBAAsB,CAAC;AAErC,oBAAoB;AACpB,cAAc,eAAe,CAAC;AAE9B,iCAAiC;AACjC,cAAc,2BAA2B,CAAC;AAE1C,wBAAwB;AACxB,cAAc,kBAAkB,CAAC;AAEjC,gDAAgD;AAChD,cAAc,wBAAwB,CAAC"}

package/dist/esm/model-cache.js

@@ -0,0 +1,158 @@
+/**
+ * Model Cache
+ *
+ * In-memory caching for model lists to reduce API calls.
+ * Supports both global (shared) and instance-scoped caches.
+ *
+ * @module
+ */
+// ============================================================================
+// Model Cache Implementation
+// ============================================================================
+/**
+ * In-memory cache for model lists with TTL-based expiration.
+ *
+ * Usage:
+ * ```typescript
+ * const cache = new ModelCache();
+ *
+ * // Set with 1 hour TTL
+ * cache.set('openai-backend', modelResult, 3600000);
+ *
+ * // Get (returns null if expired or not found)
+ * const cached = cache.get('openai-backend');
+ *
+ * // Invalidate specific backend
+ * cache.invalidate('openai-backend');
+ *
+ * // Clear all
+ * cache.clear();
+ * ```
+ */
+export class ModelCache {
+    cache;
+    constructor() {
+        this.cache = new Map();
+    }
+    /**
+     * Get cached model list for a backend.
+     *
+     * @param backendName Unique backend identifier
+     * @returns Cached result or null if not found/expired
+     */
+    get(backendName) {
+        const entry = this.cache.get(backendName);
+        if (!entry) {
+            return null;
+        }
+        // Check if expired
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(backendName);
+            return null;
+        }
+        // Return cached result with updated source
+        return {
+            ...entry.result,
+            source: 'cache',
+        };
+    }
+    /**
+     * Cache a model list result.
+     *
+     * @param backendName Unique backend identifier
+     * @param result Model list result to cache
+     * @param ttl Time to live in milliseconds
+     */
+    set(backendName, result, ttl) {
+        const expiresAt = Date.now() + ttl;
+        this.cache.set(backendName, {
+            result,
+            expiresAt,
+        });
+    }
+    /**
+     * Check if backend has cached models.
+     *
+     * @param backendName Unique backend identifier
+     * @returns true if cache exists and not expired
+     */
+    has(backendName) {
+        return this.get(backendName) !== null;
+    }
+    /**
+     * Invalidate (remove) cached models for a backend.
+     *
+     * @param backendName Unique backend identifier
+     */
+    invalidate(backendName) {
+        this.cache.delete(backendName);
+    }
+    /**
+     * Clear all cached model lists.
+     */
+    clear() {
+        this.cache.clear();
+    }
+    /**
+     * Get number of cached backends.
+     */
+    size() {
+        // Count only non-expired entries
+        let count = 0;
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now <= entry.expiresAt) {
+                count++;
+            }
+            else {
+                // Clean up expired entry
+                this.cache.delete(key);
+            }
+        }
+        return count;
+    }
+    /**
+     * Get all cached backend names (excluding expired).
+     */
+    keys() {
+        const keys = [];
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now <= entry.expiresAt) {
+                keys.push(key);
+            }
+            else {
+                // Clean up expired entry
+                this.cache.delete(key);
+            }
+        }
+        return keys;
+    }
+}
+// ============================================================================
+// Global Cache Instance
+// ============================================================================
+/**
+ * Global model cache shared across all adapter instances.
+ *
+ * This is the default cache used when `modelsCacheScope: 'global'`.
+ * Reduces redundant API calls when multiple adapters share the same backend.
+ */
+export const globalModelCache = new ModelCache();
+// ============================================================================
+// Cache Factory
+// ============================================================================
+/**
+ * Create or get model cache based on scope strategy.
+ *
+ * @param scope Cache scope strategy
+ * @returns Model cache instance
+ */
+export function getModelCache(scope = 'global') {
+    if (scope === 'global') {
+        return globalModelCache;
+    }
+    // Create new instance-scoped cache
+    return new ModelCache();
+}
+//# sourceMappingURL=model-cache.js.map

package/dist/esm/model-cache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cache.js","sourceRoot":"","sources":["../../src/model-cache.ts"],"names":[],"mappings":"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"}