@exellix/graph-engine 8.0.0 → 8.1.0

package/dist/testkit/flatGraphToAuthoring.js

@@ -0,0 +1,281 @@
+import { GRAPHENIX_FORMAT_VERSION } from '@x12i/graphenix-core';
+import { EXECUTABLE_PROFILE_NAMESPACE, EXECUTABLE_PROFILE_VERSION, FINALIZER_NODE_KIND, FINALIZER_NODE_PROFILE, TASK_NODE_KIND, TASK_NODE_PROFILE, } from '@x12i/graphenix-executable-contracts';
+const ALIAS_TO_CHOICE = {
+    cheap: 'cheap/default',
+    balanced: 'vol/default',
+    deep: 'deep/openai_deep',
+    pro: 'pro/default',
+};
+function isPlainRecord(v) {
+    return v != null && typeof v === 'object' && !Array.isArray(v);
+}
+export function isAuthoringGraphDocument(v) {
+    return isPlainRecord(v) && typeof v.formatVersion === 'string' && isPlainRecord(v.graph);
+}
+function toProfileChoice(value) {
+    if (isPlainRecord(value) && value.kind === 'profileChoice' && typeof value.key === 'string') {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim().length > 0) {
+        const key = value.includes('/') ? value : ALIAS_TO_CHOICE[value] ?? `${value}/default`;
+        return { kind: 'profileChoice', key };
+    }
+    return { kind: 'profileChoice', key: 'pro/default' };
+}
+export function defaultExecutableModelConfig() {
+    return {
+        version: 'graph-model-config/v1',
+        cases: [
+            {
+                id: 'default',
+                modelConfig: {
+                    preActionModel: { kind: 'profileChoice', key: 'cheap/default' },
+                    skillModel: { kind: 'profileChoice', key: 'pro/default' },
+                    postActionModel: { kind: 'profileChoice', key: 'cheap/default' },
+                },
+            },
+        ],
+        fallbackPolicy: {
+            enabled: true,
+            allowedTriggers: [
+                'nodeSlotMissing',
+                'nodeModelUnavailable',
+                'nodeModelUnsupported',
+                'nodeProviderNotConfigured',
+                'nodeModelRateLimited',
+                'nodeModelTransientFailure',
+            ],
+            maxAttemptsPerSlot: 1,
+        },
+    };
+}
+function flatModelConfigToAuthoring(modelConfig) {
+    if (!isPlainRecord(modelConfig) || !Array.isArray(modelConfig.cases)) {
+        return undefined;
+    }
+    return {
+        version: 'graph-model-config/v1',
+        cases: modelConfig.cases.map((entry, index) => {
+            const row = isPlainRecord(entry) ? entry : {};
+            const mc = isPlainRecord(row.modelConfig) ? row.modelConfig : {};
+            const casesLen = modelConfig.cases.length;
+            return {
+                id: typeof row.id === 'string' && row.id.trim().length > 0 ? row.id : index === casesLen - 1 ? 'default' : `case-${index}`,
+                ...(row.when != null ? { when: row.when } : {}),
+                modelConfig: {
+                    preActionModel: toProfileChoice(mc.preActionModel),
+                    skillModel: toProfileChoice(mc.skillModel),
+                    postActionModel: toProfileChoice(mc.postActionModel),
+                },
+            };
+        }),
+        fallbackPolicy: defaultExecutableModelConfig().fallbackPolicy,
+    };
+}
+function normalizeKnowledgeRefs(refs) {
+    if (!Array.isArray(refs))
+        return refs;
+    return refs.map((ref) => {
+        if (typeof ref === 'string')
+            return { id: ref };
+        return ref;
+    });
+}
+function normalizeSmartInput(smartInput) {
+    if (!isPlainRecord(smartInput) || !Array.isArray(smartInput.paths))
+        return smartInput;
+    return {
+        ...smartInput,
+        paths: smartInput.paths.map((entry) => {
+            if (typeof entry === 'string') {
+                const path = entry.startsWith('taskVariables.') || entry.startsWith('jobVariables.')
+                    ? `executionMemory.${entry}`
+                    : entry;
+                return { path };
+            }
+            if (isPlainRecord(entry) && typeof entry.path === 'string') {
+                const path = entry.path;
+                if (path.startsWith('taskVariables.') || path.startsWith('jobVariables.')) {
+                    return { ...entry, path: `executionMemory.${path}` };
+                }
+            }
+            return entry;
+        }),
+    };
+}
+function normalizeJsonConditions(conditions) {
+    if (!isPlainRecord(conditions))
+        return conditions;
+    const next = { ...conditions };
+    const jc = next.jsonConditions;
+    if (jc != null && !Array.isArray(jc)) {
+        if (isPlainRecord(jc) && isPlainRecord(jc.condition) && Array.isArray(jc.condition.all)) {
+            next.jsonConditions = jc.condition.all;
+        }
+        else {
+            next.jsonConditions = [jc];
+        }
+    }
+    return next;
+}
+function patchTaskConfigurationModelConfig(taskConfiguration) {
+    if (!isPlainRecord(taskConfiguration) || !isPlainRecord(taskConfiguration.modelConfig)) {
+        return taskConfiguration;
+    }
+    const next = structuredClone(taskConfiguration);
+    const authored = flatModelConfigToAuthoring(next.modelConfig);
+    if (authored)
+        next.modelConfig = authored;
+    return next;
+}
+function flatTaskNodeToAuthoring(node) {
+    const { id, skillKey, taskVariable, executionMapping, taskConfiguration, inputsConfig, conditions, variables, metadata, executionPipeline, taskKnowledge, smartInput, data, } = node;
+    const parameters = {
+        profile: TASK_NODE_PROFILE,
+        nodeType: 'task',
+    };
+    if (typeof skillKey === 'string')
+        parameters.skillKey = skillKey;
+    if (taskVariable !== undefined)
+        parameters.taskVariable = taskVariable;
+    if (executionMapping !== undefined)
+        parameters.executionMapping = executionMapping;
+    if (inputsConfig !== undefined)
+        parameters.inputsConfig = inputsConfig;
+    if (conditions !== undefined)
+        parameters.conditions = normalizeJsonConditions(conditions);
+    if (variables !== undefined)
+        parameters.variables = variables;
+    if (metadata !== undefined)
+        parameters.metadata = metadata;
+    if (executionPipeline !== undefined)
+        parameters.executionPipeline = executionPipeline;
+    if (taskKnowledge !== undefined)
+        parameters.taskKnowledge = normalizeKnowledgeRefs(taskKnowledge);
+    if (smartInput !== undefined)
+        parameters.smartInput = normalizeSmartInput(smartInput);
+    if (data !== undefined)
+        parameters.data = data;
+    if (taskConfiguration !== undefined) {
+        parameters.taskConfiguration = patchTaskConfigurationModelConfig(taskConfiguration);
+    }
+    else {
+        parameters.taskConfiguration = { executionStrategies: [] };
+    }
+    return {
+        id: String(id),
+        kind: TASK_NODE_KIND,
+        inputs: [{ id: 'in:record', direction: 'input', type: 'builtin:object', required: true }],
+        outputs: [{ id: 'out:answer', direction: 'output', type: 'builtin:object' }],
+        parameters,
+    };
+}
+function flatFinalizerNodeToAuthoring(node, incoming) {
+    const finalizerId = String(node.id);
+    const upstream = incoming.filter((e) => e.to === finalizerId);
+    const inputs = upstream.length > 0
+        ? upstream.map((edge) => ({
+            id: `in:${edge.from}`,
+            direction: 'input',
+            type: 'builtin:object',
+            required: true,
+        }))
+        : [{ id: 'in:final', direction: 'input', type: 'builtin:object', required: false }];
+    const parameters = {
+        profile: FINALIZER_NODE_PROFILE,
+        nodeType: 'finalizer',
+        finalizerType: node.finalizerType,
+        config: isPlainRecord(node.config) ? node.config : {},
+    };
+    if (node.inputs !== undefined)
+        parameters.inputs = node.inputs;
+    if (node.outputMapping !== undefined)
+        parameters.outputMapping = node.outputMapping;
+    return {
+        id: finalizerId,
+        kind: FINALIZER_NODE_KIND,
+        inputs,
+        outputs: [{ id: 'out:final', direction: 'output', type: 'builtin:object' }],
+        parameters,
+    };
+}
+function flatEdgeToAuthoring(edge, index) {
+    const from = String(edge.from);
+    const to = String(edge.to);
+    return {
+        id: typeof edge.id === 'string' ? edge.id : `edge:${index}:${from}:${to}`,
+        from: { nodeId: from, portId: 'out:answer' },
+        to: { nodeId: to, portId: `in:${from === to ? 'final' : from}` },
+        ...(edge.when != null ? { when: edge.when } : {}),
+    };
+}
+/** Converts legacy flat exellix test graphs into Graphenix 2.x {@link AuthoringGraphDocument}. */
+export function flatTestGraphToAuthoringDocument(flat) {
+    const graphId = String(flat.id ?? 'test-graph');
+    const nodesRaw = Array.isArray(flat.nodes) ? flat.nodes : [];
+    const edgesRaw = Array.isArray(flat.edges) ? flat.edges : [];
+    const edgesTyped = edgesRaw.filter(isPlainRecord).map((e) => ({ from: String(e.from), to: String(e.to) }));
+    const nodes = nodesRaw.filter(isPlainRecord).map((node) => {
+        const type = String(node.type ?? 'task');
+        if (type === 'finalizer')
+            return flatFinalizerNodeToAuthoring(node, edgesTyped);
+        return flatTaskNodeToAuthoring(node);
+    });
+    const edges = edgesRaw.filter(isPlainRecord).map((edge, index) => flatEdgeToAuthoring(edge, index));
+    const flatResponse = isPlainRecord(flat.response) ? flat.response : {};
+    const responseShape = isPlainRecord(flatResponse) && isPlainRecord(flatResponse.shape)
+        ? flatResponse.shape
+        : isPlainRecord(flatResponse)
+            ? flatResponse
+            : {};
+    const metadata = isPlainRecord(flat.metadata) ? { ...flat.metadata } : {};
+    if (Array.isArray(flat.jobKnowledge))
+        metadata.jobKnowledge = normalizeKnowledgeRefs(flat.jobKnowledge);
+    if (Array.isArray(flat.taskKnowledge))
+        metadata.taskKnowledge = normalizeKnowledgeRefs(flat.taskKnowledge);
+    const executableProfile = {
+        profileVersion: EXECUTABLE_PROFILE_VERSION,
+        modelConfig: flatModelConfigToAuthoring(flat.modelConfig) ?? defaultExecutableModelConfig(),
+    };
+    metadata.graphResponse = {
+        ...(flatResponse.missing != null ? { missing: flatResponse.missing } : {}),
+        ...(flatResponse.version != null ? { version: flatResponse.version } : {}),
+        shape: responseShape,
+    };
+    metadata.extensions = {
+        ...(isPlainRecord(metadata.extensions) ? metadata.extensions : {}),
+        [EXECUTABLE_PROFILE_NAMESPACE]: executableProfile,
+    };
+    const taskNodes = nodes.filter((n) => n.kind === TASK_NODE_KIND);
+    const finalizer = nodes.find((n) => n.kind === FINALIZER_NODE_KIND);
+    return {
+        formatVersion: GRAPHENIX_FORMAT_VERSION,
+        id: graphId.startsWith('graph:') ? graphId : `graph:${graphId}`,
+        revision: typeof flat.version === 'string' ? flat.version : '1.0.0',
+        name: graphId,
+        graph: {
+            nodes: nodes,
+            edges,
+            inputs: taskNodes.map((node) => ({
+                id: `graph-input:${node.id}`,
+                name: 'Input Record',
+                type: 'builtin:object',
+                target: { nodeId: node.id, portId: 'in:record' },
+                contract: { semanticKind: 'record', required: true, schema: { type: 'object' } },
+            })),
+            outputs: finalizer
+                ? [
+                    {
+                        id: 'graph-output:final',
+                        name: 'Final Output',
+                        type: 'builtin:object',
+                        source: { nodeId: finalizer.id, portId: 'out:final' },
+                        contract: { semanticKind: 'final-output', required: true, schema: { type: 'object' } },
+                    },
+                ]
+                : [],
+            metadata,
+        },
+        types: [],
+    };
+}

package/dist/testkit/index.d.ts

@@ -3,4 +3,7 @@ export { DepGraphEngineFactory } from './depGraphEngineFactory.js';
 export { RealTasksClient } from './RealTasksClient.js';
 export { createTestExellixGraphRuntime } from './testModelAliasRuntime.js';
 export { buildExecuteGraphInput } from './buildExecuteGraphInput.js';
+export { buildAiTaskAuthoringGraph, buildLocalSkillAuthoringGraph, buildGraphResponseMappingAuthoringGraph, withAuthoringGraphModelConfig, } from './authoringGraphFixtures.js';
+export { flatTestGraphToAuthoringDocument, isAuthoringGraphDocument } from './flatGraphToAuthoring.js';
+export { runTaskMainModelSelection, runTaskMainModelSlot, expectMainSkillModelKey, } from './runTaskNodePlanAssertions.js';
 export { tryLoadExellixAiTasksRuntimeSubtree, loadExellixGraphRuntimeObjects, } from './exellixRuntimeObjects.js';

package/dist/testkit/index.js

@@ -3,4 +3,7 @@ export { DepGraphEngineFactory } from './depGraphEngineFactory.js';
 export { RealTasksClient } from './RealTasksClient.js';
 export { createTestExellixGraphRuntime } from './testModelAliasRuntime.js';
 export { buildExecuteGraphInput } from './buildExecuteGraphInput.js';
+export { buildAiTaskAuthoringGraph, buildLocalSkillAuthoringGraph, buildGraphResponseMappingAuthoringGraph, withAuthoringGraphModelConfig, } from './authoringGraphFixtures.js';
+export { flatTestGraphToAuthoringDocument, isAuthoringGraphDocument } from './flatGraphToAuthoring.js';
+export { runTaskMainModelSelection, runTaskMainModelSlot, expectMainSkillModelKey, } from './runTaskNodePlanAssertions.js';
 export { tryLoadExellixAiTasksRuntimeSubtree, loadExellixGraphRuntimeObjects, } from './exellixRuntimeObjects.js';

package/dist/testkit/runTaskNodePlanAssertions.d.ts

@@ -0,0 +1,34 @@
+/** Test helpers for ai-tasks ≥ 9 nodePlan wire shape. */
+type ExecutionUnitLike = Record<string, unknown> & {
+    unitKind?: string;
+};
+export declare function runTaskMainModelSelection(req: {
+    nodePlan?: {
+        executionUnits?: ExecutionUnitLike[];
+    };
+}): unknown;
+export declare function runTaskMainModelSlot(req: {
+    nodePlan?: {
+        executionUnits?: ExecutionUnitLike[];
+    };
+}): unknown;
+export declare function runTaskModelSelectionTriplet(req: {
+    nodePlan?: {
+        executionUnits?: ExecutionUnitLike[];
+    };
+}): {
+    preActionModel: string | undefined;
+    skillModel: string | undefined;
+    postActionModel: string | undefined;
+} | undefined;
+/** Assert helper: compiled plan exposes profileChoice on MAIN unit (skillModel slot). */
+export declare function expectMainSkillModelKey(req: {
+    nodePlan?: {
+        executionUnits?: ExecutionUnitLike[];
+    };
+}, key: string): {
+    modelSelection: unknown;
+    modelSlot: unknown;
+    key: string | undefined;
+};
+export {};

package/dist/testkit/runTaskNodePlanAssertions.js

@@ -0,0 +1,32 @@
+/** Test helpers for ai-tasks ≥ 9 nodePlan wire shape. */
+function mainSkillUnit(nodePlan) {
+    return nodePlan?.executionUnits?.find((u) => u.unitKind === 'mainSkill');
+}
+export function runTaskMainModelSelection(req) {
+    return mainSkillUnit(req.nodePlan)?.modelSelection;
+}
+export function runTaskMainModelSlot(req) {
+    return mainSkillUnit(req.nodePlan)?.modelSlot;
+}
+export function runTaskModelSelectionTriplet(req) {
+    const main = mainSkillUnit(req.nodePlan);
+    const selection = main?.modelSelection;
+    if (!selection || selection.kind !== 'profileChoice' || typeof selection.key !== 'string') {
+        return undefined;
+    }
+    const slot = typeof main?.modelSlot === 'string' ? main.modelSlot : 'skillModel';
+    return {
+        preActionModel: slot === 'preActionModel' ? selection.key : undefined,
+        skillModel: slot === 'skillModel' ? selection.key : undefined,
+        postActionModel: slot === 'postActionModel' ? selection.key : undefined,
+    };
+}
+/** Assert helper: compiled plan exposes profileChoice on MAIN unit (skillModel slot). */
+export function expectMainSkillModelKey(req, key) {
+    const main = mainSkillUnit(req.nodePlan);
+    return {
+        modelSelection: main?.modelSelection,
+        modelSlot: main?.modelSlot,
+        key: main?.modelSelection?.key === key ? key : undefined,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exellix/graph-engine",
-  "version": "8.0.0",
+  "version": "8.1.0",
   "type": "module",
   "description": "Graph executor SDK",
   "main": "dist/src/index.js",
@@ -52,17 +52,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@exellix/ai-tasks": "^8.8.0",
+    "@exellix/ai-tasks": "^9.0.0",
     "@x12i/activix": "8.5.0",
     "@x12i/catalox": "5.1.3",
     "@x12i/env": "4.0.1",
     "@x12i/funcx": "4.4.4",
     "@x12i/graphenix": "2.5.0",
-    "@x12i/graphenix-executable-contracts": "^1.0.0",
-    "@x12i/graphenix-execute-envelope": "^1.0.0",
+    "@x12i/graphenix-authoring-format": "^1.1.0",
+    "@x12i/graphenix-executable-contracts": "^1.1.0",
+    "@x12i/graphenix-executable-format": "^2.1.2",
+    "@x12i/graphenix-execute-envelope": "^1.1.0",
     "@x12i/graphenix-format": "2.0.0",
-    "@x12i/graphenix-plan-format": "^1.0.0",
-    "@x12i/graphenix-plan-compiler": "^1.0.0",
+    "@x12i/graphenix-plan-compiler": "^1.1.0",
+    "@x12i/graphenix-plan-format": "^1.1.0",
     "@x12i/graphenix-trace-format": "^1.0.0",
     "@x12i/logxer": "^4.6.0",
     "@x12i/memorix-descriptors": "1.6.0",
@@ -73,7 +75,6 @@
   },
   "devDependencies": {
     "@types/node": "25.9.1",
-    "@x12i/graphenix-authoring-format": "^1.0.1",
     "tsx": "4.22.3",
     "typescript": "6.0.3"
   }

package/dist/src/adapters/compileExellixExecutablePlan.d.ts

@@ -1,8 +0,0 @@
-import type { CompileExecutablePlanV2Options, ExecutableGraphPlanV2 } from '@x12i/graphenix-executable-contracts';
-import type { Graph, GraphModelObject } from '../types/refs.js';
-import type { GraphRuntimeObject } from '../runtime/ExellixGraphRuntime.js';
-export type CompileExellixExecutablePlanOptions = CompileExecutablePlanV2Options;
-/**
- * Host/test helper: exellix graph model + runtime → validated v2 executable plan.
- */
-export declare function compileExellixExecutablePlan(model: Graph | GraphModelObject, runtime: GraphRuntimeObject, options?: CompileExellixExecutablePlanOptions): ExecutableGraphPlanV2;

package/dist/src/adapters/compileExellixExecutablePlan.js

@@ -1,18 +0,0 @@
-import { compileExecutablePlanV2 } from '@x12i/graphenix-plan-compiler';
-import { validateExecutablePlan } from '@x12i/graphenix-plan-format';
-import { migrateExellixGraphModelToAuthoring } from './migrateExellixGraphModelToAuthoring.js';
-import { patchFinalizerPlansOnExecutablePlan } from './patchFinalizerPlans.js';
-/**
- * Host/test helper: exellix graph model + runtime → validated v2 executable plan.
- */
-export function compileExellixExecutablePlan(model, runtime, options) {
-    const authoring = migrateExellixGraphModelToAuthoring(model);
-    const compiled = compileExecutablePlanV2(authoring, runtime, options);
-    const plan = patchFinalizerPlansOnExecutablePlan(compiled, runtime);
-    const validation = validateExecutablePlan(plan);
-    if (!validation.valid) {
-        const summary = validation.errors.map((e) => `${e.path}: ${e.message}`).join('; ');
-        throw new Error(`compileExellixExecutablePlan: invalid plan: ${summary}`);
-    }
-    return plan;
-}

package/dist/src/adapters/migrateExellixGraphModelToAuthoring.d.ts

@@ -1,6 +0,0 @@
-import { type AuthoringGraphDocument } from '@x12i/graphenix-executable-contracts';
-import type { Graph, GraphModelObject } from '../types/refs.js';
-/**
- * Converts exellix {@link GraphModelObject} to graphenix {@link AuthoringGraphDocument} for plan compilation.
- */
-export declare function migrateExellixGraphModelToAuthoring(model: Graph | GraphModelObject): AuthoringGraphDocument;