@x12i/ai-gateway 9.1.5 → 9.2.0

package/dist-cjs/output-contract-normalizer.cjs

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Normalizes invoke responses into `output.parsed` when an explicit output contract is forwarded.
+ * Does not infer contracts from other request fields — that is upstream (graph-engine / ai-tasks).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.contractSpecToFieldKeys = contractSpecToFieldKeys;
+exports.resolveOutputContractFieldKeys = resolveOutputContractFieldKeys;
+exports.enrichParsedContentForOutputContract = enrichParsedContentForOutputContract;
+const flex_md_loader_js_1 = require("./flex-md-loader.cjs");
+const memory_path_resolution_js_1 = require("./memory-path-resolution.cjs");
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasMeaningfulContractValue(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return value.trim().length > 0;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+/**
+ * Maps an explicit contract spec to field keys. No inference from descriptions or other request fields.
+ */
+function contractSpecToFieldKeys(contract) {
+    if (contract == null)
+        return [];
+    if (Array.isArray(contract)) {
+        return contract.filter((k) => typeof k === 'string' && k.trim().length > 0);
+    }
+    if (!isPlainObject(contract))
+        return [];
+    const properties = contract.properties;
+    if (isPlainObject(properties)) {
+        return Object.keys(properties);
+    }
+    return [];
+}
+/** Graph-engine path: `workingMemory.inputs.outputContract` or merged `input.outputContract`. */
+function readExplicitOutputContractFromWorkingMemory(workingMemory) {
+    if (!isPlainObject(workingMemory))
+        return undefined;
+    const inputs = (0, memory_path_resolution_js_1.extractCallerInputsBag)(workingMemory);
+    if (inputs?.outputContract !== undefined)
+        return inputs.outputContract;
+    const input = (0, memory_path_resolution_js_1.coalesceMergedInputBucket)(workingMemory);
+    if (isPlainObject(input) && input.outputContract !== undefined) {
+        return input.outputContract;
+    }
+    const loose = (0, memory_path_resolution_js_1.parseLooseJsonObject)(workingMemory.input);
+    if (loose?.outputContract !== undefined)
+        return loose.outputContract;
+    return undefined;
+}
+/**
+ * Resolves field keys only from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+function resolveOutputContractFieldKeys(request) {
+    if (request == null || typeof request !== 'object')
+        return undefined;
+    const r = request;
+    const candidates = [
+        r.outputContract,
+        readExplicitOutputContractFromWorkingMemory(r.workingMemory)
+    ];
+    for (const candidate of candidates) {
+        const keys = contractSpecToFieldKeys(candidate);
+        if (keys.length > 0)
+            return keys;
+    }
+    return undefined;
+}
+function asParsedRecord(parsed) {
+    if (!isPlainObject(parsed))
+        return {};
+    return { ...parsed };
+}
+function pickAliasValue(source, key) {
+    if (hasMeaningfulContractValue(source[key]))
+        return source[key];
+    const spaced = key.replace(/([A-Z])/g, ' $1').replace(/^./, (c) => c.toUpperCase());
+    const title = spaced.charAt(0).toUpperCase() + spaced.slice(1);
+    const aliases = [
+        key,
+        key.toLowerCase(),
+        title,
+        title.replace(/\s+/g, ' '),
+        key.replace(/([A-Z])/g, '_$1').toLowerCase()
+    ];
+    for (const alias of aliases) {
+        if (hasMeaningfulContractValue(source[alias]))
+            return source[alias];
+    }
+    return undefined;
+}
+/**
+ * Fills missing contract keys from markdown sections after flex-md. Only runs when explicit contract keys were supplied.
+ */
+async function enrichParsedContentForOutputContract(parsed, rawContent, contractKeys, logger) {
+    const base = asParsedRecord(parsed);
+    if (!contractKeys?.length)
+        return base;
+    const missing = contractKeys.filter((k) => !hasMeaningfulContractValue(base[k]));
+    if (missing.length === 0)
+        return base;
+    const content = typeof rawContent === 'string' && rawContent.trim().length > 0
+        ? rawContent
+        : typeof base.rawText === 'string'
+            ? base.rawText
+            : '';
+    if (!content.trim())
+        return base;
+    const fromMarkdown = (0, flex_md_loader_js_1.parseMarkdownSectionsFromContent)(content, logger);
+    const merged = { ...base };
+    for (const key of missing) {
+        const value = pickAliasValue(fromMarkdown, key);
+        if (hasMeaningfulContractValue(value)) {
+            merged[key] = value;
+        }
+    }
+    return merged;
+}

package/dist-cjs/output-contract-normalizer.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Normalizes invoke responses into `output.parsed` when an explicit output contract is forwarded.
+ * Does not infer contracts from other request fields — that is upstream (graph-engine / ai-tasks).
+ */
+import type { Logxer } from '@x12i/logxer';
+/** Explicit contract: field names or JSON-schema-style `properties` only. */
+export type OutputContractSpec = string[] | {
+    properties: Record<string, unknown>;
+};
+/**
+ * Maps an explicit contract spec to field keys. No inference from descriptions or other request fields.
+ */
+export declare function contractSpecToFieldKeys(contract: unknown): string[];
+/**
+ * Resolves field keys only from explicit `outputContract` on the request or graph-forwarded inputs.
+ */
+export declare function resolveOutputContractFieldKeys(request: unknown): string[] | undefined;
+/**
+ * Fills missing contract keys from markdown sections after flex-md. Only runs when explicit contract keys were supplied.
+ */
+export declare function enrichParsedContentForOutputContract(parsed: unknown, rawContent: string, contractKeys: string[] | undefined, logger?: Logxer): Promise<Record<string, unknown>>;

package/dist-cjs/template-parser.cjs

@@ -41,6 +41,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseTemplate = parseTemplate;
 exports.isParserAvailable = isParserAvailable;
+const memory_path_resolution_js_1 = require("./memory-path-resolution.cjs");
 let rendrixModule = null;
 let parserLoadPromise = null;
 async function loadRendrix() {
@@ -85,6 +86,7 @@ async function parseTemplate(template, workingMemory, taskConfig, shortTermMemor
     if (!workingMemory) {
         return template;
     }
+    const wmForRender = (0, memory_path_resolution_js_1.prepareWorkingMemoryForTemplateRender)(workingMemory);
     await loadRendrix();
     if (!rendrixModule) {
         return template;
@@ -94,18 +96,18 @@ async function parseTemplate(template, workingMemory, taskConfig, shortTermMemor
             ? rendrixModule
             : rendrixModule.default || rendrixModule;
         if (typeof api.render === 'function') {
-            return await api.render(template, workingMemory, shortTermMemory, experienceMemory, knowledgeMemory, undefined, // functionsMap
+            return await api.render(template, wmForRender, shortTermMemory, experienceMemory, knowledgeMemory, undefined, // functionsMap
             undefined, // choiceOptions
             undefined, // filesContent
             templateRenderOptions);
         }
         if (typeof api.parse === 'function') {
-            return await api.parse(template, workingMemory);
+            return await api.parse(template, wmForRender);
         }
         else if (typeof api === 'function') {
             const parser = new api();
             if (typeof parser.parse === 'function') {
-                return await parser.parse(template, workingMemory);
+                return await parser.parse(template, wmForRender);
             }
         }
         return template;

package/dist-cjs/types.d.ts

@@ -626,6 +626,10 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * Working memory (optional) - Affects all template parsing
      * Passed to Rendrix (v4+) for template variable substitution.
      * Plain {{path}} tokens are MUST paths: undefined after merge throws TemplateResolutionError (rethrown by the gateway).
+     *
+     * Dual roots (graph-engine / ai-tasks contract): `inputs` is the caller / graph-entry bag;
+     * `input` is the merged MAIN payload (object or JSON string). Smart-input and `input.*` / `inputs.*`
+     * paths resolve with cross-root fallback before render (see `resolveGatewayMemoryPathValue`).
      */
     workingMemory?: unknown;
     /**
@@ -697,6 +701,14 @@ interface BaseLLMRequest extends Omit<LLMRequest, 'messages' | 'input' | 'reques
      * attach heavy diagnostic objects or raw provider payloads.
      */
     diagnostics?: DiagnosticsOptions;
+    /**
+     * Explicit output contract from graph-engine / ai-tasks: field names or `{ properties }`.
+     * Also accepted on `workingMemory.inputs.outputContract`. When absent, the gateway does not
+     * infer contract fields from other request shapes (`expectedSchema`, config, etc.).
+     */
+    outputContract?: string[] | {
+        properties: Record<string, unknown>;
+    };
 }
 /**
  * Chat request for conversational use cases
@@ -928,6 +940,12 @@ export interface EnhancedLLMResponse<TContent = unknown> extends Omit<AIResponse
          * Cost in USD (if available)
          */
         cost?: number;
+        /**
+         * Billing state for Run Analysis / Activix when usage is recorded.
+         * - `priced`: {@link cost} / {@link costUsd} is a finite number from the router
+         * - `unpriced`: usage exists but no price table / adapter cost was returned
+         */
+        costStatus?: 'priced' | 'unpriced';
         /**
          * Cost in USD (preferred stable key when the router exposes it).
          * When both are present, costUsd should mirror cost.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x12i/ai-gateway",
-  "version": "9.1.5",
+  "version": "9.2.0",
   "description": "AI Gateway - Unified interface for LLM provider routing and management",
   "type": "module",
   "exports": {
@@ -60,7 +60,7 @@
   "author": "x12i",
   "license": "mit",
   "dependencies": {
-    "@x12i/ai-providers-router": "^4.7.7",
+    "@x12i/ai-providers-router": "^4.8.0",
     "@x12i/rendrix": "^4.3.0",
     "@aws-sdk/s3-request-presigner": "^3.953.0",
     "@x12i/env": "^4.0.1",