@x12i/ai-gateway 7.9.1

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

@@ -0,0 +1,38 @@
+/**
+ * Response Analyzer
+ *
+ * Main class that orchestrates object type and format type detection.
+ * Analyzes normalized responses and provides enhanced metadata.
+ */
+import type { ResponseAnalyzerConfig, AnalysisResult, ObjectTypeDefinition } from './types.js';
+/**
+ * Analyzes AI responses to detect object types and format types
+ */
+export declare class ResponseAnalyzer {
+    private objectDetector?;
+    private formatDetector;
+    private enableFormatDetection;
+    constructor(config?: ResponseAnalyzerConfig);
+    /**
+     * Analyzes a response and returns enhanced metadata
+     *
+     * @param rawText - Raw text content from response
+     * @param parsedContent - Parsed content (object, array, or null)
+     * @returns Analysis result with detected types
+     */
+    analyze(rawText?: string, parsedContent?: any): AnalysisResult;
+    /**
+     * Determines the content type of the response
+     *
+     * @param rawText - Raw text content
+     * @param parsedContent - Parsed content
+     * @returns Content type classification
+     */
+    private determineContentType;
+    /**
+     * Updates object type definitions
+     *
+     * @param definitions - New object type definitions
+     */
+    updateObjectTypeDefinitions(definitions: ObjectTypeDefinition[]): void;
+}

package/dist-cjs/response-analyzer/types.cjs

@@ -0,0 +1,5 @@
+"use strict";
+/**
+ * Type definitions for Response Analyzer
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist-cjs/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-cjs/response-fallback-fixer.cjs

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryFixGatewayResponseToJsonText = tryFixGatewayResponseToJsonText;
+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;
+}
+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-cjs/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-cjs/runtime-objects.cjs

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeObjects = void 0;
+exports.setGatewayLastJobId = setGatewayLastJobId;
+exports.setGatewayRuntimeClients = setGatewayRuntimeClients;
+exports.getRuntimeObservabilityMode = getRuntimeObservabilityMode;
+exports.runtimeObjects = createRuntimeObjectsForMode();
+function setGatewayLastJobId(jobId) {
+    const objects = ensureRuntimeObjectsForCurrentMode();
+    if (!objects)
+        return;
+    objects.lastJobId = jobId;
+}
+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 = [];
+}
+function getRuntimeObservabilityMode() {
+    const rawMode = process.env.mode ?? process.env.MODE;
+    return rawMode === 'prod' ? 'prod' : 'debug';
+}
+function ensureRuntimeObjectsForCurrentMode() {
+    if (getRuntimeObservabilityMode() === 'prod') {
+        exports.runtimeObjects = undefined;
+        return undefined;
+    }
+    exports.runtimeObjects ??= createRuntimeObjects();
+    return exports.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-cjs/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-cjs/template-parser.cjs

@@ -0,0 +1,136 @@
+"use strict";
+/**
+ * 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.
+ */
+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.parseTemplate = parseTemplate;
+exports.isParserAvailable = isParserAvailable;
+let rendrixModule = null;
+let parserLoadPromise = null;
+async function loadRendrix() {
+    if (rendrixModule !== null || parserLoadPromise) {
+        if (parserLoadPromise)
+            await parserLoadPromise;
+        return;
+    }
+    parserLoadPromise = (async () => {
+        try {
+            rendrixModule = await Promise.resolve().then(() => __importStar(require('@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)
+ */
+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
+ */
+function isParserAvailable() {
+    return rendrixModule !== null;
+}

package/dist-cjs/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-cjs/template-render-merge.cjs

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Merge @x12i/rendrix TemplateRenderOptions from gateway defaults and per-request overrides.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeTemplateRenderOptions = mergeTemplateRenderOptions;
+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.
+ */
+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-cjs/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;