@x12i/ai-gateway 7.9.1

package/dist/response-analyzer/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Type definitions for Response Analyzer
+ */
+/**
+ * Object type definition for matching against response objects
+ */
+export interface ObjectTypeDefinition {
+    /**
+     * Unique identifier for the type
+     */
+    id: string;
+    /**
+     * Human-readable name
+     */
+    name: string;
+    /**
+     * Properties that must be present for a match
+     */
+    requiredProperties: string[];
+    /**
+     * Properties that boost confidence if present
+     */
+    optionalProperties?: string[];
+    /**
+     * Priority weight (higher = more important)
+     * Used to break ties when confidence is equal
+     * @default 1
+     */
+    priority?: number;
+}
+/**
+ * Configuration for ResponseAnalyzer
+ */
+export interface ResponseAnalyzerConfig {
+    /**
+     * Object type definitions to match against
+     */
+    objectTypeDefinitions?: ObjectTypeDefinition[];
+    /**
+     * Enable format type detection for text responses
+     * @default true
+     */
+    enableFormatDetection?: boolean;
+    /**
+     * Minimum confidence threshold for object type matching
+     * Types below this threshold are filtered out
+     * @default 0.5
+     */
+    minConfidenceThreshold?: number;
+}
+/**
+ * Matched object type with confidence score
+ */
+export interface MatchedObjectType {
+    /**
+     * The matched type definition
+     */
+    type: ObjectTypeDefinition;
+    /**
+     * Confidence score (0-1)
+     */
+    confidence: number;
+}
+/**
+ * Detected format type with confidence score
+ */
+export interface DetectedFormatType {
+    /**
+     * Format type identifier
+     */
+    formatType: string;
+    /**
+     * Confidence score (0-1)
+     */
+    confidence: number;
+}
+/**
+ * Analysis result containing all detected information
+ */
+export interface AnalysisResult {
+    /**
+     * Content type classification
+     */
+    contentType: 'object' | 'text' | 'empty';
+    /**
+     * Best matching object type (highest confidence)
+     */
+    bestObjectType?: MatchedObjectType;
+    /**
+     * All matching object types (sorted by confidence)
+     */
+    allObjectTypes?: MatchedObjectType[];
+    /**
+     * Detected format type (for text responses)
+     */
+    formatType?: DetectedFormatType;
+}

package/dist/response-analyzer/types.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Response Analyzer
+ */
+export {};

package/dist/response-fallback-fixer.d.ts

@@ -0,0 +1,11 @@
+export type GatewayFallbackFixResult = {
+    fixed: true;
+    jsonText: string;
+    fixApplied: 'extract-fenced-json' | 'extract-balanced-json' | 'strip-to-first-json';
+    confidence: number;
+    warnings?: string[];
+} | {
+    fixed: false;
+    warnings?: string[];
+};
+export declare function tryFixGatewayResponseToJsonText(raw: string): GatewayFallbackFixResult;

package/dist/response-fallback-fixer.js

@@ -0,0 +1,123 @@
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function extractFirstFencedBlock(text) {
+    // Supports ```json ... ``` and ```markdown ... ``` (and unlabeled ``` ... ```)
+    const re = /```(?:json|markdown)?\s*\n?([\s\S]*?)\n?```/i;
+    const match = text.match(re);
+    return match?.[1]?.trim() || undefined;
+}
+function extractBalancedJsonSubstring(text) {
+    // Finds first balanced {...} or [...] substring while respecting JSON strings.
+    const s = text;
+    const startObj = s.indexOf('{');
+    const startArr = s.indexOf('[');
+    let start = -1;
+    let openChar = '';
+    let closeChar = '';
+    if (startObj === -1 && startArr === -1)
+        return undefined;
+    if (startObj !== -1 && (startArr === -1 || startObj < startArr)) {
+        start = startObj;
+        openChar = '{';
+        closeChar = '}';
+    }
+    else {
+        start = startArr;
+        openChar = '[';
+        closeChar = ']';
+    }
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let i = start; i < s.length; i++) {
+        const ch = s[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === '\\') {
+                escape = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === openChar)
+            depth++;
+        if (ch === closeChar)
+            depth--;
+        if (depth === 0) {
+            const candidate = s.slice(start, i + 1).trim();
+            return candidate.length > 0 ? candidate : undefined;
+        }
+    }
+    return undefined;
+}
+function stripToFirstJsonLike(text) {
+    const s = text.trim();
+    const firstBrace = s.indexOf('{');
+    const firstBracket = s.indexOf('[');
+    if (firstBrace === -1 && firstBracket === -1)
+        return undefined;
+    const start = firstBrace !== -1 && (firstBracket === -1 || firstBrace < firstBracket) ? firstBrace : firstBracket;
+    const stripped = s.slice(start).trim();
+    return stripped.length > 0 ? stripped : undefined;
+}
+export function tryFixGatewayResponseToJsonText(raw) {
+    const warnings = [];
+    const input = raw ?? '';
+    if (!input || !input.trim()) {
+        return { fixed: false, warnings: ['empty-input'] };
+    }
+    // 0) Already valid JSON
+    const trimmed = input.trim();
+    if (tryParseJson(trimmed) !== undefined) {
+        return {
+            fixed: true,
+            jsonText: trimmed,
+            fixApplied: 'strip-to-first-json',
+            confidence: 0.95,
+            warnings: ['input-already-valid-json']
+        };
+    }
+    // 1) Fenced block extraction
+    const fenced = extractFirstFencedBlock(input);
+    if (fenced) {
+        if (tryParseJson(fenced) !== undefined) {
+            return { fixed: true, jsonText: fenced, fixApplied: 'extract-fenced-json', confidence: 0.7 };
+        }
+        warnings.push('fenced-block-found-but-not-json');
+    }
+    // 2) Balanced substring extraction
+    const balanced = extractBalancedJsonSubstring(input);
+    if (balanced) {
+        if (tryParseJson(balanced) !== undefined) {
+            return { fixed: true, jsonText: balanced, fixApplied: 'extract-balanced-json', confidence: 0.55 };
+        }
+        warnings.push('balanced-json-substring-found-but-not-json');
+    }
+    // 3) Strip leading prose to first { or [
+    const stripped = stripToFirstJsonLike(input);
+    if (stripped) {
+        // It might still have trailing junk; try balanced extraction again on stripped first.
+        const strippedBalanced = extractBalancedJsonSubstring(stripped) ?? stripped;
+        if (tryParseJson(strippedBalanced) !== undefined) {
+            return { fixed: true, jsonText: strippedBalanced, fixApplied: 'strip-to-first-json', confidence: 0.4 };
+        }
+        warnings.push('stripped-to-first-jsonlike-but-not-json');
+    }
+    return { fixed: false, warnings: warnings.length ? warnings : undefined };
+}

package/dist/runtime-objects.d.ts

@@ -0,0 +1,52 @@
+import type { Logxer } from '@x12i/logxer';
+import type { Activix } from '@x12i/activix';
+export type ActivixQueryableClient = {
+    getJobActivities(input: {
+        jobId: string;
+        graphId?: string;
+        nodeId?: string;
+        limit?: number;
+    }): Promise<{
+        jobId: string;
+        graphRun?: unknown;
+        activities: unknown[];
+    }>;
+};
+export type LogxerQueryableClient = {
+    getJobLogs(input: {
+        jobId: string;
+        graphId?: string;
+        nodeId?: string;
+        limit?: number;
+    }): Promise<{
+        jobId: string;
+        lines: Array<{
+            ts?: number | string;
+            level?: 'debug' | 'info' | 'warn' | 'error';
+            scope?: string;
+            packageName?: string;
+            nodeId?: string;
+            message: string;
+            data?: unknown;
+        }>;
+    }>;
+};
+export type PackageRuntimeObjects = {
+    name: string;
+    activixClient?: ActivixQueryableClient;
+    logxerClient?: LogxerQueryableClient;
+};
+export type RuntimeObjects = {
+    lastJobId?: string;
+    activixClient?: ActivixQueryableClient;
+    logxerClient?: LogxerQueryableClient;
+    packagesRuntimeObjects: PackageRuntimeObjects[];
+};
+export type RuntimeObservabilityMode = 'debug' | 'prod';
+export declare let runtimeObjects: RuntimeObjects | undefined;
+export declare function setGatewayLastJobId(jobId: string | undefined): void;
+export declare function setGatewayRuntimeClients(input: {
+    activix?: Activix;
+    logger?: Logxer;
+}): void;
+export declare function getRuntimeObservabilityMode(): RuntimeObservabilityMode;

package/dist/runtime-objects.js

@@ -0,0 +1,46 @@
+export let runtimeObjects = createRuntimeObjectsForMode();
+export function setGatewayLastJobId(jobId) {
+    const objects = ensureRuntimeObjectsForCurrentMode();
+    if (!objects)
+        return;
+    objects.lastJobId = jobId;
+}
+export function setGatewayRuntimeClients(input) {
+    const objects = ensureRuntimeObjectsForCurrentMode();
+    if (!objects)
+        return;
+    objects.activixClient = input.activix ? asActivixQueryableClient(input.activix) : undefined;
+    objects.logxerClient = input.logger ? asLogxerQueryableClient(input.logger) : undefined;
+    objects.packagesRuntimeObjects = [];
+}
+export function getRuntimeObservabilityMode() {
+    const rawMode = process.env.mode ?? process.env.MODE;
+    return rawMode === 'prod' ? 'prod' : 'debug';
+}
+function ensureRuntimeObjectsForCurrentMode() {
+    if (getRuntimeObservabilityMode() === 'prod') {
+        runtimeObjects = undefined;
+        return undefined;
+    }
+    runtimeObjects ??= createRuntimeObjects();
+    return runtimeObjects;
+}
+function createRuntimeObjectsForMode() {
+    return getRuntimeObservabilityMode() === 'debug' ? createRuntimeObjects() : undefined;
+}
+function createRuntimeObjects() {
+    return {
+        lastJobId: undefined,
+        activixClient: undefined,
+        logxerClient: undefined,
+        packagesRuntimeObjects: []
+    };
+}
+function asActivixQueryableClient(activix) {
+    const candidate = activix;
+    return typeof candidate.getJobActivities === 'function' ? candidate : undefined;
+}
+function asLogxerQueryableClient(logger) {
+    const candidate = logger;
+    return typeof candidate.getJobLogs === 'function' ? candidate : undefined;
+}

package/dist/template-parser.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Template Parser
+ *
+ * Uses @x12i/rendrix (v4+) to parse templates with workingMemory.
+ * TemplateResolutionError from the parser is rethrown; other errors fall back to the raw template.
+ */
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+/**
+ * Task configuration type for template rendering
+ * @deprecated taskConfig is no longer used by Rendrix 3.0.0+
+ * Kept for backward compatibility only - will be ignored
+ */
+export interface TaskConfig {
+    includeThoughts?: boolean;
+}
+/**
+ * Short-term memory type - flexible key-value storage
+ */
+export interface ShortTermMemory {
+    [key: string]: string | number | boolean | object | object[];
+}
+/**
+ * Experience memory type - structured storage for learned experiences
+ */
+export interface ExperienceMemory {
+    knowHows?: object | object[] | string[] | string;
+    narratives?: object | object[] | string[] | string;
+    experiences?: object | object[] | string[] | string;
+    insights?: object | object[] | string[] | string;
+    learnings?: object | object[] | string[] | string;
+    lessons?: object | object[] | string[] | string;
+    frameworks?: object | object[] | string[] | string;
+    tools?: object | object[] | string[] | string;
+}
+/**
+ * Knowledge memory type - flexible key-value storage for reference data
+ */
+export interface KnowledgeMemory {
+    [key: string]: string | number | boolean | object | object[];
+}
+/**
+ * Parses a template string using Rendrix with all memory contexts
+ *
+ * @param template - Template string to parse
+ * @param workingMemory - Working memory object for variable substitution (required for rendering)
+ * @param taskConfig - @deprecated Task configuration flags - no longer used by Rendrix 3.0.0+ (kept for backward compatibility)
+ * @param shortTermMemory - Short-term memory for session-specific overrides (optional)
+ * @param experienceMemory - Experience memory for learned knowledge (optional)
+ * @param knowledgeMemory - Knowledge memory for reference data (optional)
+ * @param templateRenderOptions - Passed to Rendrix `render` (v4+): templateId, subPathSearch, silentMissingMustTokens
+ * @returns Parsed template string
+ * @throws {Error} When the parser throws TemplateResolutionError (v4 MUST path missing after merge)
+ */
+export declare function parseTemplate(template: string, workingMemory?: unknown, taskConfig?: TaskConfig, shortTermMemory?: ShortTermMemory, experienceMemory?: ExperienceMemory, knowledgeMemory?: KnowledgeMemory, templateRenderOptions?: TemplateRenderOptions): Promise<string>;
+/**
+ * Checks if Rendrix (@x12i/rendrix) is available
+ */
+export declare function isParserAvailable(): boolean;

package/dist/template-parser.js

@@ -0,0 +1,99 @@
+/**
+ * Template Parser
+ *
+ * Uses @x12i/rendrix (v4+) to parse templates with workingMemory.
+ * TemplateResolutionError from the parser is rethrown; other errors fall back to the raw template.
+ */
+let rendrixModule = null;
+let parserLoadPromise = null;
+async function loadRendrix() {
+    if (rendrixModule !== null || parserLoadPromise) {
+        if (parserLoadPromise)
+            await parserLoadPromise;
+        return;
+    }
+    parserLoadPromise = (async () => {
+        try {
+            rendrixModule = await import('@x12i/rendrix');
+        }
+        catch {
+            rendrixModule = null;
+        }
+        finally {
+            parserLoadPromise = null;
+        }
+    })();
+    await parserLoadPromise;
+}
+/**
+ * Parses a template string using Rendrix with all memory contexts
+ *
+ * @param template - Template string to parse
+ * @param workingMemory - Working memory object for variable substitution (required for rendering)
+ * @param taskConfig - @deprecated Task configuration flags - no longer used by Rendrix 3.0.0+ (kept for backward compatibility)
+ * @param shortTermMemory - Short-term memory for session-specific overrides (optional)
+ * @param experienceMemory - Experience memory for learned knowledge (optional)
+ * @param knowledgeMemory - Knowledge memory for reference data (optional)
+ * @param templateRenderOptions - Passed to Rendrix `render` (v4+): templateId, subPathSearch, silentMissingMustTokens
+ * @returns Parsed template string
+ * @throws {Error} When the parser throws TemplateResolutionError (v4 MUST path missing after merge)
+ */
+export async function parseTemplate(template, workingMemory, taskConfig, shortTermMemory, experienceMemory, knowledgeMemory, templateRenderOptions) {
+    // If no template or empty, return as-is
+    if (!template || typeof template !== 'string') {
+        return template || '';
+    }
+    // If no workingMemory, return template as-is (workingMemory is required for Rendrix)
+    if (!workingMemory) {
+        return template;
+    }
+    await loadRendrix();
+    if (!rendrixModule) {
+        return template;
+    }
+    try {
+        const api = typeof rendrixModule.render === 'function'
+            ? rendrixModule
+            : rendrixModule.default || rendrixModule;
+        if (typeof api.render === 'function') {
+            return await api.render(template, workingMemory, shortTermMemory, experienceMemory, knowledgeMemory, undefined, // functionsMap
+            undefined, // choiceOptions
+            undefined, // filesContent
+            templateRenderOptions);
+        }
+        if (typeof api.parse === 'function') {
+            return await api.parse(template, workingMemory);
+        }
+        else if (typeof api === 'function') {
+            const parser = new api();
+            if (typeof parser.parse === 'function') {
+                return await parser.parse(template, workingMemory);
+            }
+        }
+        return template;
+    }
+    catch (error) {
+        // @x12i/rendrix v4+: missing MUST paths throw TemplateResolutionError.
+        if (error instanceof Error &&
+            error.name === 'TemplateResolutionError') {
+            throw error;
+        }
+        const err = error instanceof Error ? error : new Error(String(error));
+        console.warn('Template parsing failed, using template as-is:', {
+            error: err.message,
+            templateLength: template.length,
+            hasWorkingMemory: !!workingMemory,
+            hasTaskConfig: !!taskConfig,
+            hasShortTermMemory: !!shortTermMemory,
+            hasExperienceMemory: !!experienceMemory,
+            hasKnowledgeMemory: !!knowledgeMemory
+        });
+        return template;
+    }
+}
+/**
+ * Checks if Rendrix (@x12i/rendrix) is available
+ */
+export function isParserAvailable() {
+    return rendrixModule !== null;
+}

package/dist/template-render-merge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Merge @x12i/rendrix TemplateRenderOptions from gateway defaults and per-request overrides.
+ */
+import type { TemplateRenderOptions } from '@x12i/rendrix';
+/**
+ * Deep-merge template render options. Request/gateway overrides win per field.
+ * For `subPathSearch`, `roots` on the override replace the base list when present.
+ */
+export declare function mergeTemplateRenderOptions(base?: TemplateRenderOptions, override?: TemplateRenderOptions): TemplateRenderOptions | undefined;

package/dist/template-render-merge.js

@@ -0,0 +1,40 @@
+/**
+ * Merge @x12i/rendrix TemplateRenderOptions from gateway defaults and per-request overrides.
+ */
+function hasMeaningfulOptions(o) {
+    if (o.templateId !== undefined)
+        return true;
+    if (o.silentMissingMustTokens !== undefined)
+        return true;
+    if (o.subPathSearch !== undefined) {
+        const s = o.subPathSearch;
+        return (s.enabled !== undefined ||
+            (Array.isArray(s.roots) && s.roots.length > 0));
+    }
+    return false;
+}
+/**
+ * Deep-merge template render options. Request/gateway overrides win per field.
+ * For `subPathSearch`, `roots` on the override replace the base list when present.
+ */
+export function mergeTemplateRenderOptions(base, override) {
+    if (!base && !override)
+        return undefined;
+    if (!base) {
+        const o = { ...override };
+        return hasMeaningfulOptions(o) ? o : undefined;
+    }
+    if (!override) {
+        const o = { ...base };
+        return hasMeaningfulOptions(o) ? o : undefined;
+    }
+    const merged = { ...base, ...override };
+    if (base.subPathSearch || override.subPathSearch) {
+        merged.subPathSearch = {
+            ...(base.subPathSearch ?? {}),
+            ...(override.subPathSearch ?? {}),
+            roots: override.subPathSearch?.roots ?? base.subPathSearch?.roots
+        };
+    }
+    return hasMeaningfulOptions(merged) ? merged : undefined;
+}

package/dist/troubleshooting-helper.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Troubleshooting Helper Toolbox
+ *
+ * Utility functions to diagnose and test AI Gateway issues
+ * Based on TROUBLESHOOTING.md guide
+ */
+import type { AIRequest, ChatRequest, EnhancedLLMResponse } from './types.js';
+/**
+ * Converts JSON Schema to simple, human-readable format for LLM instructions
+ *
+ * Supports both formats:
+ * - JSON Schema format: { "type": "object", "properties": {...} }
+ * - Simple format: { "emails": ["<string> description"] }
+ *
+ * If schema is already in simple format, returns it as-is.
+ * If schema is in JSON Schema format, converts it to simple format.
+ *
+ * Simple format example:
+ * {
+ *   "emails": [
+ *     "<string> A valid email address extracted from the input text"
+ *   ]
+ * }
+ *
+ * Format rules:
+ * - Arrays: Show as array with single example item containing type hint + description
+ * - Objects: Show nested structure recursively
+ * - Primitives: Show as type hint with description
+ * - Required fields: Implicit (just present in structure)
+ *
+ * @param schema - Schema object (JSON Schema or simple format)
+ * @returns Schema in simple format
+ */
+export declare function convertSchemaToSimpleFormat(schema: Record<string, unknown>): Record<string, unknown>;
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+export interface DiagnosticInfo {
+    request: {
+        hasJobId: boolean;
+        hasAgentId: boolean;
+        hasInstructions: boolean;
+        hasPrompt: boolean;
+        hasWorkingMemory: boolean;
+        hasConfig: boolean;
+        hasModel: boolean;
+        hasProvider: boolean;
+    };
+    response?: {
+        hasContent: boolean;
+        isJSON: boolean;
+        hasParsedContent: boolean;
+        contentType: string;
+        validationPassed?: boolean;
+        validationErrors?: string[];
+    };
+}
+/**
+ * Validates AIRequest structure
+ */
+export declare function validateAIRequest(request: Partial<AIRequest>): ValidationResult;
+/**
+ * Validates JSON string
+ */
+export declare function validateJSON(jsonString: string): ValidationResult;
+/**
+ * Extracts JSON from text (handles markdown code blocks, etc.)
+ */
+export declare function extractJSON(text: string): {
+    json: string | null;
+    method: string;
+};
+/**
+ * Validates response structure
+ */
+export declare function validateResponse(response: Partial<EnhancedLLMResponse>): ValidationResult;
+/**
+ * Collects comprehensive diagnostic information
+ */
+export declare function diagnoseRequest(request: Partial<AIRequest | ChatRequest>): DiagnosticInfo;
+/**
+ * Diagnoses response issues
+ */
+export declare function diagnoseResponse(response: Partial<EnhancedLLMResponse>): DiagnosticInfo['response'];
+/**
+ * Tests if a provider/model combination supports JSON mode
+ */
+export declare function supportsJSONMode(provider?: string, model?: string): {
+    supported: boolean;
+    notes: string;
+};
+/**
+ * Creates a test AIRequest with minimal valid structure
+ */
+export declare function createTestAIRequest(overrides?: Partial<AIRequest>): AIRequest;
+/**
+ * Creates test cases for validation
+ */
+export declare function createValidationTestCases(): Array<{
+    name: string;
+    request: Partial<AIRequest>;
+    shouldFail: boolean;
+    expectedErrors?: string[];
+}>;
+/**
+ * Runs all validation tests and returns results
+ */
+export declare function runValidationTests(): Array<{
+    name: string;
+    passed: boolean;
+    errors: string[];
+    warnings: string[];
+}>;
+/**
+ * Formats diagnostic information for display
+ */
+export declare function formatDiagnostic(diagnostic: DiagnosticInfo): string;
+/**
+ * Quick validation helper - throws if invalid
+ */
+export declare function assertValidAIRequest(request: Partial<AIRequest>): void;