ai.matey.utils 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AI Matey Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cjs/conversation-history.js

@@ -0,0 +1,139 @@
+"use strict";
+/**
+ * Conversation History Management Utilities
+ *
+ * Utilities for managing conversation history with configurable trimming strategies.
+ * Used by both middleware and wrappers for consistent history management.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimHistory = trimHistory;
+exports.countMessagePairs = countMessagePairs;
+exports.shouldTrimHistory = shouldTrimHistory;
+/**
+ * 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
+ * ```
+ */
+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
+ * ```
+ */
+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
+ */
+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/cjs/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/cjs/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Utility Functions
+ *
+ * Collection of utility functions for validation, normalization, and streaming.
+ *
+ * @module
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Validation utilities
+__exportStar(require("./validation.js"), exports);
+// System message utilities
+__exportStar(require("./system-message.js"), exports);
+// Parameter normalization utilities
+__exportStar(require("./parameter-normalizer.js"), exports);
+// Streaming utilities
+__exportStar(require("./streaming.js"), exports);
+// Streaming mode conversion utilities
+__exportStar(require("./streaming-modes.js"), exports);
+// Warning utilities
+__exportStar(require("./warnings.js"), exports);
+// Conversation history utilities
+__exportStar(require("./conversation-history.js"), exports);
+// Model cache utilities
+__exportStar(require("./model-cache.js"), exports);
+// Structured output utilities (Zod integration)
+__exportStar(require("./structured-output.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;;;;;;;;;;;;;;AAEH,uBAAuB;AACvB,kDAAgC;AAEhC,2BAA2B;AAC3B,sDAAoC;AAEpC,oCAAoC;AACpC,4DAA0C;AAE1C,sBAAsB;AACtB,iDAA+B;AAE/B,sCAAsC;AACtC,uDAAqC;AAErC,oBAAoB;AACpB,gDAA8B;AAE9B,iCAAiC;AACjC,4DAA0C;AAE1C,wBAAwB;AACxB,mDAAiC;AAEjC,gDAAgD;AAChD,yDAAuC"}

package/dist/cjs/model-cache.js

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Model Cache
+ *
+ * In-memory caching for model lists to reduce API calls.
+ * Supports both global (shared) and instance-scoped caches.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.globalModelCache = exports.ModelCache = void 0;
+exports.getModelCache = getModelCache;
+// ============================================================================
+// 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();
+ * ```
+ */
+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;
+    }
+}
+exports.ModelCache = ModelCache;
+// ============================================================================
+// 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.
+ */
+exports.globalModelCache = new ModelCache();
+// ============================================================================
+// Cache Factory
+// ============================================================================
+/**
+ * Create or get model cache based on scope strategy.
+ *
+ * @param scope Cache scope strategy
+ * @returns Model cache instance
+ */
+function getModelCache(scope = 'global') {
+    if (scope === 'global') {
+        return exports.globalModelCache;
+    }
+    // Create new instance-scoped cache
+    return new ModelCache();
+}
+//# sourceMappingURL=model-cache.js.map

package/dist/cjs/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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"}