ai.matey.core 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/bridge.js

@@ -0,0 +1,657 @@
+"use strict";
+/**
+ * Bridge Implementation
+ *
+ * The Bridge connects frontend and backend adapters with middleware support.
+ * It's the main entry point for making requests through the universal adapter system.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bridge = void 0;
+exports.createBridge = createBridge;
+const ai_matey_types_1 = require("ai.matey.types");
+const middleware_stack_js_1 = require("./middleware-stack.js");
+const ai_matey_errors_1 = require("ai.matey.errors");
+const ai_matey_utils_1 = require("ai.matey.utils");
+// ============================================================================
+// Bridge Implementation
+// ============================================================================
+/**
+ * Bridge connects frontend and backend adapters.
+ *
+ * @template TFrontend Frontend adapter type
+ */
+class Bridge {
+    frontend;
+    backend;
+    config;
+    middlewareStack;
+    // Statistics tracking
+    _totalRequests = 0;
+    _successfulRequests = 0;
+    _failedRequests = 0;
+    _streamingRequests = 0;
+    _latencies = [];
+    static MAX_LATENCY_SAMPLES = 1000; // Prevent unbounded memory growth
+    _errorCounts = {};
+    _statsResetTimestamp = Date.now();
+    // Event listeners (stored for future event emission)
+    _eventListeners = new Map();
+    /**
+     * Create a new Bridge instance.
+     *
+     * @param frontend Frontend adapter
+     * @param backend Backend adapter
+     * @param config Bridge configuration
+     */
+    constructor(frontend, backend, config = {}) {
+        this.frontend = frontend;
+        this.backend = backend;
+        this.config = {
+            debug: config.debug ?? false,
+            timeout: config.timeout ?? 30000,
+            retries: config.retries ?? 0,
+            autoRequestId: config.autoRequestId ?? true,
+            defaultModel: config.defaultModel,
+            routerConfig: config.routerConfig,
+            custom: config.custom,
+        };
+        this.middlewareStack = new middleware_stack_js_1.MiddlewareStack();
+    }
+    // ==========================================================================
+    // Core Request Methods
+    // ==========================================================================
+    /**
+     * Execute a non-streaming chat completion request.
+     */
+    async chat(request, options) {
+        const startTime = Date.now();
+        this._totalRequests++;
+        // Step 1: Convert frontend request to IR
+        const irRequest = await this.frontend.toIR(request);
+        // Step 2: Ensure metadata has requestId and timestamp
+        const enrichedRequest = this.enrichRequest(irRequest, options);
+        // Emit REQUEST_START event
+        this.emit({
+            type: ai_matey_types_1.BridgeEventType.REQUEST_START,
+            timestamp: Date.now(),
+            requestId: enrichedRequest.metadata.requestId,
+            request: enrichedRequest,
+        });
+        const maxAttempts = (this.config.retries ?? 0) + 1;
+        let lastError;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                // Step 3: Validate IR request
+                (0, ai_matey_utils_1.validateIRChatRequest)(enrichedRequest, {
+                    frontend: this.frontend.metadata.name,
+                });
+                // Step 4: Create middleware context
+                const context = (0, middleware_stack_js_1.createMiddlewareContext)(enrichedRequest, this.config, options?.signal);
+                // Step 5: Execute middleware stack + backend
+                const irResponse = await this.middlewareStack.execute(context, async () => {
+                    // Call backend adapter
+                    return await this.backend.execute(enrichedRequest, options?.signal);
+                });
+                // Step 6: Enrich response with provenance
+                const enrichedResponse = this.enrichResponse(irResponse, enrichedRequest);
+                // Step 7: Convert IR response to frontend format
+                const frontendResponse = await this.frontend.fromIR(enrichedResponse);
+                // Track success
+                this._successfulRequests++;
+                const durationMs = Date.now() - startTime;
+                this.recordLatency(durationMs);
+                // Emit REQUEST_SUCCESS event
+                this.emit({
+                    type: ai_matey_types_1.BridgeEventType.REQUEST_SUCCESS,
+                    timestamp: Date.now(),
+                    requestId: enrichedRequest.metadata.requestId,
+                    request: enrichedRequest,
+                    response: enrichedResponse,
+                    durationMs,
+                });
+                return frontendResponse;
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                // Don't retry on non-retryable errors or if this is the last attempt
+                const isRetryable = error instanceof ai_matey_errors_1.AdapterError ? error.isRetryable : true;
+                if (!isRetryable || attempt >= maxAttempts) {
+                    break;
+                }
+                // Wait before retrying (simple exponential backoff)
+                await this.delay(Math.min(1000 * Math.pow(2, attempt - 1), 10000));
+            }
+        }
+        // Track failure
+        this._failedRequests++;
+        const errorCode = lastError instanceof ai_matey_errors_1.AdapterError ? lastError.code : 'UNKNOWN';
+        this._errorCounts[errorCode] = (this._errorCounts[errorCode] ?? 0) + 1;
+        // Emit REQUEST_ERROR event
+        this.emit({
+            type: ai_matey_types_1.BridgeEventType.REQUEST_ERROR,
+            timestamp: Date.now(),
+            requestId: enrichedRequest.metadata.requestId,
+            request: enrichedRequest,
+            error: lastError,
+            durationMs: Date.now() - startTime,
+        });
+        // Re-throw adapter errors, wrap others
+        // lastError is guaranteed to be defined here (we only reach this point if all retries failed)
+        if (!lastError) {
+            throw new Error('Bridge execution failed with no error information');
+        }
+        if (lastError instanceof ai_matey_errors_1.AdapterError) {
+            throw lastError;
+        }
+        throw new ai_matey_errors_1.AdapterError({
+            code: ai_matey_errors_1.ErrorCode.INTERNAL_ERROR,
+            message: `Bridge execution failed: ${lastError.message}`,
+            isRetryable: false,
+            cause: lastError,
+            provenance: {},
+        });
+    }
+    /**
+     * Execute a streaming chat completion request.
+     */
+    async *chatStream(request, options) {
+        const startTime = Date.now();
+        this._totalRequests++;
+        this._streamingRequests++;
+        // Step 1: Convert frontend request to IR
+        const irRequest = await this.frontend.toIR(request);
+        // Step 2: Ensure streaming is enabled
+        const streamingRequest = {
+            ...irRequest,
+            stream: true,
+        };
+        // Step 3: Ensure metadata has requestId and timestamp
+        const enrichedRequest = this.enrichRequest(streamingRequest, options);
+        // Emit STREAM_START event
+        this.emit({
+            type: ai_matey_types_1.BridgeEventType.STREAM_START,
+            timestamp: Date.now(),
+            requestId: enrichedRequest.metadata.requestId,
+            request: enrichedRequest,
+        });
+        try {
+            // Step 4: Validate IR request
+            (0, ai_matey_utils_1.validateIRChatRequest)(enrichedRequest, {
+                frontend: this.frontend.metadata.name,
+            });
+            // Step 5: Create streaming middleware context
+            const context = (0, middleware_stack_js_1.createStreamingMiddlewareContext)(enrichedRequest, this.config, options?.signal);
+            // Step 6: Execute middleware stack + backend
+            const irStream = await this.middlewareStack.executeStream(context, async () => {
+                // Call backend adapter streaming
+                return this.backend.executeStream(enrichedRequest, options?.signal);
+            });
+            // Step 7: Convert IR stream to frontend format
+            const frontendStream = this.frontend.fromIRStream(irStream);
+            // Step 8: Yield chunks to caller
+            let chunkSequence = 0;
+            for await (const chunk of frontendStream) {
+                chunkSequence++;
+                yield chunk;
+            }
+            // Track success (after stream completes)
+            this._successfulRequests++;
+            const durationMs = Date.now() - startTime;
+            this.recordLatency(durationMs);
+            // Emit STREAM_COMPLETE event
+            this.emit({
+                type: ai_matey_types_1.BridgeEventType.STREAM_COMPLETE,
+                timestamp: Date.now(),
+                requestId: enrichedRequest.metadata.requestId,
+                request: enrichedRequest,
+                chunkSequence,
+                durationMs,
+            });
+        }
+        catch (error) {
+            // Track failure
+            this._failedRequests++;
+            const errorCode = error instanceof ai_matey_errors_1.AdapterError ? error.code : 'UNKNOWN';
+            this._errorCounts[errorCode] = (this._errorCounts[errorCode] ?? 0) + 1;
+            // Emit STREAM_ERROR event
+            this.emit({
+                type: ai_matey_types_1.BridgeEventType.STREAM_ERROR,
+                timestamp: Date.now(),
+                requestId: enrichedRequest.metadata.requestId,
+                request: enrichedRequest,
+                error: error instanceof Error ? error : new Error(String(error)),
+                durationMs: Date.now() - startTime,
+            });
+            // Re-throw adapter errors, wrap others
+            if (error instanceof ai_matey_errors_1.AdapterError) {
+                throw error;
+            }
+            throw new ai_matey_errors_1.AdapterError({
+                code: ai_matey_errors_1.ErrorCode.INTERNAL_ERROR,
+                message: `Bridge streaming failed: ${error instanceof Error ? error.message : String(error)}`,
+                isRetryable: false,
+                cause: error instanceof Error ? error : undefined,
+                provenance: {},
+            });
+        }
+    }
+    // ==========================================================================
+    // Model Listing
+    // ==========================================================================
+    /**
+     * List available models from the backend.
+     *
+     * This delegates directly to the backend adapter's listModels() method.
+     * Useful for discovering available models before making requests.
+     *
+     * @param options Options for listing models (filtering, cache control)
+     * @returns List of available models, or null if backend doesn't support listing
+     */
+    async listModels(options) {
+        if (!this.backend.listModels) {
+            return null; // Backend doesn't support model listing
+        }
+        return await this.backend.listModels(options);
+    }
+    /**
+     * Check if a specific model is available from the backend.
+     *
+     * @param modelId Model identifier to check
+     * @returns true if model is available, false otherwise
+     */
+    async hasModel(modelId) {
+        const result = await this.listModels();
+        if (!result) {
+            return true;
+        } // Can't check, assume available
+        return result.models.some((m) => m.id === modelId);
+    }
+    /**
+     * Validate that a model is available (optional safety check).
+     *
+     * Note: This is an optional validation - the system doesn't automatically
+     * validate models since cross-provider translation is supported.
+     *
+     * @param modelId Model identifier to validate
+     * @throws {ValidationError} If model is not available
+     */
+    async validateModel(modelId) {
+        const available = await this.hasModel(modelId);
+        if (!available) {
+            throw new ai_matey_errors_1.ValidationError({
+                code: ai_matey_errors_1.ErrorCode.UNSUPPORTED_MODEL,
+                message: `Model "${modelId}" is not available from backend "${this.backend.metadata.name}"`,
+                validationDetails: [
+                    {
+                        field: 'model',
+                        value: modelId,
+                        reason: `Model not available from backend "${this.backend.metadata.name}"`,
+                        expected: 'Available model ID from backend',
+                    },
+                ],
+                provenance: {
+                    frontend: this.frontend.metadata.name,
+                    backend: this.backend.metadata.name,
+                },
+            });
+        }
+    }
+    // ==========================================================================
+    // Middleware Management
+    // ==========================================================================
+    /**
+     * Add middleware to the bridge's middleware stack.
+     */
+    use(middleware) {
+        this.middlewareStack.use(middleware);
+        return this;
+    }
+    /**
+     * Remove middleware from the stack.
+     *
+     * @param middleware Middleware to remove
+     * @returns This bridge for chaining
+     */
+    removeMiddleware(middleware) {
+        this.middlewareStack.remove(middleware);
+        return this;
+    }
+    /**
+     * Clear all middleware from the stack.
+     */
+    clearMiddleware() {
+        this.middlewareStack.clear();
+        return this;
+    }
+    /**
+     * Get all middleware in the stack.
+     */
+    getMiddleware() {
+        return this.middlewareStack.getMiddleware();
+    }
+    // ==========================================================================
+    // Event Handling
+    // ==========================================================================
+    /**
+     * Register an event listener.
+     *
+     * Note: Event emission is not yet implemented. Listeners are stored
+     * for future use when event emission is added.
+     *
+     * @param event Event type to listen for, or '*' for all events
+     * @param listener Callback function
+     */
+    on(event, listener) {
+        const key = event;
+        if (!this._eventListeners.has(key)) {
+            this._eventListeners.set(key, new Set());
+        }
+        this._eventListeners.get(key).add(listener);
+        return this;
+    }
+    /**
+     * Remove an event listener.
+     *
+     * @param event Event type
+     * @param listener Callback function to remove
+     */
+    off(event, listener) {
+        const key = event;
+        const listeners = this._eventListeners.get(key);
+        if (listeners) {
+            listeners.delete(listener);
+        }
+        return this;
+    }
+    /**
+     * Register a one-time event listener.
+     *
+     * Note: Event emission is not yet implemented. Listeners are stored
+     * for future use when event emission is added.
+     *
+     * @param event Event type to listen for
+     * @param listener Callback function
+     */
+    once(event, listener) {
+        const wrappedListener = (eventData) => {
+            this.off(event, wrappedListener);
+            return listener(eventData);
+        };
+        return this.on(event, wrappedListener);
+    }
+    // ==========================================================================
+    // Statistics & Monitoring
+    // ==========================================================================
+    /**
+     * Get runtime statistics for this bridge.
+     *
+     * @returns Bridge statistics including request counts, latencies, and error breakdown
+     */
+    getStats() {
+        const sortedLatencies = [...this._latencies].sort((a, b) => a - b);
+        const len = sortedLatencies.length;
+        const getPercentile = (p) => {
+            if (len === 0) {
+                return 0;
+            }
+            const index = Math.ceil((p / 100) * len) - 1;
+            return sortedLatencies[Math.max(0, Math.min(index, len - 1))] ?? 0;
+        };
+        const avgLatency = len > 0 ? sortedLatencies.reduce((a, b) => a + b, 0) / len : 0;
+        return {
+            totalRequests: this._totalRequests,
+            successfulRequests: this._successfulRequests,
+            failedRequests: this._failedRequests,
+            successRate: this._totalRequests > 0 ? (this._successfulRequests / this._totalRequests) * 100 : 100,
+            streamingRequests: this._streamingRequests,
+            averageLatencyMs: Math.round(avgLatency),
+            p50LatencyMs: getPercentile(50),
+            p95LatencyMs: getPercentile(95),
+            p99LatencyMs: getPercentile(99),
+            backendUsage: {
+                [this.backend.metadata.name]: this._successfulRequests,
+            },
+            errorBreakdown: { ...this._errorCounts },
+            sinceTimestamp: this._statsResetTimestamp,
+        };
+    }
+    /**
+     * Reset all statistics to zero.
+     */
+    resetStats() {
+        this._totalRequests = 0;
+        this._successfulRequests = 0;
+        this._failedRequests = 0;
+        this._streamingRequests = 0;
+        this._latencies = [];
+        this._errorCounts = {};
+        this._statsResetTimestamp = Date.now();
+    }
+    // ==========================================================================
+    // Utility Methods
+    // ==========================================================================
+    /**
+     * Get router instance (returns null for basic Bridge).
+     */
+    getRouter() {
+        return null;
+    }
+    /**
+     * Check health of the backend.
+     *
+     * @returns true if backend is healthy, false otherwise
+     */
+    async checkHealth() {
+        if (this.backend.healthCheck) {
+            return await this.backend.healthCheck();
+        }
+        return true; // Assume healthy if no health check is available
+    }
+    /**
+     * Get a copy of the bridge configuration.
+     *
+     * @returns Readonly copy of the bridge configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Clone bridge with new configuration.
+     */
+    clone(config) {
+        return new Bridge(this.frontend, this.backend, {
+            ...this.config,
+            ...config,
+        });
+    }
+    /**
+     * Clean up resources.
+     */
+    dispose() {
+        // Cleanup logic if needed
+    }
+    // ==========================================================================
+    // Private Helper Methods
+    // ==========================================================================
+    /**
+     * Enrich request with metadata (requestId, timestamp, provenance) and apply defaults.
+     */
+    enrichRequest(request, options) {
+        // Always generate requestId if missing (frontend adapters should provide it)
+        const requestId = request.metadata?.requestId || this.generateRequestId();
+        const timestamp = request.metadata?.timestamp ?? Date.now();
+        // Apply default model if not specified in request
+        const model = request.parameters?.model ?? this.config.defaultModel;
+        return {
+            ...request,
+            parameters: {
+                ...request.parameters,
+                ...(model && { model }),
+            },
+            metadata: {
+                ...request.metadata,
+                requestId,
+                timestamp,
+                provenance: {
+                    ...request.metadata?.provenance,
+                    frontend: this.frontend.metadata.name,
+                },
+                custom: {
+                    ...request.metadata?.custom,
+                    ...options?.metadata,
+                },
+            },
+        };
+    }
+    /**
+     * Enrich response with provenance and timing.
+     */
+    enrichResponse(response, request) {
+        return {
+            ...response,
+            metadata: {
+                ...response.metadata,
+                requestId: request.metadata.requestId,
+                provenance: {
+                    ...response.metadata.provenance,
+                    frontend: this.frontend.metadata.name,
+                    backend: this.backend.metadata.name,
+                },
+            },
+        };
+    }
+    /**
+     * Generate unique request ID.
+     */
+    generateRequestId() {
+        // Use standard UUID v4 for request IDs
+        return crypto.randomUUID();
+    }
+    /**
+     * Generate a structured object matching a Zod schema using an LLM.
+     *
+     * This method uses tool calling to extract structured data from the LLM response,
+     * validates it against the provided schema, and returns the typed object.
+     *
+     * @param options Configuration for object generation
+     * @returns Promise resolving to the generated and validated object
+     *
+     * @example
+     * ```typescript
+     * const UserSchema = z.object({
+     *   name: z.string(),
+     *   age: z.number(),
+     *   email: z.string().email(),
+     * });
+     *
+     * const result = await bridge.generateObject({
+     *   schema: UserSchema,
+     *   prompt: 'Generate a user profile for Alice, age 30',
+     *   model: 'gpt-4',
+     * });
+     *
+     * console.log(result.object); // { name: 'Alice', age: 30, email: '...' }
+     * ```
+     */
+    generateObject = (0, ai_matey_utils_1.createGenerateObject)(this);
+    /**
+     * Stream a structured object matching a Zod schema using an LLM.
+     *
+     * This method uses streaming tool calling to incrementally build up a structured
+     * object, yielding partial results as they become available.
+     *
+     * @param options Configuration for streaming object generation
+     * @returns Async generator yielding partial objects and returning the final validated object
+     *
+     * @example
+     * ```typescript
+     * const ArticleSchema = z.object({
+     *   title: z.string(),
+     *   content: z.string(),
+     *   tags: z.array(z.string()),
+     * });
+     *
+     * const stream = bridge.streamObject({
+     *   schema: ArticleSchema,
+     *   prompt: 'Write a blog post about TypeScript',
+     *   onPartial: (partial) => {
+     *     console.log('Partial:', partial);
+     *   },
+     * });
+     *
+     * for await (const partial of stream) {
+     *   console.log('Progress:', partial);
+     * }
+     * ```
+     */
+    streamObject = (0, ai_matey_utils_1.createStreamObject)(this);
+    /**
+     * Emit an event to all registered listeners.
+     *
+     * @param event Event data to emit
+     */
+    emit(event) {
+        // Emit to specific event type listeners
+        const specificListeners = this._eventListeners.get(event.type);
+        if (specificListeners) {
+            for (const listener of specificListeners) {
+                try {
+                    void listener(event);
+                }
+                catch {
+                    // Ignore listener errors to prevent breaking the chain
+                }
+            }
+        }
+        // Emit to wildcard listeners
+        const wildcardListeners = this._eventListeners.get('*');
+        if (wildcardListeners) {
+            for (const listener of wildcardListeners) {
+                try {
+                    void listener(event);
+                }
+                catch {
+                    // Ignore listener errors to prevent breaking the chain
+                }
+            }
+        }
+    }
+    /**
+     * Record a latency sample, maintaining a rolling window to prevent unbounded memory growth.
+     *
+     * @param latencyMs Latency in milliseconds
+     */
+    recordLatency(latencyMs) {
+        this._latencies.push(latencyMs);
+        // Maintain rolling window to prevent memory leak in long-running applications
+        if (this._latencies.length > Bridge.MAX_LATENCY_SAMPLES) {
+            this._latencies.shift();
+        }
+    }
+    /**
+     * Delay execution for a specified number of milliseconds.
+     *
+     * @param ms Milliseconds to delay
+     */
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.Bridge = Bridge;
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a new Bridge instance.
+ *
+ * @param frontend Frontend adapter
+ * @param backend Backend adapter
+ * @param config Bridge configuration
+ * @returns Bridge instance
+ */
+function createBridge(frontend, backend, config) {
+    return new Bridge(frontend, backend, config);
+}
+//# sourceMappingURL=bridge.js.map