@x12i/ai-gateway 7.9.1

package/dist/gateway.js

@@ -0,0 +1,430 @@
+/**
+ * @x12i/ai-gateway
+ *
+ * Simplified AI Gateway - Clean proxy implementation
+ */
+import { validateChatRequest, validateAIRequest } from './gateway-validation.js';
+import { ensureGatewayRequestIdentity } from './activity-manager.js';
+import { initializeGatewayComponents, loadConfig } from './gateway-config.js';
+import { buildMessages } from './message-builder.js';
+import { extractJsonFromFlexMd } from './flex-md-loader.js';
+import { mergeConfig } from './gateway-utils.js';
+import { autoRegisterProviders } from './gateway-provider-auto-register.js';
+import { setGatewayLastJobId, setGatewayRuntimeClients } from './runtime-objects.js';
+/** Error message thrown by the router when no provider is registered or specified */
+const NO_PROVIDER_ERROR = 'No provider specified and no providers registered';
+const NO_PROVIDER_HINT = ' Set OPEN_ROUTER_KEY (or OPENROUTER_API_KEY) in the environment to use OpenRouter, or register a provider with the router (e.g. via autoRegisterProviders or gateway config).';
+/**
+ * Simplified AI Gateway - Clean proxy implementation
+ */
+export class AIGateway {
+    router;
+    config;
+    logger;
+    activityManager;
+    messageBuilderConfig;
+    _autoRegisterDone = false;
+    constructor(config = {}, activityManager) {
+        this.config = config;
+        this.activityManager = activityManager;
+        // Load configuration and initialize components
+        const { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering } = loadConfig();
+        const components = initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering);
+        this.logger = components.logger;
+        this.router = components.router;
+        this.activityManager = components.activityManager;
+        this.messageBuilderConfig = components.messageBuilderConfig;
+        setGatewayRuntimeClients({
+            activix: this.activityManager?.getTracker(),
+            logger: this.logger
+        });
+        this.logger.info('AI Gateway initialized with full component stack', {
+            hasActivityManager: !!this.activityManager,
+            hasMessageBuilder: !!this.messageBuilderConfig
+        });
+    }
+    /**
+     * Invoke chat request (without structured output requirements)
+     */
+    async invokeChat(request) {
+        const startTime = Date.now();
+        // Basic validation
+        validateChatRequest(request);
+        if (!this.activityManager) {
+            ensureGatewayRequestIdentity(request);
+        }
+        setGatewayLastJobId(resolveRuntimeJobId(request));
+        // Generate simple task type ID
+        const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
+        // Simple message construction
+        const messages = this.buildSimpleMessages(request);
+        // Merge config (modelConfig > request.config > gateway defaults)
+        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
+        if (!this._autoRegisterDone) {
+            await autoRegisterProviders(this.router, this.logger);
+            this._autoRegisterDone = true;
+        }
+        // Start activity tracking if available
+        let activity = undefined;
+        if (this.activityManager) {
+            try {
+                activity = await this.activityManager.startActivity(request, startTime);
+            }
+            catch (activityError) {
+                // Log activity tracking error but don't fail the request
+                this.logger.warn('Failed to start activity tracking', {
+                    aiRequestId: request.aiRequestId,
+                    error: activityError instanceof Error ? activityError.message : String(activityError)
+                });
+            }
+        }
+        try {
+            // Call router directly with merged config
+            const response = await this.router.invoke({
+                request: {
+                    messages,
+                    config: mergedConfig,
+                    identity: request.identity
+                },
+                mode: 'sync'
+            });
+            // Create enhanced response
+            const enhancedResponse = {
+                content: response.content || '',
+                metadata: {
+                    aiRequestId: request.aiRequestId,
+                    identity: request.identity,
+                    latencyMs: Date.now() - startTime,
+                    tokens: response.usage || { prompt: 0, completion: 0, total: 0 },
+                    taskTypeId,
+                    agentType: 'chat'
+                }
+            };
+            // Track activity success if activity was started
+            if (activity) {
+                try {
+                    await this.activityManager.logSuccess(activity, {
+                        response: enhancedResponse,
+                        endTime: Date.now(),
+                        duration: Date.now() - startTime
+                    });
+                }
+                catch (activityError) {
+                    // Log activity tracking error but don't fail the request
+                    this.logger.warn('Failed to track activity success', {
+                        aiRequestId: request.aiRequestId,
+                        error: activityError instanceof Error ? activityError.message : String(activityError)
+                    });
+                }
+            }
+            return enhancedResponse;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (err.message.includes(NO_PROVIDER_ERROR)) {
+                throw new Error(err.message + NO_PROVIDER_HINT);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Invoke AI request (with structured output support)
+     */
+    async invoke(request) {
+        const startTime = Date.now();
+        // Basic validation
+        validateAIRequest(request);
+        if (!this.activityManager) {
+            ensureGatewayRequestIdentity(request);
+        }
+        setGatewayLastJobId(resolveRuntimeJobId(request));
+        // Generate simple task type ID
+        const taskTypeId = request.taskTypeId || `task-${Date.now()}`;
+        // Resolve instructions and build messages using proper components
+        let resolvedRequest = request;
+        let messages = [];
+        // Create parsedSnapshot to store parsed request data and messages
+        const parsedSnapshot = {};
+        // Use proper instruction resolution and message building
+        let builtMessages;
+        try {
+            builtMessages = await buildMessages(request, this.messageBuilderConfig, {
+                parsedSnapshot
+            });
+            messages = builtMessages.messages;
+            resolvedRequest = request;
+        }
+        catch (error) {
+            // If message building fails (e.g., prompt/instruction resolution error), log as bad request
+            const err = error instanceof Error ? error : new Error(String(error));
+            const endTime = Date.now();
+            const duration = endTime - startTime;
+            // Determine if this is a prompt/instruction resolution error
+            // If a key was provided but couldn't be resolved to content, it's a bad request
+            const errWithCode = err; // Type assertion for error with optional code property
+            const isResolutionError = err.name === 'InstructionNotFoundError' ||
+                err.name === 'InstructionBackendError' ||
+                err.name === 'TemplateResolutionError' ||
+                errWithCode.code === 'PROMPT_NOT_FOUND' ||
+                errWithCode.code === 'PROMPT_RESOLUTION_ERROR' ||
+                errWithCode.code === 'PROMPT_RENDERED_EMPTY' ||
+                errWithCode.code === 'TEMPLATE_RESOLUTION_ERROR' ||
+                errWithCode.code === 'TEMPLATE_VARIABLE_MISSING' ||
+                err.message.includes('Failed to resolve') ||
+                err.message.includes('Failed to render prompt template') ||
+                err.message.includes('not found') ||
+                err.message.includes('Instruction not found') ||
+                err.message.includes('Prompt not found');
+            if (isResolutionError && this.activityManager) {
+                // Log to bad requests collection
+                await this.activityManager.logBadRequest(request, err, {
+                    endTime,
+                    duration,
+                    error: err.message,
+                    errorType: errWithCode.code || 'MessageBuildError',
+                    diagnosticInfo: {
+                        errorCode: errWithCode.code,
+                        errorName: err.name,
+                        failureType: 'validation-failure',
+                        stage: 'message-building',
+                        prompt: request.prompt,
+                        instructions: typeof request.instructions === 'string' ? request.instructions.substring(0, 100) : '(object)'
+                    },
+                    failureType: 'validation-failure'
+                }, startTime);
+            }
+            // Re-throw the error so it propagates to the caller
+            throw err;
+        }
+        // Store messages in parsedSnapshot for activity tracking
+        parsedSnapshot.messages = messages;
+        // parsed.instructions and parsed.prompt are set by buildMessages to the resolved/rendered content
+        // (after key resolution and Rendrix). Do not overwrite with raw request keys.
+        if (parsedSnapshot.context === undefined) {
+            parsedSnapshot.context = request.context;
+        }
+        // Attach parsedSnapshot to request for activity tracking
+        request._parsedRequest = parsedSnapshot;
+        // Merge config (modelConfig > request.config > gateway defaults)
+        const mergedConfig = await mergeConfig(request, this.config, this.logger);
+        // Lazy auto-register providers from env (OPENAI_API_KEY, etc.) so consumers don't have to call init
+        if (!this._autoRegisterDone) {
+            await autoRegisterProviders(this.router, this.logger);
+            this._autoRegisterDone = true;
+        }
+        // Start activity tracking if available
+        let activity = undefined;
+        if (this.activityManager) {
+            try {
+                activity = await this.activityManager.startActivity(request, startTime);
+            }
+            catch (activityError) {
+                // Log activity tracking error but don't fail the request
+                this.logger.warn('Failed to start activity tracking', {
+                    aiRequestId: request.aiRequestId,
+                    error: activityError instanceof Error ? activityError.message : String(activityError)
+                });
+            }
+        }
+        try {
+            // Call router directly with merged config
+            const response = await this.router.invoke({
+                request: {
+                    messages,
+                    config: mergedConfig,
+                    identity: request.identity
+                },
+                mode: 'sync'
+            });
+            // Contract output processing removed - expectedSchema no longer supported
+            // Create enhanced response - extract content properly from router response
+            const routerResponse = response;
+            // Extract content from router response - router returns outputText, not content
+            let content = routerResponse.content || routerResponse.outputText || '';
+            // If content is still empty, try to extract from ai-activities metadata
+            if (!content && routerResponse.metadata?.['ai-activities-response']?.outputText) {
+                content = routerResponse.metadata['ai-activities-response'].outputText;
+            }
+            // Parse content using available parsers (flex-md, content normalizer, etc.)
+            let parsedContent = undefined;
+            let contentType = undefined;
+            let parsingMethod = undefined;
+            // Actually use flex-md parsing - extract structured data from markdown
+            try {
+                this.logger.debug('Attempting flex-md extraction', {
+                    aiRequestId: request.aiRequestId,
+                    contentLength: content.length,
+                    hasInstructions: !!resolvedRequest.instructions
+                });
+                // Let flex-md extract structured data from the response content
+                const extractionResult = await extractJsonFromFlexMd(content);
+                this.logger.debug('Flex-md extraction result', {
+                    aiRequestId: request.aiRequestId,
+                    hasResult: !!extractionResult,
+                    hasJson: !!(extractionResult && extractionResult.json),
+                    method: extractionResult?.method,
+                    jsonType: extractionResult?.json ? typeof extractionResult.json : 'none'
+                });
+                if (extractionResult && extractionResult.json) {
+                    // Successfully extracted structured data
+                    parsedContent = extractionResult.json;
+                    this.logger.info('Flex-md extraction successful - parsed into structured object', {
+                        aiRequestId: request.aiRequestId,
+                        method: extractionResult.method,
+                        extractedKeys: Object.keys(extractionResult.json)
+                    });
+                }
+                else {
+                    // Extraction failed, fall back to raw text wrapper
+                    this.logger.warn('Flex-md extraction failed - no structured data extracted', {
+                        aiRequestId: request.aiRequestId,
+                        hasResult: !!extractionResult,
+                        method: extractionResult?.method || 'none'
+                    });
+                    parsedContent = { rawText: content };
+                }
+            }
+            catch (extractionError) {
+                // Extraction failed, fall back to raw text wrapper
+                const errorMessage = extractionError instanceof Error ? extractionError.message : String(extractionError);
+                this.logger.warn('Flex-md extraction failed - flex-md library compatibility issue', {
+                    aiRequestId: request.aiRequestId,
+                    error: errorMessage,
+                    issue: 'flex-md uses require() in ES module context - needs fixing in flex-md-loader.ts',
+                    fallback: 'using rawText wrapper'
+                });
+                parsedContent = { rawText: content };
+            }
+            contentType = 'structured';
+            parsingMethod = 'flex-md';
+            // Extract token usage properly
+            let tokens = { prompt: 0, completion: 0, total: 0 };
+            if (routerResponse.usage) {
+                tokens = {
+                    prompt: routerResponse.usage.promptTokens || routerResponse.usage.inputTokens || 0,
+                    completion: routerResponse.usage.completionTokens || routerResponse.usage.outputTokens || 0,
+                    total: routerResponse.usage.totalTokens || 0
+                };
+            }
+            else if (routerResponse.metadata?.['ai-activities-response']?.usage) {
+                const usage = routerResponse.metadata['ai-activities-response'].usage;
+                tokens = {
+                    prompt: usage.promptTokens || usage.inputTokens || 0,
+                    completion: usage.completionTokens || usage.outputTokens || 0,
+                    total: usage.totalTokens || 0
+                };
+            }
+            const enhancedResponse = {
+                content: content,
+                parsedContent: parsedContent,
+                metadata: {
+                    aiRequestId: request.aiRequestId,
+                    identity: request.identity,
+                    latencyMs: Date.now() - startTime,
+                    tokens: tokens,
+                    taskTypeId,
+                    agentType: 'ai',
+                    contentType,
+                    parsingMethod
+                }
+            };
+            // Track activity success if activity was started
+            if (activity) {
+                try {
+                    // Create activity response with proper structure for ActivityTracker
+                    const activityResponse = {
+                        content: {
+                            rawContent: content, // Store the actual response content as rawContent
+                            fullResponse: routerResponse.rawResponse || routerResponse // Include full router response
+                        },
+                        parsed: parsedContent, // Include parsed content in activity record
+                        metadata: enhancedResponse.metadata,
+                        status: 'success',
+                        error: null,
+                        usage: tokens
+                    };
+                    await this.activityManager.logSuccess(activity, {
+                        response: activityResponse,
+                        endTime: Date.now(),
+                        duration: Date.now() - startTime
+                    });
+                }
+                catch (activityError) {
+                    // Log activity tracking error but don't fail the request
+                    this.logger.warn('Failed to track activity success', {
+                        aiRequestId: request.aiRequestId,
+                        error: activityError instanceof Error ? activityError.message : String(activityError)
+                    });
+                }
+            }
+            console.debug('gateway: enhancedResponse:', enhancedResponse);
+            return enhancedResponse;
+        }
+        catch (error) {
+            const err = error instanceof Error ? error : new Error(String(error));
+            if (err.message.includes(NO_PROVIDER_ERROR)) {
+                throw new Error(err.message + NO_PROVIDER_HINT);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Build simple messages from request (instructions and prompt as literal template text; no registry).
+     */
+    buildSimpleMessages(request) {
+        const messages = [];
+        // Add instructions as system message if present
+        if (request.instructions) {
+            const instructions = typeof request.instructions === 'string'
+                ? request.instructions
+                : 'Default instructions';
+            messages.push({ role: 'system', content: instructions });
+        }
+        // Add context as assistant message if present
+        if (request.context) {
+            const context = typeof request.context === 'string'
+                ? request.context
+                : JSON.stringify(request.context);
+            messages.push({ role: 'assistant', content: context });
+        }
+        // Add prompt/input as user message
+        // Input field has been removed - prompt template should contain {{input}} which resolves from workingMemory.input
+        const userContent = request.prompt || '';
+        if (userContent) {
+            messages.push({ role: 'user', content: userContent });
+        }
+        // Add direct messages if present
+        if (request.messages) {
+            messages.push(...request.messages);
+        }
+        return messages;
+    }
+    // Provider management methods
+    register(provider) {
+        this.router.registerProvider(provider);
+    }
+    listProviders() {
+        return this.router.listProviders ? this.router.listProviders() : [];
+    }
+    // Utility methods
+    getRouter() {
+        return this.router;
+    }
+    getLogger() {
+        return this.logger;
+    }
+    getActivityManager() {
+        return this.activityManager;
+    }
+    setActivityManager(activityManager) {
+        this.activityManager = activityManager;
+        setGatewayRuntimeClients({
+            activix: this.activityManager.getTracker(),
+            logger: this.logger
+        });
+    }
+}
+function resolveRuntimeJobId(request) {
+    return request.identity?.jobId ?? request.jobId ?? request.identity?.sessionId ?? request.aiRequestId;
+}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @x12i/ai-gateway
+ *
+ * Unified gateway for LLM provider routing and management.
+ * This package exposes all functionality from @x12i/ai-providers-router
+ * with enhanced features: context propagation, usage tier tracking, and comprehensive metadata.
+ */
+export { LLMProviderRouter } from '@x12i/ai-providers-router';
+export type { RouterConfig, HealthCheckResult } from '@x12i/ai-providers-router';
+export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
+export type { CreateRouterConfig } from '@x12i/ai-providers-router';
+export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+export type { RequestInterceptor, ResponseInterceptor } from '@x12i/ai-providers-router';
+export type { UsageTracker } from '@x12i/ai-providers-router';
+export * from '@x12i/ai-providers-router';
+export { AIGateway } from './gateway.js';
+export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
+export { autoRegisterProviders } from './gateway-provider-auto-register.js';
+export type { GatewayConfig, ProviderModelRef, ModelConfig, RetryConfig, ChatRequest, AIRequest, EnhancedLLMResponse, InstructionMetadata, ValidationRule, ResponseTransformationConfig, TemplateRenderOptions } from './types.js';
+export { mergeTemplateRenderOptions } from './template-render-merge.js';
+export type { UsageTier } from './types.js';
+export { Activix } from '@x12i/activix';
+export type { ActivixRunContext, FindByRunContextCriteria } from '@x12i/activix';
+export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
+export type { ActivityIdentity } from './types.js';
+export { createLogxer } from '@x12i/logxer';
+export type { Logxer } from '@x12i/logxer';
+export { runtimeObjects } from './runtime-objects.js';
+export type { ActivixQueryableClient, LogxerQueryableClient, PackageRuntimeObjects, RuntimeObjects } from './runtime-objects.js';
+export { GatewayRateLimiter } from './gateway-rate-limiter.js';
+export { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, DEFAULT_RATE_LIMIT_ENABLED } from './gateway-rate-limiter-constants.js';
+export { validateAIRequest, validateJSON, extractJSON, validateResponse, diagnoseRequest, diagnoseResponse, supportsJSONMode, createTestAIRequest, createValidationTestCases, runValidationTests, formatDiagnostic, assertValidAIRequest } from './troubleshooting-helper.js';
+export type { ValidationResult, DiagnosticInfo } from './troubleshooting-helper.js';
+export { OBJECT_TYPES_LIBRARY, getObjectType, getObjectTypesForAgent } from './object-types-library.js';
+export type { ReasoningResult, AuditReport, ScopeDefinition, DiscoveryFindings, ActionPlan, ExecutionResult } from './object-types-library.js';
+export { initializeObjectTypesLibrary, getObjectTypesLibrary, resetObjectTypesLibrary } from './object-types-library-integration.js';

package/dist/index.js

@@ -0,0 +1,55 @@
+/**
+ * @x12i/ai-gateway
+ *
+ * Unified gateway for LLM provider routing and management.
+ * This package exposes all functionality from @x12i/ai-providers-router
+ * with enhanced features: context propagation, usage tier tracking, and comprehensive metadata.
+ */
+// Re-export router class and types (base functionality)
+export { LLMProviderRouter } from '@x12i/ai-providers-router';
+// Re-export factory functions
+export { createRouter, createRouterFromConfig } from '@x12i/ai-providers-router';
+// Re-export error classes
+export { ProviderNotFoundError, FallbackExhaustedError } from '@x12i/ai-providers-router';
+// Re-export all from router (includes everything it exports)
+export * from '@x12i/ai-providers-router';
+// Export enhanced gateway
+export { AIGateway } from './gateway.js';
+export { InstructionNotFoundError, InstructionBackendError } from './instruction-errors.js';
+export { autoRegisterProviders } from './gateway-provider-auto-register.js';
+export { mergeTemplateRenderOptions } from './template-render-merge.js';
+// Usage tracking: UsageTracker class methods are available but consumption calculation is disabled
+// (x-models was previously used for RPM/TPM tracking but is no longer integrated)
+// Re-export activity tracking primitives (Activix)
+export { Activix } from '@x12i/activix';
+export { ActivityManager, ensureGatewayRequestIdentity } from './activity-manager.js';
+// Re-export logging (@x12i/logxer)
+export { createLogxer } from '@x12i/logxer';
+// Runtime observability surface (leaf package: no downstream runtime objects)
+export { runtimeObjects } from './runtime-objects.js';
+// Export rate limiter
+export { GatewayRateLimiter } from './gateway-rate-limiter.js';
+export { DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS, DEFAULT_RATE_LIMIT_ENABLED } from './gateway-rate-limiter-constants.js';
+// Export troubleshooting helpers
+export { validateAIRequest, validateJSON, extractJSON, validateResponse, diagnoseRequest, diagnoseResponse, supportsJSONMode, createTestAIRequest, createValidationTestCases, runValidationTests, formatDiagnostic, assertValidAIRequest } from './troubleshooting-helper.js';
+// Export object types library
+export { OBJECT_TYPES_LIBRARY, getObjectType, getObjectTypesForAgent } from './object-types-library.js';
+// Re-export outputs library integration functions
+export { initializeObjectTypesLibrary, getObjectTypesLibrary, resetObjectTypesLibrary } from './object-types-library-integration.js';
+// Re-export outputs library types and utilities for convenience
+// Note: Since we use dynamic imports for the outputs library, these types may not be available
+// at compile time if the package isn't installed. Users can import directly from
+// @x12i/outputs-library if they need these types or utilities.
+//
+// Recommended: Import types and utilities directly from @x12i/outputs-library:
+//   import type { ClassificationOutput } from '@x12i/outputs-library/types';
+//   import { ResponseParser } from '@x12i/outputs-library/parsers';
+//   import type { ObjectTypesLibrary, FlexMdSupport } from '@x12i/outputs-library';
+//
+// The gateway integrates with the outputs library internally via dynamic imports,
+// so these re-exports are optional and mainly for convenience.
+//
+// For outputs-library v3.3.1+ with flex-md support:
+//   - ObjectTypesLibrary class with flex-md methods (getFlexMdTemplate, getFlexMdFormatSpec, etc.)
+//   - FlexMdSupport type for object type definitions
+//   - All flex-md methods are available on the library instance returned by getObjectTypesLibrary()

package/dist/instruction-errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Errors for instruction / prompt template and instructions-block resolution.
+ */
+export declare class InstructionNotFoundError extends Error {
+    key: string;
+    backend: string;
+    originalKey: string;
+    constructor(key: string, backend: string, message: string, originalKey: string);
+}
+export declare class InstructionBackendError extends Error {
+    key: string;
+    backend: string;
+    isRetryable: boolean;
+    originalError?: Error | undefined;
+    constructor(key: string, backend: string, message: string, isRetryable: boolean, originalError?: Error | undefined);
+}

package/dist/instruction-errors.js

@@ -0,0 +1,29 @@
+/**
+ * Errors for instruction / prompt template and instructions-block resolution.
+ */
+export class InstructionNotFoundError extends Error {
+    key;
+    backend;
+    originalKey;
+    constructor(key, backend, message, originalKey) {
+        super(message);
+        this.key = key;
+        this.backend = backend;
+        this.originalKey = originalKey;
+        this.name = 'InstructionNotFoundError';
+    }
+}
+export class InstructionBackendError extends Error {
+    key;
+    backend;
+    isRetryable;
+    originalError;
+    constructor(key, backend, message, isRetryable, originalError) {
+        super(message);
+        this.key = key;
+        this.backend = backend;
+        this.isRetryable = isRetryable;
+        this.originalError = originalError;
+        this.name = 'InstructionBackendError';
+    }
+}