ai.matey.types 0.2.0

package/dist/types/router.d.ts

@@ -0,0 +1,526 @@
+/**
+ * Router Types and Interfaces
+ *
+ * The Router manages multiple backend adapters and provides intelligent routing,
+ * fallback strategies, and parallel dispatch capabilities.
+ *
+ * @module
+ */
+import type { BackendAdapter, AdapterMetadata } from './adapters.js';
+import type { IRChatRequest, IRChatResponse, IRChatStream } from './ir.js';
+import type { AdapterError } from './errors.js';
+import type { ModelTranslationConfig, ModelMapping } from './model-translation.js';
+export type { ModelMapping };
+/**
+ * Fallback strategies for handling backend failures.
+ */
+export declare const FallbackStrategy: {
+    /**
+     * No fallback - fail immediately if primary backend fails.
+     */
+    readonly NONE: "none";
+    /**
+     * Try backends sequentially in order until one succeeds.
+     */
+    readonly SEQUENTIAL: "sequential";
+    /**
+     * Try all backends in parallel, return first success.
+     */
+    readonly PARALLEL: "parallel";
+    /**
+     * Use custom fallback logic.
+     */
+    readonly CUSTOM: "custom";
+};
+export type FallbackStrategy = (typeof FallbackStrategy)[keyof typeof FallbackStrategy];
+/**
+ * Routing strategies for selecting backends.
+ */
+export declare const RoutingStrategy: {
+    /**
+     * Use backend specified in request options.
+     */
+    readonly EXPLICIT: "explicit";
+    /**
+     * Route based on model name.
+     */
+    readonly MODEL_BASED: "model-based";
+    /**
+     * Route to least-cost backend.
+     */
+    readonly COST_OPTIMIZED: "cost-optimized";
+    /**
+     * Route to fastest backend (lowest latency).
+     */
+    readonly LATENCY_OPTIMIZED: "latency-optimized";
+    /**
+     * Round-robin load balancing.
+     */
+    readonly ROUND_ROBIN: "round-robin";
+    /**
+     * Random backend selection.
+     */
+    readonly RANDOM: "random";
+    /**
+     * Use custom routing logic.
+     */
+    readonly CUSTOM: "custom";
+};
+export type RoutingStrategy = (typeof RoutingStrategy)[keyof typeof RoutingStrategy];
+/**
+ * Router configuration options.
+ */
+export interface RouterConfig {
+    /**
+     * Primary routing strategy.
+     * @default 'explicit'
+     */
+    readonly routingStrategy?: RoutingStrategy;
+    /**
+     * Fallback strategy when primary backend fails.
+     * @default 'sequential'
+     */
+    readonly fallbackStrategy?: FallbackStrategy;
+    /**
+     * Default backend to use if routing doesn't select one.
+     */
+    readonly defaultBackend?: string;
+    /**
+     * Interval for health checking backends (milliseconds).
+     * Set to 0 to disable health checks.
+     * @default 0
+     */
+    readonly healthCheckInterval?: number;
+    /**
+     * Enable circuit breaker pattern.
+     * @default false
+     */
+    readonly enableCircuitBreaker?: boolean;
+    /**
+     * Number of consecutive failures before circuit breaker opens.
+     * @default 5
+     */
+    readonly circuitBreakerThreshold?: number;
+    /**
+     * Time to wait before attempting to close circuit breaker (milliseconds).
+     * @default 60000
+     */
+    readonly circuitBreakerTimeout?: number;
+    /**
+     * Track latency statistics per backend.
+     * @default true
+     */
+    readonly trackLatency?: boolean;
+    /**
+     * Track cost per backend (requires backends to implement estimateCost).
+     * @default false
+     */
+    readonly trackCost?: boolean;
+    /**
+     * Enable capability-based routing.
+     * When enabled, the router will select backends based on their model capabilities
+     * matching the request requirements.
+     * @default false
+     */
+    readonly capabilityBasedRouting?: boolean;
+    /**
+     * Optimization strategy for capability-based routing.
+     * Determines how to weigh cost, speed, and quality when selecting models.
+     * @default 'balanced'
+     */
+    readonly optimization?: 'cost' | 'speed' | 'quality' | 'balanced';
+    /**
+     * Custom optimization weights for capability-based routing.
+     * Must sum to 1.0. Overrides optimization preset.
+     */
+    readonly optimizationWeights?: {
+        cost: number;
+        speed: number;
+        quality: number;
+    };
+    /**
+     * Cache duration for model capability data in milliseconds.
+     * @default 3600000 (1 hour)
+     */
+    readonly capabilityCacheDuration?: number;
+    /**
+     * Custom routing function.
+     */
+    readonly customRouter?: CustomRoutingFunction;
+    /**
+     * Custom fallback function.
+     */
+    readonly customFallback?: CustomFallbackFunction;
+    /**
+     * Model translation configuration for fallback scenarios.
+     * Controls how model names are translated when falling back to different backends.
+     * @default { strategy: 'hybrid', warnOnDefault: true, strictMode: false }
+     */
+    readonly modelTranslation?: ModelTranslationConfig;
+}
+/**
+ * Custom routing function signature.
+ */
+export type CustomRoutingFunction = (request: IRChatRequest, availableBackends: readonly string[], context: RoutingContext) => Promise<string | null>;
+/**
+ * Custom fallback function signature.
+ */
+export type CustomFallbackFunction = (request: IRChatRequest, failedBackend: string, error: AdapterError, attemptedBackends: readonly string[], availableBackends: readonly string[]) => Promise<string | null>;
+/**
+ * Context provided to routing functions.
+ */
+export interface RoutingContext {
+    /**
+     * Backend statistics for making informed decisions.
+     */
+    readonly stats: RouterStats;
+    /**
+     * Request metadata.
+     */
+    readonly metadata: Record<string, unknown>;
+    /**
+     * Preferred backend from request options (if any).
+     */
+    readonly preferredBackend?: string;
+}
+/**
+ * Information about a registered backend.
+ */
+export interface BackendInfo {
+    /**
+     * Backend identifier.
+     */
+    readonly name: string;
+    /**
+     * Backend adapter instance.
+     */
+    readonly adapter: BackendAdapter;
+    /**
+     * Backend metadata.
+     */
+    readonly metadata: AdapterMetadata;
+    /**
+     * Whether backend is currently healthy.
+     */
+    readonly isHealthy: boolean;
+    /**
+     * Last health check timestamp.
+     */
+    readonly lastHealthCheck?: number;
+    /**
+     * Circuit breaker state.
+     */
+    readonly circuitBreakerState: 'closed' | 'open' | 'half-open';
+    /**
+     * Consecutive failures count (for circuit breaker).
+     */
+    readonly consecutiveFailures: number;
+    /**
+     * Statistics for this backend.
+     */
+    readonly stats: BackendStats;
+}
+/**
+ * Statistics for a single backend.
+ */
+export interface BackendStats {
+    /**
+     * Total requests routed to this backend.
+     */
+    readonly totalRequests: number;
+    /**
+     * Successful requests.
+     */
+    readonly successfulRequests: number;
+    /**
+     * Failed requests.
+     */
+    readonly failedRequests: number;
+    /**
+     * Success rate (0-100).
+     */
+    readonly successRate: number;
+    /**
+     * Average latency in milliseconds.
+     */
+    readonly averageLatencyMs: number;
+    /**
+     * P50 latency in milliseconds.
+     */
+    readonly p50LatencyMs: number;
+    /**
+     * P95 latency in milliseconds.
+     */
+    readonly p95LatencyMs: number;
+    /**
+     * P99 latency in milliseconds.
+     */
+    readonly p99LatencyMs: number;
+    /**
+     * Total estimated cost (if tracking enabled).
+     */
+    readonly totalCost?: number;
+    /**
+     * Average cost per request (if tracking enabled).
+     */
+    readonly averageCost?: number;
+}
+/**
+ * Overall router statistics.
+ */
+export interface RouterStats {
+    /**
+     * Total requests routed.
+     */
+    readonly totalRequests: number;
+    /**
+     * Requests that succeeded on first try.
+     */
+    readonly successfulRequests: number;
+    /**
+     * Requests that failed completely.
+     */
+    readonly failedRequests: number;
+    /**
+     * Requests that required fallback.
+     */
+    readonly totalFallbacks: number;
+    /**
+     * Parallel/fan-out requests.
+     */
+    readonly parallelRequests: number;
+    /**
+     * Per-backend statistics.
+     */
+    readonly backendStats: Record<string, BackendStats>;
+    /**
+     * When statistics were last reset.
+     */
+    readonly sinceTimestamp: number;
+}
+/**
+ * Strategy for handling parallel dispatch results.
+ */
+export declare const ParallelStrategy: {
+    /**
+     * Return first successful response, cancel others.
+     */
+    readonly FIRST: "first";
+    /**
+     * Wait for all responses, return array of results.
+     */
+    readonly ALL: "all";
+    /**
+     * Return fastest successful response (with timeout).
+     */
+    readonly FASTEST: "fastest";
+    /**
+     * Use custom aggregation logic.
+     */
+    readonly CUSTOM: "custom";
+};
+export type ParallelStrategy = (typeof ParallelStrategy)[keyof typeof ParallelStrategy];
+/**
+ * Options for parallel dispatch.
+ */
+export interface ParallelDispatchOptions {
+    /**
+     * Backend names to dispatch to.
+     */
+    readonly backends?: readonly string[];
+    /**
+     * Parallel dispatch strategy.
+     * @default 'first'
+     */
+    readonly strategy?: ParallelStrategy;
+    /**
+     * Timeout for parallel requests (milliseconds).
+     */
+    readonly timeout?: number;
+    /**
+     * Cancel remaining requests on first success.
+     * @default true
+     */
+    readonly cancelOnFirstSuccess?: boolean;
+    /**
+     * Custom aggregation function for 'custom' strategy.
+     */
+    readonly customAggregator?: (responses: Array<{
+        backend: string;
+        response: IRChatResponse;
+        latencyMs: number;
+    }>) => IRChatResponse;
+}
+/**
+ * Result of parallel dispatch.
+ */
+export interface ParallelDispatchResult {
+    /**
+     * Primary response (based on strategy).
+     */
+    readonly response: IRChatResponse;
+    /**
+     * All responses (only for 'all' strategy).
+     */
+    readonly allResponses?: Array<{
+        readonly backend: string;
+        readonly response: IRChatResponse;
+        readonly latencyMs: number;
+    }>;
+    /**
+     * Backends that succeeded.
+     */
+    readonly successfulBackends: readonly string[];
+    /**
+     * Backends that failed.
+     */
+    readonly failedBackends: Array<{
+        readonly backend: string;
+        readonly error: AdapterError;
+    }>;
+    /**
+     * Total time for parallel dispatch (milliseconds).
+     */
+    readonly totalTimeMs: number;
+}
+/**
+ * Model pattern to backend mapping.
+ */
+export interface ModelPatternMapping {
+    /**
+     * Regular expression pattern to match model names.
+     */
+    readonly pattern: RegExp;
+    /**
+     * Backend name to route matching models to.
+     */
+    readonly backend: string;
+    /**
+     * Optional target model name to use (for translation during fallback).
+     * If not specified, original model name is passed through.
+     */
+    readonly targetModel?: string;
+    /**
+     * Pattern matching priority (higher = checked first).
+     * @default 0
+     */
+    readonly priority?: number;
+}
+/**
+ * Router manages multiple backend adapters with intelligent routing.
+ */
+export interface Router extends BackendAdapter<unknown, unknown> {
+    /**
+     * Router configuration.
+     */
+    readonly config: RouterConfig;
+    /**
+     * Register a backend adapter.
+     */
+    register(name: string, adapter: BackendAdapter): Router;
+    /**
+     * Unregister a backend adapter.
+     */
+    unregister(name: string): Router;
+    /**
+     * Get a registered backend adapter.
+     */
+    get(name: string): BackendAdapter | undefined;
+    /**
+     * Check if backend is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered backend names.
+     */
+    listBackends(): readonly string[];
+    /**
+     * Get information about all registered backends.
+     */
+    getBackendInfo(): BackendInfo[];
+    /**
+     * Get information about specific backend.
+     */
+    getBackendInfo(name: string): BackendInfo | undefined;
+    /**
+     * Set fallback chain for sequential failover.
+     */
+    setFallbackChain(chain: readonly string[]): Router;
+    /**
+     * Get current fallback chain.
+     */
+    getFallbackChain(): readonly string[];
+    /**
+     * Set model to backend mapping.
+     */
+    setModelMapping(mapping: ModelMapping): Router;
+    /**
+     * Get current model mapping.
+     */
+    getModelMapping(): ModelMapping;
+    /**
+     * Set model pattern mappings.
+     */
+    setModelPatterns(patterns: readonly ModelPatternMapping[]): Router;
+    /**
+     * Get current model patterns.
+     */
+    getModelPatterns(): readonly ModelPatternMapping[];
+    /**
+     * Select backend for a request.
+     */
+    selectBackend(request: IRChatRequest, preferredBackend?: string): Promise<string>;
+    /**
+     * Execute request with automatic backend selection and fallback.
+     */
+    execute(request: IRChatRequest, signal?: AbortSignal): Promise<IRChatResponse>;
+    /**
+     * Execute streaming request with automatic backend selection and fallback.
+     */
+    executeStream(request: IRChatRequest, signal?: AbortSignal): IRChatStream;
+    /**
+     * Dispatch request to multiple backends in parallel.
+     */
+    dispatchParallel(request: IRChatRequest, options?: ParallelDispatchOptions, signal?: AbortSignal): Promise<ParallelDispatchResult>;
+    /**
+     * Check health of all backends.
+     */
+    checkHealth(): Promise<Record<string, boolean>>;
+    /**
+     * Check health of specific backend.
+     */
+    checkHealth(name: string): Promise<boolean>;
+    /**
+     * Manually open circuit breaker for a backend.
+     */
+    openCircuitBreaker(name: string, timeoutMs?: number): void;
+    /**
+     * Manually close circuit breaker for a backend.
+     */
+    closeCircuitBreaker(name: string): void;
+    /**
+     * Reset circuit breaker statistics.
+     */
+    resetCircuitBreaker(name?: string): void;
+    /**
+     * Get router statistics.
+     */
+    getStats(): RouterStats;
+    /**
+     * Reset router statistics.
+     */
+    resetStats(): void;
+    /**
+     * Get statistics for specific backend.
+     */
+    getBackendStats(name: string): BackendStats | undefined;
+    /**
+     * Clone router with new configuration.
+     */
+    clone(config: Partial<RouterConfig>): Router;
+    /**
+     * Clean up resources.
+     */
+    dispose(): void;
+}
+//# sourceMappingURL=router.d.ts.map

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

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

package/dist/types/streaming.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Streaming Configuration Types
+ *
+ * Defines how streaming responses should be delivered across the system.
+ * Supports flexible streaming modes with delta (incremental) and accumulated (full text) formats.
+ *
+ * @module
+ */
+/**
+ * Streaming mode determines how chunks are delivered.
+ *
+ * - `delta`: Stream only new content chunks (standard behavior, most efficient)
+ *   - Each chunk contains only the incremental text that was just generated
+ *   - Consumers must accumulate chunks to get full text
+ *   - Example: chunk1="Hello", chunk2=" world", chunk3="!"
+ *
+ * - `accumulated`: Stream full accumulated content so far (Chrome AI behavior)
+ *   - Each chunk contains all text generated up to that point
+ *   - Consumers can use the latest chunk directly without accumulation
+ *   - Example: chunk1="Hello", chunk2="Hello world", chunk3="Hello world!"
+ */
+export type StreamMode = 'delta' | 'accumulated';
+/**
+ * Buffer strategy for accumulated mode.
+ */
+export type BufferStrategy = 'memory' | 'none';
+/**
+ * Streaming configuration options.
+ */
+export interface StreamingConfig {
+    /**
+     * How to deliver streaming chunks.
+     *
+     * - `delta`: Only new content (default, most efficient)
+     * - `accumulated`: Full content accumulated so far (Chrome AI style)
+     *
+     * @default 'delta'
+     */
+    mode?: StreamMode;
+    /**
+     * Whether to include both delta and accumulated in chunks.
+     * Only applicable when mode='accumulated' at backend level.
+     * When true, chunks will contain both formats for maximum flexibility.
+     *
+     * @default false
+     */
+    includeBoth?: boolean;
+    /**
+     * Buffer strategy for accumulated mode.
+     *
+     * - 'memory': Keep full buffer in memory (default, works with any provider)
+     * - 'none': Don't buffer (only works if provider natively gives accumulated)
+     *
+     * @default 'memory'
+     */
+    bufferStrategy?: BufferStrategy;
+}
+/**
+ * Options for stream conversion/transformation.
+ */
+export interface StreamConversionOptions {
+    /**
+     * Target streaming mode for conversion.
+     * If specified, stream will be converted to this mode.
+     */
+    mode?: StreamMode;
+    /**
+     * Whether to preserve original format if already in target mode.
+     * When true, avoids unnecessary conversion overhead.
+     *
+     * @default true
+     */
+    preserveIfMatch?: boolean;
+    /**
+     * Custom buffer transform function.
+     * Applied to accumulated text before yielding.
+     * Useful for sanitization, formatting, etc.
+     */
+    transform?: (text: string) => string;
+    /**
+     * Whether to validate chunk sequence numbers.
+     * When true, throws error if chunks arrive out of order.
+     *
+     * @default false
+     */
+    validateSequence?: boolean;
+}
+/**
+ * Default streaming configuration.
+ */
+export declare const DEFAULT_STREAMING_CONFIG: Required<StreamingConfig>;
+/**
+ * Default conversion options.
+ */
+export declare const DEFAULT_CONVERSION_OPTIONS: Required<Omit<StreamConversionOptions, 'transform'>>;
+//# sourceMappingURL=streaming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../src/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,aAAa,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE/C;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;OAOG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAElB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAErC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,QAAQ,CAAC,eAAe,CAI9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,IAAI,CAAC,uBAAuB,EAAE,WAAW,CAAC,CAI3F,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "ai.matey.types",
+  "version": "0.2.0",
+  "description": "Type definitions for AI Matey - Universal AI Adapter System",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "types",
+    "typescript",
+    "ai-matey"
+  ],
+  "author": "AI Matey",
+  "license": "MIT",
+  "homepage": "https://github.com/johnhenry/ai.matey#readme",
+  "bugs": {
+    "url": "https://github.com/johnhenry/ai.matey/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/ai.matey.git",
+    "directory": "packages/ai.matey.types"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}