ai.matey.utils 0.2.0

package/dist/esm/warnings.js

@@ -0,0 +1,284 @@
+/**
+ * Warning Utilities
+ *
+ * Helpers for creating, formatting, and managing semantic drift warnings.
+ *
+ * @module
+ */
+// ============================================================================
+// Warning Creation
+// ============================================================================
+/**
+ * Create a warning object.
+ *
+ * @param category Warning category
+ * @param message Human-readable message
+ * @param options Additional warning options
+ * @returns Warning object
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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
+ */
+export 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/esm/warnings.js.map

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

package/dist/types/conversation-history.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Conversation History Management Utilities
+ *
+ * Utilities for managing conversation history with configurable trimming strategies.
+ * Used by both middleware and wrappers for consistent history management.
+ *
+ * @module
+ */
+import type { IRMessage } from 'ai.matey.types';
+/**
+ * Strategy for trimming conversation history
+ */
+export type TrimStrategy = 'fifo' | 'smart';
+/**
+ * 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 declare function trimHistory(history: readonly IRMessage[], maxHistorySize: number, strategy?: TrimStrategy): IRMessage[];
+/**
+ * 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 declare function countMessagePairs(history: readonly IRMessage[]): number;
+/**
+ * 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 declare function shouldTrimHistory(history: readonly IRMessage[], maxHistorySize: number, strategy?: TrimStrategy): boolean;
+//# sourceMappingURL=conversation-history.d.ts.map

package/dist/types/conversation-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-history.d.ts","sourceRoot":"","sources":["../../src/conversation-history.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,YAAqB,GAC9B,SAAS,EAAE,CAsBb;AA2CD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,SAAS,EAAE,GAAG,MAAM,CAGvE;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,SAAS,SAAS,EAAE,EAC7B,cAAc,EAAE,MAAM,EACtB,QAAQ,GAAE,YAAqB,GAC9B,OAAO,CAiBT"}

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Utility Functions
+ *
+ * Collection of utility functions for validation, normalization, and streaming.
+ *
+ * @module
+ */
+export * from './validation.js';
+export * from './system-message.js';
+export * from './parameter-normalizer.js';
+export * from './streaming.js';
+export * from './streaming-modes.js';
+export * from './warnings.js';
+export * from './conversation-history.js';
+export * from './model-cache.js';
+export * from './structured-output.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,iBAAiB,CAAC;AAGhC,cAAc,qBAAqB,CAAC;AAGpC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,sBAAsB,CAAC;AAGrC,cAAc,eAAe,CAAC;AAG9B,cAAc,2BAA2B,CAAC;AAG1C,cAAc,kBAAkB,CAAC;AAGjC,cAAc,wBAAwB,CAAC"}

package/dist/types/model-cache.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Model Cache
+ *
+ * In-memory caching for model lists to reduce API calls.
+ * Supports both global (shared) and instance-scoped caches.
+ *
+ * @module
+ */
+import type { ListModelsResult } from 'ai.matey.types';
+/**
+ * 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 declare class ModelCache {
+    private cache;
+    constructor();
+    /**
+     * Get cached model list for a backend.
+     *
+     * @param backendName Unique backend identifier
+     * @returns Cached result or null if not found/expired
+     */
+    get(backendName: string): ListModelsResult | null;
+    /**
+     * 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: string, result: ListModelsResult, ttl: number): void;
+    /**
+     * Check if backend has cached models.
+     *
+     * @param backendName Unique backend identifier
+     * @returns true if cache exists and not expired
+     */
+    has(backendName: string): boolean;
+    /**
+     * Invalidate (remove) cached models for a backend.
+     *
+     * @param backendName Unique backend identifier
+     */
+    invalidate(backendName: string): void;
+    /**
+     * Clear all cached model lists.
+     */
+    clear(): void;
+    /**
+     * Get number of cached backends.
+     */
+    size(): number;
+    /**
+     * Get all cached backend names (excluding expired).
+     */
+    keys(): string[];
+}
+/**
+ * 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 declare const globalModelCache: ModelCache;
+/**
+ * Create or get model cache based on scope strategy.
+ *
+ * @param scope Cache scope strategy
+ * @returns Model cache instance
+ */
+export declare function getModelCache(scope?: 'global' | 'instance'): ModelCache;
+//# sourceMappingURL=model-cache.d.ts.map

package/dist/types/model-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-cache.d.ts","sourceRoot":"","sources":["../../src/model-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAyBvD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAA0B;;IAMvC;;;;;OAKG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAoBjD;;;;;;OAMG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IASrE;;;;;OAKG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;OAIG;IACH,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAIrC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,MAAM;IAiBd;;OAEG;IACH,IAAI,IAAI,MAAM,EAAE;CAejB;AAMD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,YAAmB,CAAC;AAMjD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,QAAQ,GAAG,UAAqB,GAAG,UAAU,CAOjF"}

package/dist/types/parameter-normalizer.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Parameter Normalization Utilities
+ *
+ * Normalizes parameters across different provider ranges and conventions.
+ * Enhanced with warning generation for semantic drift tracking.
+ *
+ * @module
+ */
+import type { IRParameters, IRCapabilities, IRWarning } from 'ai.matey.types';
+/**
+ * Normalize temperature to provider's range.
+ *
+ * IR uses 0-2 range (OpenAI convention).
+ * Some providers use 0-1 range (Anthropic).
+ *
+ * @param temperature Temperature value (0-2)
+ * @param targetRange Target range ('0-1' or '0-2')
+ * @returns Normalized temperature
+ */
+export declare function normalizeTemperature(temperature: number | undefined, targetRange?: '0-1' | '0-2'): number | undefined;
+/**
+ * Denormalize temperature from provider's range back to IR.
+ *
+ * @param temperature Temperature value from provider
+ * @param sourceRange Source range ('0-1' or '0-2')
+ * @returns IR temperature (0-2)
+ */
+export declare function denormalizeTemperature(temperature: number | undefined, sourceRange?: '0-1' | '0-2'): number | undefined;
+/**
+ * Normalize topP parameter.
+ *
+ * Always 0-1 range across providers.
+ *
+ * @param topP TopP value
+ * @returns Clamped topP
+ */
+export declare function normalizeTopP(topP: number | undefined): number | undefined;
+/**
+ * Normalize topK parameter.
+ *
+ * @param topK TopK value
+ * @param maxTopK Maximum topK supported by provider
+ * @returns Clamped topK
+ */
+export declare function normalizeTopK(topK: number | undefined, maxTopK?: number): number | undefined;
+/**
+ * Normalize penalty parameters (frequency, presence).
+ *
+ * IR uses -2 to 2 range (OpenAI convention).
+ * Some providers might use different ranges.
+ *
+ * @param penalty Penalty value
+ * @param targetRange Target range
+ * @returns Normalized penalty
+ */
+export declare function normalizePenalty(penalty: number | undefined, targetRange?: {
+    min: number;
+    max: number;
+}): number | undefined;
+/**
+ * Normalize stop sequences.
+ *
+ * @param stopSequences Stop sequences array
+ * @param maxStopSequences Maximum number of stop sequences supported
+ * @returns Normalized stop sequences
+ */
+export declare function normalizeStopSequences(stopSequences: readonly string[] | undefined, maxStopSequences?: number): string[] | undefined;
+/**
+ * Filter parameters based on provider capabilities.
+ *
+ * Removes parameters that the provider doesn't support.
+ *
+ * @param parameters IR parameters
+ * @param capabilities Provider capabilities
+ * @returns Filtered parameters
+ */
+export declare function filterUnsupportedParameters(parameters: IRParameters | undefined, capabilities: IRCapabilities): IRParameters;
+/**
+ * Apply parameter defaults.
+ *
+ * @param parameters IR parameters
+ * @param defaults Default values
+ * @returns Parameters with defaults applied
+ */
+export declare function applyParameterDefaults(parameters: IRParameters | undefined, defaults: Partial<IRParameters>): IRParameters;
+/**
+ * Merge parameter objects.
+ *
+ * Later parameters override earlier ones.
+ *
+ * @param parameterSets Parameter objects to merge
+ * @returns Merged parameters
+ */
+export declare function mergeParameters(...parameterSets: Array<IRParameters | undefined>): IRParameters;
+/**
+ * Clamp parameter to valid range.
+ *
+ * @param value Parameter value
+ * @param min Minimum value
+ * @param max Maximum value
+ * @returns Clamped value
+ */
+export declare function clampParameter(value: number | undefined, min: number, max: number): number | undefined;
+/**
+ * Sanitize parameters by clamping to valid ranges.
+ *
+ * @param parameters IR parameters
+ * @returns Sanitized parameters
+ */
+export declare function sanitizeParameters(parameters: IRParameters | undefined): IRParameters;
+/**
+ * Check if parameters are within valid ranges.
+ *
+ * @param parameters IR parameters
+ * @returns true if all parameters are valid
+ */
+export declare function areParametersValid(parameters: IRParameters | undefined): boolean;
+/**
+ * Result of parameter normalization with warnings.
+ */
+export interface NormalizationResult<T> {
+    /** Normalized value */
+    value: T;
+    /** Warnings generated during normalization */
+    warnings: IRWarning[];
+}
+/**
+ * Normalize temperature with warning generation.
+ *
+ * @param temperature Temperature value (0-2)
+ * @param targetRange Target range ('0-1' or '0-2')
+ * @param source Source adapter name
+ * @returns Normalized temperature and warnings
+ */
+export declare function normalizeTemperatureWithWarnings(temperature: number | undefined, targetRange?: '0-1' | '0-2', source?: string): NormalizationResult<number | undefined>;
+/**
+ * Normalize stop sequences with warning generation.
+ *
+ * @param stopSequences Stop sequences array
+ * @param maxStopSequences Maximum number supported
+ * @param source Source adapter name
+ * @returns Normalized stop sequences and warnings
+ */
+export declare function normalizeStopSequencesWithWarnings(stopSequences: readonly string[] | undefined, maxStopSequences: number | undefined, source?: string): NormalizationResult<string[] | undefined>;
+/**
+ * Filter parameters with warning generation.
+ *
+ * @param parameters IR parameters
+ * @param capabilities Provider capabilities
+ * @param source Source adapter name
+ * @returns Filtered parameters and warnings
+ */
+export declare function filterUnsupportedParametersWithWarnings(parameters: IRParameters | undefined, capabilities: IRCapabilities, source?: string): NormalizationResult<IRParameters>;
+//# sourceMappingURL=parameter-normalizer.d.ts.map

package/dist/types/parameter-normalizer.d.ts.map

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