@x12i/ai-gateway 7.9.1

package/dist-cjs/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-cjs/instruction-optimizer.cjs

@@ -0,0 +1,299 @@
+"use strict";
+/**
+ * Instruction Optimizer Feature
+ *
+ * Uses AI to analyze and fix poorly-written instructions.
+ * This is a meta-feature that uses the AI Gateway (via router) to improve AI instructions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.optimizeInstructions = optimizeInstructions;
+exports.getFixedInstructions = getFixedInstructions;
+exports.getChangesSummary = getChangesSummary;
+exports.validateTokenPreservation = validateTokenPreservation;
+/**
+ * The meta-instructions used to fix other instructions
+ * Loaded from instructions-audit.md
+ */
+const INSTRUCTION_OPTIMIZER_INSTRUCTIONS = `You are an AI instruction optimizer. Your task is to analyze and fix poorly-written AI instructions.
+
+You will receive instructions that may have issues like:
+- Vague or unclear task descriptions
+- Missing output format specifications
+- Contradictory requirements
+- Poor structure or organization
+- Missing critical rules for JSON-only responses
+
+Your response must be ONLY a valid JSON object with this exact structure:
+
+{
+  "analysis": {
+    "problems_found": [
+      "<string> Description of each problem identified"
+    ],
+    "missing_elements": [
+      "<string> What critical elements are missing"
+    ],
+    "clarity_score": <number 1-10> How clear the original instructions were
+  },
+  "fixed_instructions": {
+    "complete_text": "<string> The complete fixed instructions ready to use as-is. This should be a fully self-contained instruction set that needs NO composition or assembly. Preserve all {{tokens}} exactly as they appear.",
+    "breakdown": {
+      "core_task": "<string> The main task/objective extracted",
+      "task_description": "<string> What the AI should do",
+      "output_requirements": "<string> Required output format and structure",
+      "constraints": [
+        "<string> Each constraint or rule"
+      ],
+      "schemas": [
+        {
+          "type": "<string> Schema type/name",
+          "schema": <object> The actual schema object,
+          "when_to_use": "<string> When this schema applies"
+        }
+      ],
+      "tokens_preserved": [
+        "<string> List of all {{tokens}} found and preserved"
+      ]
+    }
+  },
+  "changes_made": [
+    {
+      "change_type": "<string> Type of change (clarification|addition|restructure|correction)",
+      "original": "<string> What the original said (or 'missing' if added)",
+      "fixed": "<string> What it was changed to",
+      "reason": "<string> Why this change was necessary"
+    }
+  ],
+  "quality_improvements": {
+    "before_score": <number 1-10>,
+    "after_score": <number 1-10>,
+    "summary": "<string> Brief summary of overall improvements"
+  }
+}
+
+CRITICAL RULES:
+- Your ENTIRE response must be parseable JSON
+- Do NOT write conversational text outside the JSON
+- Response must START with { and END with }
+- The "complete_text" field must contain fully usable instructions that need NO further assembly
+- Preserve ALL template tokens exactly: {{taskDescription}}, {{input}}, {{role}}, etc.
+- Do NOT resolve or replace tokens - keep them as placeholders
+- If instructions mention JSON output, ensure complete JSON enforcement rules are included
+- If schemas are mentioned, extract and structure them properly
+
+INSTRUCTION FIXING GUIDELINES:
+
+1. CLARITY: Make task objectives crystal clear
+2. COMPLETENESS: Add missing critical elements (output format, constraints, error handling)
+3. STRUCTURE: Organize logically (task → requirements → constraints → schemas)
+4. JSON ENFORCEMENT: If JSON output is required, add strict enforcement rules:
+   - "Your ENTIRE response must be parseable JSON"
+   - "Do NOT write conversational text"
+   - "Response must START with { and END with }"
+   - "FORBIDDEN: 'I'm sorry', 'Please provide', 'Sure!', etc."
+5. TOKENS: Preserve all {{token}} placeholders exactly as written
+6. SCHEMAS: Extract any schema definitions into proper structure
+7. EXAMPLES: Add examples if they would improve clarity
+
+If the instructions are already well-written, explain that in the analysis and make only minor improvements.`;
+/**
+ * Optimizes AI instructions by analyzing and fixing common issues
+ *
+ * This is a meta-feature that uses AI (via the gateway router) to improve AI instructions.
+ * It takes poorly-written instructions and returns:
+ * 1. Analysis of problems
+ * 2. Fixed, production-ready instructions
+ * 3. Detailed breakdown of components
+ * 4. List of changes made and why
+ *
+ * @param gateway - AI Gateway instance (uses router, not direct provider calls)
+ * @param originalInstructions - The instructions to optimize
+ * @param options - Optimization options
+ * @returns Optimization result with fixed instructions and analysis
+ */
+async function optimizeInstructions(gateway, originalInstructions, options = {}) {
+    // Get internal system action config (instruction optimization)
+    const internalConfig = gateway.config?.internalSystemActions?.instructionOptimization;
+    const defaultEngine = gateway.config?.defaultEngine || 'openai';
+    const defaultModel = internalConfig?.model || 'gpt-4o';
+    const defaultProvider = internalConfig?.engine || defaultEngine;
+    const { agentId = 'instruction-optimizer', targetUseCase, enforceJsonOutput, model = defaultModel, // Use internal config default if not provided
+    provider = defaultProvider, // Use internal config default if not provided
+    includeDetailedExplanations = true } = options;
+    // Build context based on target use case
+    let additionalContext = '';
+    if (targetUseCase === 'json-extraction') {
+        additionalContext = '\n\nTarget Use Case: These instructions will be used for JSON extraction tasks. Ensure strict JSON output enforcement and empty result handling are included.';
+    }
+    else if (targetUseCase === 'chat') {
+        additionalContext = '\n\nTarget Use Case: These instructions will be used for conversational AI. Ensure natural, helpful responses are encouraged while maintaining clarity.';
+    }
+    else if (targetUseCase === 'reasoning') {
+        additionalContext = '\n\nTarget Use Case: These instructions will be used for reasoning tasks. Ensure step-by-step thinking is encouraged and output includes reasoning process.';
+    }
+    if (enforceJsonOutput) {
+        additionalContext += '\n\nIMPORTANT: The fixed instructions MUST include strict JSON-only output enforcement rules.';
+    }
+    // Create the optimization request - uses gateway.invoke() which goes through router
+    // Use internal system action config for temperature and maxTokens if available
+    const optimizationRequest = {
+        jobId: `optimize-instructions-${Date.now()}`,
+        agentId,
+        instructions: INSTRUCTION_OPTIMIZER_INSTRUCTIONS + additionalContext,
+        input: originalInstructions,
+        config: {
+            model,
+            provider,
+            temperature: internalConfig?.temperature ?? 0.3, // Use internal config or default
+            maxTokens: internalConfig?.maxTokens ?? 4000 // Use internal config or default
+        },
+        // Use JSON output type to ensure we get structured response
+        primaryObjectType: {
+            type: 'instruction-optimization',
+            schema: {
+                analysis: {
+                    type: 'object',
+                    properties: {
+                        problems_found: {
+                            type: 'array',
+                            items: { type: 'string' }
+                        },
+                        missing_elements: {
+                            type: 'array',
+                            items: { type: 'string' }
+                        },
+                        clarity_score: { type: 'number' }
+                    },
+                    required: ['problems_found', 'missing_elements', 'clarity_score']
+                },
+                fixed_instructions: {
+                    type: 'object',
+                    properties: {
+                        complete_text: { type: 'string' },
+                        breakdown: {
+                            type: 'object',
+                            properties: {
+                                core_task: { type: 'string' },
+                                task_description: { type: 'string' },
+                                output_requirements: { type: 'string' },
+                                constraints: {
+                                    type: 'array',
+                                    items: { type: 'string' }
+                                },
+                                schemas: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            type: { type: 'string' },
+                                            schema: { type: 'object' },
+                                            when_to_use: { type: 'string' }
+                                        }
+                                    }
+                                },
+                                tokens_preserved: {
+                                    type: 'array',
+                                    items: { type: 'string' }
+                                }
+                            },
+                            required: ['core_task', 'task_description', 'output_requirements', 'constraints', 'schemas', 'tokens_preserved']
+                        }
+                    },
+                    required: ['complete_text', 'breakdown']
+                },
+                changes_made: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            change_type: { type: 'string' },
+                            original: { type: 'string' },
+                            fixed: { type: 'string' },
+                            reason: { type: 'string' }
+                        },
+                        required: ['change_type', 'original', 'fixed', 'reason']
+                    }
+                },
+                quality_improvements: {
+                    type: 'object',
+                    properties: {
+                        before_score: { type: 'number' },
+                        after_score: { type: 'number' },
+                        summary: { type: 'string' }
+                    },
+                    required: ['before_score', 'after_score', 'summary']
+                }
+            },
+            whenToUse: 'Always use this schema for instruction optimization results',
+            description: 'Result of instruction optimization with analysis and fixes'
+        }
+    };
+    // Call the gateway - this goes through the router, not direct provider calls
+    const response = await gateway.invoke(optimizationRequest);
+    // Check for errors
+    if (!response.parsedContent) {
+        throw new Error(`Instruction optimization failed: Response missing parsedContent. Content: ${response.content?.substring(0, 200)}`);
+    }
+    // Parse the result
+    const result = response.parsedContent;
+    if (!result || !result.fixed_instructions || !result.fixed_instructions.complete_text) {
+        throw new Error('Invalid optimization result: missing fixed instructions');
+    }
+    return result;
+}
+/**
+ * Utility: Extract only the fixed instructions text
+ *
+ * @param result - Optimization result
+ * @returns Just the complete fixed instructions text
+ */
+function getFixedInstructions(result) {
+    return result.fixed_instructions.complete_text;
+}
+/**
+ * Utility: Get a summary of changes made
+ *
+ * @param result - Optimization result
+ * @returns Human-readable summary of changes
+ */
+function getChangesSummary(result) {
+    const summary = [
+        `Quality improved from ${result.quality_improvements.before_score}/10 to ${result.quality_improvements.after_score}/10`,
+        `\n${result.quality_improvements.summary}`,
+        `\nProblems fixed: ${result.analysis.problems_found.length}`,
+        `Missing elements added: ${result.analysis.missing_elements.length}`,
+        `Total changes: ${result.changes_made.length}`
+    ];
+    if (result.fixed_instructions.breakdown.tokens_preserved.length > 0) {
+        summary.push(`\nTokens preserved: ${result.fixed_instructions.breakdown.tokens_preserved.join(', ')}`);
+    }
+    return summary.join('\n');
+}
+/**
+ * Utility: Validate that fixed instructions preserve all tokens
+ *
+ * @param originalInstructions - Original instructions
+ * @param result - Optimization result
+ * @returns Object with validation status and any missing tokens
+ */
+function validateTokenPreservation(originalInstructions, result) {
+    // Extract tokens from original (matches {{anything}})
+    const tokenRegex = /\{\{([^}]+)\}\}/g;
+    const originalTokens = new Set();
+    let match;
+    while ((match = tokenRegex.exec(originalInstructions)) !== null) {
+        originalTokens.add(match[0]); // Store full token with braces
+    }
+    // Check if all tokens are preserved in fixed instructions
+    const fixedText = result.fixed_instructions.complete_text;
+    const missingTokens = [];
+    for (const token of originalTokens) {
+        if (!fixedText.includes(token)) {
+            missingTokens.push(token);
+        }
+    }
+    return {
+        valid: missingTokens.length === 0,
+        missingTokens
+    };
+}

package/dist-cjs/instruction-optimizer.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Instruction Optimizer Feature
+ *
+ * Uses AI to analyze and fix poorly-written instructions.
+ * This is a meta-feature that uses the AI Gateway (via router) to improve AI instructions.
+ */
+import type { AIGateway } from './gateway.js';
+/**
+ * Result from instruction optimization
+ */
+export interface InstructionOptimizationResult {
+    analysis: {
+        problems_found: string[];
+        missing_elements: string[];
+        clarity_score: number;
+    };
+    fixed_instructions: {
+        complete_text: string;
+        breakdown: {
+            core_task: string;
+            task_description: string;
+            output_requirements: string;
+            constraints: string[];
+            schemas: Array<{
+                type: string;
+                schema: Record<string, unknown>;
+                when_to_use: string;
+            }>;
+            tokens_preserved: string[];
+        };
+    };
+    changes_made: Array<{
+        change_type: string;
+        original: string;
+        fixed: string;
+        reason: string;
+    }>;
+    quality_improvements: {
+        before_score: number;
+        after_score: number;
+        summary: string;
+    };
+}
+/**
+ * Options for instruction optimization
+ */
+export interface OptimizeInstructionsOptions {
+    /**
+     * Agent ID for the optimization request
+     */
+    agentId?: string;
+    /**
+     * Target use case (helps optimizer know what to prioritize)
+     */
+    targetUseCase?: 'json-extraction' | 'chat' | 'reasoning' | 'general';
+    /**
+     * Whether to enforce JSON output in fixed instructions
+     */
+    enforceJsonOutput?: boolean;
+    /**
+     * Model to use for optimization (default: gpt-4o)
+     */
+    model?: string;
+    /**
+     * Provider to use (default: openai)
+     */
+    provider?: string;
+    /**
+     * Whether to include detailed explanations
+     */
+    includeDetailedExplanations?: boolean;
+}
+/**
+ * Optimizes AI instructions by analyzing and fixing common issues
+ *
+ * This is a meta-feature that uses AI (via the gateway router) to improve AI instructions.
+ * It takes poorly-written instructions and returns:
+ * 1. Analysis of problems
+ * 2. Fixed, production-ready instructions
+ * 3. Detailed breakdown of components
+ * 4. List of changes made and why
+ *
+ * @param gateway - AI Gateway instance (uses router, not direct provider calls)
+ * @param originalInstructions - The instructions to optimize
+ * @param options - Optimization options
+ * @returns Optimization result with fixed instructions and analysis
+ */
+export declare function optimizeInstructions(gateway: AIGateway, originalInstructions: string, options?: OptimizeInstructionsOptions): Promise<InstructionOptimizationResult>;
+/**
+ * Utility: Extract only the fixed instructions text
+ *
+ * @param result - Optimization result
+ * @returns Just the complete fixed instructions text
+ */
+export declare function getFixedInstructions(result: InstructionOptimizationResult): string;
+/**
+ * Utility: Get a summary of changes made
+ *
+ * @param result - Optimization result
+ * @returns Human-readable summary of changes
+ */
+export declare function getChangesSummary(result: InstructionOptimizationResult): string;
+/**
+ * Utility: Validate that fixed instructions preserve all tokens
+ *
+ * @param originalInstructions - Original instructions
+ * @param result - Optimization result
+ * @returns Object with validation status and any missing tokens
+ */
+export declare function validateTokenPreservation(originalInstructions: string, result: InstructionOptimizationResult): {
+    valid: boolean;
+    missingTokens: string[];
+};

package/dist-cjs/instructions-parser.cjs

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * Instructions Parser Module
+ *
+ * Handles template rendering for instruction content using Rendrix (@x12i/rendrix).
+ * Separated from instruction resolution to keep concerns clean.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderInstructionTemplate = renderInstructionTemplate;
+exports.hasTemplateVariables = hasTemplateVariables;
+exports.extractTemplateVariables = extractTemplateVariables;
+const template_parser_js_1 = require("./template-parser.cjs");
+/**
+ * Renders instruction templates with variables using Rendrix (@x12i/rendrix)
+ */
+async function renderInstructionTemplate(template, variables = {}, templateRenderOptions) {
+    const startTime = Date.now();
+    // Extract memory contexts for Rendrix
+    // parseTemplate expects: (template, workingMemory, shortTermMemory?, experienceMemory?, knowledgeMemory?)
+    const workingMemory = variables.workingMemory || {};
+    const shortTermMemory = variables.shortTermMemory || {};
+    const experienceMemory = variables.experienceMemory || {};
+    const knowledgeMemory = variables.knowledgeMemory || {};
+    // Render template using Rendrix
+    // Pass memory contexts as separate parameters, not as a combined object
+    const renderedText = await (0, template_parser_js_1.parseTemplate)(template, workingMemory, undefined, // taskConfig removed - no longer used
+    shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions);
+    // Combine all memory contexts for return value (for metadata)
+    const combinedVariables = {
+        ...variables,
+        workingMemory,
+        shortTermMemory,
+        experienceMemory,
+        knowledgeMemory
+    };
+    const renderTime = Date.now() - startTime;
+    return {
+        text: renderedText,
+        templateVariables: combinedVariables,
+        renderTime
+    };
+}
+/**
+ * Checks if a template contains variables that need rendering
+ */
+function hasTemplateVariables(template) {
+    // Check for double-brace variables like {{variable}}
+    return /\{\{[^}]+\}\}/g.test(template);
+}
+/**
+ * Extracts variable names from a template
+ */
+function extractTemplateVariables(template) {
+    const matches = template.match(/\{\{([^}]+)\}\}/g);
+    if (!matches)
+        return [];
+    return matches.map(match => {
+        // Remove {{ and }} and trim whitespace
+        return match.slice(2, -2).trim();
+    }).filter((value, index, array) => array.indexOf(value) === index); // Remove duplicates
+}

package/dist-cjs/instructions-parser.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Instructions Parser Module
+ *
+ * Handles template rendering for instruction content using Rendrix (@x12i/rendrix).
+ * Separated from instruction resolution to keep concerns clean.
+ */
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+export interface TemplateVariables {
+    workingMemory?: Record<string, any>;
+    shortTermMemory?: Record<string, any>;
+    experienceMemory?: Record<string, any>;
+    knowledgeMemory?: Record<string, any>;
+    [key: string]: any;
+}
+export interface RenderedInstruction {
+    text: string;
+    templateVariables: TemplateVariables;
+    renderTime: number;
+}
+/**
+ * Renders instruction templates with variables using Rendrix (@x12i/rendrix)
+ */
+export declare function renderInstructionTemplate(template: string, variables?: TemplateVariables, templateRenderOptions?: TemplateRenderOptions): Promise<RenderedInstruction>;
+/**
+ * Checks if a template contains variables that need rendering
+ */
+export declare function hasTemplateVariables(template: string): boolean;
+/**
+ * Extracts variable names from a template
+ */
+export declare function extractTemplateVariables(template: string): string[];

package/dist-cjs/logger-factory.cjs

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Logger Factory
+ *
+ * Creates and configures logxer instances for the gateway
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGatewayLogger = createGatewayLogger;
+const logxer_1 = require("@x12i/logxer");
+/**
+ * Creates a logger instance based on configuration
+ *
+ * @param config - Logger configuration
+ * @returns Configured logger or no-op logger if logging is disabled
+ */
+function createGatewayLogger(config) {
+    if (config.customLogger) {
+        return config.customLogger;
+    }
+    if (!config.enableLogging) {
+        return createNoOpLogger();
+    }
+    return (0, logxer_1.createLogxer)({
+        packageName: config.packageName || 'AI_GATEWAY',
+        envPrefix: config.packageName || 'AI_GATEWAY',
+        debugNamespace: 'ai-gateway'
+    }, {
+        logLevel: 'info',
+        logFormat: 'json'
+    });
+}
+function createNoOpLogger() {
+    const noop = () => { };
+    return {
+        verbose: noop,
+        debug: noop,
+        info: noop,
+        warn: noop,
+        error: noop,
+        success: noop,
+        isLevelEnabled: () => false,
+        getConfig: () => ({}),
+        shadow: {}
+    };
+}

package/dist-cjs/logger-factory.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Logger Factory
+ *
+ * Creates and configures logxer instances for the gateway
+ */
+import { type Logxer } from '@x12i/logxer';
+/**
+ * Creates a logger instance based on configuration
+ *
+ * @param config - Logger configuration
+ * @returns Configured logger or no-op logger if logging is disabled
+ */
+export declare function createGatewayLogger(config: {
+    enableLogging: boolean;
+    packageName?: string;
+    customLogger?: Logxer;
+}): Logxer;