@x12i/ai-gateway 7.9.1

package/dist-cjs/flex-md-loader.d.ts

@@ -0,0 +1,109 @@
+/**
+ * @x12i/flex-md Loader
+ *
+ * Handles ES Module loading and provides unified API for flex-md operations.
+ * @x12i/flex-md is an ES Module, so we use dynamic import() instead of require().
+ *
+ * Features:
+ * - extractJsonFromFlexMd: Extract and parse JSON from flex-md content
+ * - buildDynamicInstructions: Build output format instructions from schema objects (3.1+)
+ * - Embedded nx-md-parser: flex-md 4.x includes nx-md-parser functionality (no separate package needed)
+ * - Utilizes latest flex-md 4.x APIs: extractFromMarkdown, transformWithOfs, processResponseMarkdown
+ * - Memory/caching: flex-md 4.x functions may utilize internal memory/caching for performance
+ * - Native output format support: Extracts and uses flex-md native output formats from instructions
+ *   based on compliance level when no explicit format is provided
+ */
+/**
+ * Load flex-md module (ES Module) asynchronously
+ * Caches the result to avoid multiple imports
+ */
+export declare function loadFlexMd(): Promise<any>;
+/**
+ * Extract and parse JSON from flex-md content (unstructured parsing only)
+ * Uses flex-md 4.2.0 APIs with latest features for unstructured markdown conversion
+ *
+ * ARCHITECTURE: This function only handles unstructured parsing at ai-gateway layer
+ * Schema-driven parsing happens at skills layer with nx-md-parser
+ *
+ * Supports flex-md native output formats from instructions:
+ * - Extracts flex-md output format from instructions when provided
+ * - Uses the extracted format based on compliance level for parsing
+ * - Falls back to simple markdown parsing when flex-md is unavailable
+ *
+ * @param content - The markdown content to parse (unstructured)
+ * @param options - Optional flex-md options:
+ *   - instructions: Instruction text to guide unstructured parsing
+ *   - complianceLevel: Compliance level ('L0' | 'L1' | 'L2' | 'L3') for format extraction
+ *   - spec: Pre-parsed flex-md output format spec
+ *   - Other flex-md options
+ * @returns Parsed JSON object and method used, or null if parsing fails
+ */
+export declare function extractJsonFromFlexMd(content: string): Promise<{
+    json: any;
+    method: string;
+} | null>;
+/**
+ * Check if flex-md module is available
+ */
+export declare function isFlexMdAvailable(): boolean;
+/**
+ * Get maxTokens for a model from flex-md if available
+ * Tries various flex-md APIs to get model information and maxTokens
+ *
+ * @param provider - Provider name (e.g., 'openai', 'anthropic')
+ * @param model - Model name (e.g., 'gpt-4', 'claude-3-opus')
+ * @returns maxTokens if found, null otherwise
+ */
+export declare function getModelMaxTokensFromFlexMd(provider: string, model: string): Promise<number | null>;
+/**
+ * Get flex-md module directly (must call loadFlexMd() first)
+ */
+export declare function getFlexMdModule(): any;
+export declare function buildDynamicInstructions(schemaObject: Record<string, any> | any, options?: {
+    title?: string;
+    description?: string;
+    includeExamples?: boolean;
+}): Promise<string | null>;
+/**
+ * Enrich instructions with flex-md compliance guidance (flex-md 3.0+ feature)
+ * Adds appropriate flex-md format instructions based on strictness level
+ *
+ * @param instructions - Base instructions text
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Enriched instructions with flex-md guidance
+ */
+export declare function enrichInstructionsWithFlexMd(instructions: string, strictnessLevel?: 'L0' | 'L1' | 'L2' | 'L3'): Promise<string>;
+/**
+ * Get strictness defaults for a compliance level (flex-md 3.0+ feature)
+ * Returns configuration object for the specified compliance level
+ *
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Configuration object with level-specific defaults
+ */
+export declare function getStrictnessDefaults(strictnessLevel?: 'L0' | 'L1' | 'L2' | 'L3'): Promise<Record<string, any> | null>;
+/**
+ * Enforce flex-md format in instructions (flex-md 3.0+ feature)
+ * Adds enforcement rules based on output format spec and strictness level
+ *
+ * @param instructions - Base instructions text
+ * @param outputFormatSpec - Output format specification (optional)
+ * @param strictnessLevel - Compliance level ('L0' | 'L1' | 'L2' | 'L3')
+ * @returns Instructions with flex-md enforcement rules
+ */
+export declare function enforceFlexMdFormat(instructions: string, outputFormatSpec?: any, strictnessLevel?: 'L0' | 'L1' | 'L2' | 'L3'): Promise<string>;
+/**
+ * Check if instructions meet a specific flex-md compliance level
+ *
+ * @param instructions - Instructions text to check
+ * @param complianceLevel - Required compliance level
+ * @returns true if instructions meet the compliance level
+ */
+export declare function hasFlexMdContract(instructions: string, complianceLevel?: 'L0' | 'L1' | 'L2' | 'L3'): Promise<boolean>;
+/**
+ * Detect the actual compliance level that instructions meet
+ * Checks from highest (L3) to lowest (L0) to find the highest level met
+ *
+ * @param instructions - Instructions text to check
+ * @returns The highest compliance level met ('L0' | 'L1' | 'L2' | 'L3' | null if none)
+ */
+export declare function detectComplianceLevel(instructions: string): Promise<'L0' | 'L1' | 'L2' | 'L3' | null>;

package/dist-cjs/gateway-config.cjs

@@ -0,0 +1,331 @@
+"use strict";
+/**
+ * Gateway Configuration Module
+ * Handles configuration loading and setup
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadConfig = loadConfig;
+exports.getFlexMdMinComplianceLevel = getFlexMdMinComplianceLevel;
+exports.setupRequestInterceptor = setupRequestInterceptor;
+exports.initializeGatewayComponents = initializeGatewayComponents;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const url_1 = require("url");
+/** Resolve current module directory across ESM/CJS builds. */
+function getModuleDir() {
+    if (typeof __dirname !== 'undefined') {
+        return __dirname;
+    }
+    try {
+        const getMetaUrl = new Function('return import.meta.url');
+        const metaUrl = getMetaUrl();
+        if (metaUrl && metaUrl.startsWith('file:')) {
+            return path.dirname((0, url_1.fileURLToPath)(metaUrl));
+        }
+    }
+    catch {
+        // Fall through to cwd
+    }
+    return process.cwd();
+}
+/** Resolve directory containing defaults/ with package-local precedence. */
+function getDefaultsDir() {
+    const moduleDir = getModuleDir();
+    const cwd = process.cwd();
+    const candidates = [
+        moduleDir,
+        path.resolve(moduleDir, '..'),
+        path.resolve(moduleDir, '../dist'),
+        path.resolve(moduleDir, '../dist-cjs'),
+        path.resolve(moduleDir, '../src'),
+        path.join(cwd, 'dist'),
+        path.join(cwd, 'dist-cjs'),
+        path.join(cwd, 'src'),
+    ];
+    for (const dir of candidates) {
+        const modelConfigPath = path.join(dir, 'defaults', 'model-config.json');
+        if (fs.existsSync(modelConfigPath)) {
+            return dir;
+        }
+    }
+    // Keep existing behavior as a last fallback.
+    return path.join(cwd, 'dist');
+}
+const ai_providers_router_1 = require("@x12i/ai-providers-router");
+const logger_factory_js_1 = require("./logger-factory.cjs");
+const activity_manager_js_1 = require("./activity-manager.cjs");
+const usage_tracker_js_1 = require("./usage-tracker.cjs");
+const template_render_merge_js_1 = require("./template-render-merge.cjs");
+const gateway_rate_limiter_js_1 = require("./gateway-rate-limiter.cjs");
+const gateway_rate_limiter_constants_js_1 = require("./gateway-rate-limiter-constants.cjs");
+/**
+ * Loads configuration from JSON files (model config and instructionsBlocks)
+ * Note: Called before logger is initialized, so no logging here
+ */
+function loadConfig() {
+    const defaultModelConfig = {};
+    const defaultInstructionsBlocks = {};
+    let defaultTemplateRendering;
+    try {
+        const defaultsDir = getDefaultsDir();
+        const templateRenderingPath = path.join(defaultsDir, 'defaults', 'template-rendering.json');
+        if (fs.existsSync(templateRenderingPath)) {
+            const trContent = fs.readFileSync(templateRenderingPath, 'utf-8');
+            defaultTemplateRendering = JSON.parse(trContent);
+        }
+        // Load model config (includes rate limiting and retry defaults)
+        const modelConfigPath = path.join(defaultsDir, 'defaults', 'model-config.json');
+        if (fs.existsSync(modelConfigPath)) {
+            const content = fs.readFileSync(modelConfigPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            Object.assign(defaultModelConfig, parsed);
+        }
+        // Load instructionsBlocks
+        const instructionsBlocksPath = path.join(defaultsDir, 'defaults', 'instructions-blocks.json');
+        if (fs.existsSync(instructionsBlocksPath)) {
+            const content = fs.readFileSync(instructionsBlocksPath, 'utf-8');
+            const parsed = JSON.parse(content);
+            // Use Object.assign to merge, preserving nested structure
+            Object.assign(defaultInstructionsBlocks, parsed);
+            // Debug: Log what was loaded (only in development)
+            if (process.env.NODE_ENV !== 'production') {
+                console.log('Loaded instructions blocks:', {
+                    topLevelKeys: Object.keys(defaultInstructionsBlocks),
+                    hasOutput: 'output' in defaultInstructionsBlocks,
+                    outputKeys: 'output' in defaultInstructionsBlocks ? Object.keys(defaultInstructionsBlocks.output) : []
+                });
+            }
+        }
+        else {
+            // Optional file: fallback defaults below still keep the gateway functional.
+            if (process.env.NODE_ENV !== 'production') {
+                console.debug('Optional instructions blocks file not found at:', instructionsBlocksPath);
+            }
+        }
+    }
+    catch (error) {
+        // Can't log here as logger isn't initialized yet
+        // Error will be logged after logger initialization in constructor
+        console.warn('Failed to load defaults from JSON files:', error);
+    }
+    // Ensure critical blocks exist even if file loading failed
+    if (!defaultInstructionsBlocks['outputObjectPrefix']) {
+        defaultInstructionsBlocks['outputObjectPrefix'] = "Reply in Markdown. Return your entire answer inside a single ```markdown fenced block and nothing else. The content must conform to the schema provided below. If no items are found, return empty arrays (e.g., emails: []). Never ask for more input. Do not write conversational text. Do not write explanations. Do not ask questions.\n\n";
+    }
+    if (!defaultInstructionsBlocks['outputObjectTypesPrefix']) {
+        defaultInstructionsBlocks['outputObjectTypesPrefix'] = "Reply in Markdown. Return your entire answer inside a single ```markdown fenced block and nothing else. Select ONE of the following object types based on the input. The content must conform to the chosen schema. Do not write conversational text. Do not write explanations.\n\n";
+    }
+    return { defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering };
+}
+/**
+ * Gets the minimum flex-md compliance level from environment variable
+ * Defaults to 'L0' if not set or invalid
+ */
+function getFlexMdMinComplianceLevel() {
+    const envValue = process.env.FLEX_MD_MIN_COMPLIANCE_LEVEL;
+    if (envValue === 'L0' || envValue === 'L1' || envValue === 'L2' || envValue === 'L3') {
+        return envValue;
+    }
+    return 'L0'; // Default: allow anything
+}
+/**
+ * Sets up request interceptor for jobId propagation and config cleanup
+ */
+function setupRequestInterceptor(router, logger) {
+    logger.debug('Setting up request interceptor for jobId propagation and config cleanup');
+    router.addRequestInterceptor(async (request, provider) => {
+        // Propagate jobId to request metadata
+        if (request.jobId) {
+            logger.verbose('Propagating jobId to request metadata', {
+                jobId: request.jobId,
+                provider: provider?.getProviderName?.() || 'unknown'
+            });
+            if (!request.config) {
+                request.config = {};
+            }
+            if (!request.config.metadata) {
+                request.config.metadata = {};
+            }
+            request.config.metadata.jobId = request.jobId;
+        }
+        // Remove 'provider' from config - router uses it for routing but providers don't accept it
+        // Router reads config.provider to determine which provider to call, but then passes
+        // the entire config to the provider, which rejects 'provider' as invalid
+        if (request.config && 'provider' in request.config) {
+            logger.debug('Removing provider from config before passing to provider', {
+                provider: request.config.provider
+            });
+            const { provider: _, ...cleanConfig } = request.config;
+            request.config = cleanConfig;
+        }
+        return request;
+    });
+    logger.debug('Request interceptor configured');
+}
+/**
+ * Initializes gateway components
+ */
+function initializeGatewayComponents(config, defaultModelConfig, defaultInstructionsBlocks, defaultTemplateRendering) {
+    // Initialize logger FIRST (before other components that might need it)
+    const logger = (0, logger_factory_js_1.createGatewayLogger)({
+        enableLogging: config.enableLogging ?? true,
+        packageName: config.packageName,
+        customLogger: config.logger
+    });
+    // Now that logger is initialized, log the defaults loading
+    logger.verbose('Gateway initializing', {
+        defaultEngine: config.defaultEngine,
+        hasDefaultInstructionsBlocks: Object.keys(defaultInstructionsBlocks).length > 0
+    });
+    // Activity tracking is handled by Activix internally.
+    // Initialize router - this is the ONLY way to access providers
+    // RouterConfig properties are inherited from RouterConfig interface
+    const routerConfig = {};
+    const defaultTarget = config.defaultTarget;
+    if (defaultTarget) {
+        routerConfig.defaultTarget = defaultTarget;
+    }
+    else if (config.defaultProvider !== undefined) {
+        routerConfig.defaultProvider = config.defaultProvider;
+    }
+    else if (config.defaultEngine !== undefined) {
+        routerConfig.defaultProvider = config.defaultEngine;
+    }
+    const fallbackChain = config.fallbackChain;
+    if (fallbackChain) {
+        routerConfig.fallbackChain = fallbackChain;
+    }
+    else if (config.fallbackChain !== undefined) {
+        routerConfig.fallbackChain = config.fallbackChain;
+    }
+    if (config.autoDiscover !== undefined)
+        routerConfig.autoDiscover = config.autoDiscover;
+    if (config.usageTracker !== undefined)
+        routerConfig.usageTracker = config.usageTracker;
+    // OpenRouter: enable when key is set and not explicitly disabled (so consumers get a working default without registering providers).
+    // Prefer explicit config from consumer (e.g. ai-skills) to avoid env-loading timing; fall back to process.env.
+    const explicitOpenRouterKey = config.openrouter?.apiKey;
+    const isExplicitKey = typeof explicitOpenRouterKey === 'string' && !explicitOpenRouterKey.startsWith('ENV.');
+    const openRouterKey = isExplicitKey ? explicitOpenRouterKey : (process.env.OPEN_ROUTER_KEY ?? process.env.OPENROUTER_API_KEY);
+    const useOpenRouter = config.openRouter?.enabled !== undefined ? config.openRouter?.enabled : process.env.USE_OPENROUTER;
+    if (openRouterKey && useOpenRouter !== false && useOpenRouter !== 'false') {
+        routerConfig.openRouter = { enabled: true };
+        routerConfig.openrouter = { apiKey: openRouterKey };
+        routerConfig.defaultMode = 'openrouter';
+    }
+    const router = new ai_providers_router_1.LLMProviderRouter(routerConfig);
+    // Set up BETWEEN-CALLS rate limiting as a request interceptor (applies to all provider calls)
+    // This ensures rate limiting works even when router is used directly without gateway
+    // Hidden in the flow - automatic and transparent
+    // 
+    // NOTE: This is for BETWEEN-CALLS rate limiting (smart, tracks last call time).
+    // Retry delays are handled separately in gateway-retry.ts (simple sleep, not smart).
+    const rateLimitConfig = config.rateLimit;
+    // Get defaults from JSON config, fallback to constants
+    const jsonRateLimitConfig = defaultModelConfig.rateLimit || {};
+    const rateLimitEnabled = rateLimitConfig?.enabled ?? jsonRateLimitConfig.enabled ?? gateway_rate_limiter_constants_js_1.DEFAULT_RATE_LIMIT_ENABLED;
+    if (rateLimitEnabled) {
+        // Priority: explicit config > JSON defaults > constants
+        const defaultMinIntervalMs = rateLimitConfig?.defaultMinIntervalMs
+            ?? jsonRateLimitConfig.defaultMinIntervalMs
+            ?? gateway_rate_limiter_constants_js_1.DEFAULT_RATE_LIMIT_MIN_INTERVAL_MS;
+        const providerIntervals = rateLimitConfig?.providerIntervals;
+        const rateLimiter = new gateway_rate_limiter_js_1.GatewayRateLimiter(defaultMinIntervalMs, providerIntervals, logger);
+        // Add request interceptor for BETWEEN-CALLS rate limiting (hidden in the flow)
+        router.addRequestInterceptor(async (request, provider) => {
+            // Get provider name
+            const providerName = typeof provider?.getProviderName === 'function'
+                ? provider.getProviderName()
+                : 'global';
+            // Smart rate limiting: wait only if necessary based on last call time
+            // This is for BETWEEN-CALLS, not retries (retries use simple sleep in gateway-retry.ts)
+            await rateLimiter.waitIfNeeded(providerName);
+            // Return request unchanged (interceptor can modify request, but we just need to wait)
+            return request;
+        });
+        // Add response interceptor to record call completion
+        // Note: Type assertion needed due to ResponseInterceptor type definition mismatch
+        router.addResponseInterceptor((async (response, request, provider) => {
+            // Get provider name
+            const providerName = typeof provider?.getProviderName === 'function'
+                ? provider.getProviderName()
+                : 'global';
+            // Record the call time after completion (for smart between-calls rate limiting)
+            rateLimiter.recordCall(providerName);
+            // Return response unchanged
+            return response;
+        }));
+        logger.debug('Between-calls rate limiting configured as router interceptor', {
+            defaultMinIntervalMs,
+            providerIntervals: providerIntervals ? Object.keys(providerIntervals).length : 0,
+            enabled: true,
+            note: 'Smart rate limiting (between-calls only). Retry delays handled separately (simple sleep).'
+        });
+    }
+    else {
+        logger.debug('Rate limiting disabled');
+    }
+    // Initialize usage tracking
+    const usageTracker = new usage_tracker_js_1.UsageTracker({
+        enableUsageTracking: config.enableUsageTracking ?? true,
+        usageTier: config.usageTier,
+        logger
+    });
+    // Initialize activity tracking
+    const activityManager = new activity_manager_js_1.ActivityManager({
+        enableActivityTracking: config.enableActivityTracking ?? true,
+        customTracker: config.activityTracker,
+        logger
+    });
+    const templateRendering = (0, template_render_merge_js_1.mergeTemplateRenderOptions)(defaultTemplateRendering, config.templateRendering);
+    const instructionsBlockOverrides = {
+        ...(config.instructionsBlocks ?? {})
+    };
+    // Initialize message builder config - for direct message construction
+    const messageBuilderConfig = {
+        defaultInstructionsBlocks,
+        instructionsBlockOverrides,
+        logger,
+        templateRendering
+    };
+    return {
+        logger,
+        router,
+        activityManager,
+        usageTracker,
+        messageBuilderConfig
+    };
+}

package/dist-cjs/gateway-config.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Gateway Configuration Module
+ * Handles configuration loading and setup
+ */
+import type { GatewayConfig } from './types.js';
+import type { Logxer } from '@x12i/logxer';
+import { LLMProviderRouter } from '@x12i/ai-providers-router';
+import { ActivityManager } from './activity-manager.js';
+import { UsageTracker } from './usage-tracker.js';
+import type { MessageBuilderConfig } from './message-builder.js';
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+export interface GatewayConfigContext {
+    defaultModelConfig: Record<string, unknown>;
+    defaultInstructionsBlocks: Record<string, any>;
+    config: GatewayConfig;
+    logger: Logxer;
+    router: LLMProviderRouter;
+    activityManager: ActivityManager;
+    usageTracker: UsageTracker;
+    messageBuilderConfig: MessageBuilderConfig;
+}
+/**
+ * Loads configuration from JSON files (model config and instructionsBlocks)
+ * Note: Called before logger is initialized, so no logging here
+ */
+export declare function loadConfig(): {
+    defaultModelConfig: Record<string, unknown>;
+    defaultInstructionsBlocks: Record<string, any>;
+    defaultTemplateRendering?: TemplateRenderOptions;
+};
+/**
+ * Gets the minimum flex-md compliance level from environment variable
+ * Defaults to 'L0' if not set or invalid
+ */
+export declare function getFlexMdMinComplianceLevel(): 'L0' | 'L1' | 'L2' | 'L3';
+/**
+ * Sets up request interceptor for jobId propagation and config cleanup
+ */
+export declare function setupRequestInterceptor(router: LLMProviderRouter, logger: Logxer): void;
+/**
+ * Initializes gateway components
+ */
+export declare function initializeGatewayComponents(config: GatewayConfig, defaultModelConfig: Record<string, unknown>, defaultInstructionsBlocks: Record<string, any>, defaultTemplateRendering?: TemplateRenderOptions): {
+    logger: Logxer;
+    router: LLMProviderRouter;
+    activityManager: ActivityManager;
+    usageTracker: UsageTracker;
+    messageBuilderConfig: MessageBuilderConfig;
+};