@exellix/graph-engine 6.0.0

package/dist/src/integrations/ActivixNodeActivityIntegration.js

@@ -0,0 +1,220 @@
+/**
+ * Bridges exellix-graph node execution events to @x12i/activix (start → complete / fail records).
+ *
+ * Listens for `node:start`, `node:complete`, and `node:fail` only. Graph-level events are ignored.
+ */
+function summarizeValueForRecord(value) {
+    if (value === null || value === undefined) {
+        return { shape: 'empty' };
+    }
+    if (typeof value === 'string') {
+        return { shape: 'string', length: value.length };
+    }
+    if (typeof value === 'object' && !Array.isArray(value)) {
+        const keys = Object.keys(value);
+        return { shape: 'object', keyCount: keys.length, keysSample: keys.slice(0, 40) };
+    }
+    if (Array.isArray(value)) {
+        return { shape: 'array', length: value.length };
+    }
+    return { shape: typeof value };
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Returns an EventEmitter that persists node lifecycle rows via Activix.
+ * Correlates start → complete/fail using `graphId:nodeId:taskId` (includes engine-generated graph-run `taskId`).
+ */
+export function createActivixNodeActivityIntegration(ax, options) {
+    const collection = options?.collection;
+    const includeInputSnapshot = options?.includeInputSnapshot === true;
+    const extractNarrixOutcome = options?.extractNarrixOutcome === true;
+    const colOpts = collection ? { collection } : undefined;
+    const nodeRecordIds = new Map();
+    let initPromise = null;
+    function ensureInit() {
+        if (!initPromise) {
+            initPromise = ax.init().catch((err) => {
+                initPromise = null;
+                throw err;
+            });
+        }
+        return initPromise;
+    }
+    const eventEmitter = {
+        emit(event) {
+            setImmediate(async () => {
+                try {
+                    if (event.type === 'node:start') {
+                        const nodeEvent = event;
+                        const input = nodeEvent.data?.input;
+                        const jobType = nodeEvent.data != null && typeof nodeEvent.data === 'object' && 'jobType' in nodeEvent.data
+                            ? nodeEvent.data.jobType
+                            : undefined;
+                        // Activix v5+ correlation object is `runContext` and must include `sessionId`.
+                        // This SDK does not have a separate session id today, so we align it to `jobId`.
+                        const runContext = {
+                            sessionId: nodeEvent.jobId,
+                            jobId: nodeEvent.jobId,
+                            taskId: nodeEvent.taskId,
+                            graphId: nodeEvent.graphId,
+                            nodeId: nodeEvent.nodeId,
+                            skillKey: nodeEvent.skillKey,
+                            ...(jobType != null ? { jobType } : {}),
+                        };
+                        const outerInput = isPlainObject(input) ? input : {};
+                        const outerRequest = nodeEvent.data?.input?.request;
+                        const outerMemoryStart = nodeEvent.data?.input?.memoryStart;
+                        const outerMetadata = {
+                            kind: 'exellix-graph-node',
+                            jobId: nodeEvent.jobId,
+                            taskId: nodeEvent.taskId,
+                            graphId: nodeEvent.graphId,
+                            nodeId: nodeEvent.nodeId,
+                            skillKey: nodeEvent.skillKey,
+                            ...(jobType != null ? { jobType } : {}),
+                            eventTimestamp: nodeEvent.timestamp,
+                        };
+                        const base = {
+                            kind: 'exellix-graph-node',
+                            jobId: nodeEvent.jobId,
+                            taskId: nodeEvent.taskId,
+                            graphId: nodeEvent.graphId,
+                            nodeId: nodeEvent.nodeId,
+                            skillKey: nodeEvent.skillKey,
+                            ...(jobType != null ? { jobType } : {}),
+                            eventTimestamp: nodeEvent.timestamp,
+                            runContext,
+                            outer: {
+                                input: {
+                                    ...outerInput,
+                                    request: outerRequest,
+                                },
+                                output: undefined,
+                                memory: {
+                                    start: outerMemoryStart,
+                                },
+                                metadata: outerMetadata,
+                            },
+                        };
+                        if (includeInputSnapshot && input && typeof input === 'object') {
+                            const vars = input.variables;
+                            if (vars && typeof vars === 'object') {
+                                base.inputVariableKeys = Object.keys(vars);
+                                if (isPlainObject(base.outer?.metadata)) {
+                                    base.outer.metadata.inputVariableKeys = base.inputVariableKeys;
+                                }
+                            }
+                            const jm = input.jobMemory;
+                            const ex = jm?.execution;
+                            if (ex != null && typeof ex === 'object') {
+                                base.executionKeys = Object.keys(ex);
+                                if (isPlainObject(base.outer?.metadata)) {
+                                    base.outer.metadata.executionKeys = base.executionKeys;
+                                }
+                            }
+                        }
+                        const key = `${nodeEvent.graphId}:${nodeEvent.nodeId}:${nodeEvent.taskId}`;
+                        // Start the record insert immediately (promise inserted into the map synchronously),
+                        // but defer actual DB work until `ax.init()` is ready.
+                        const recordPromise = (async () => {
+                            await ensureInit();
+                            const { recordId } = await ax.startRecord(base, colOpts);
+                            return recordId;
+                        })();
+                        nodeRecordIds.set(key, recordPromise);
+                        await recordPromise;
+                    }
+                    else if (event.type === 'node:complete') {
+                        const nodeEvent = event;
+                        const key = `${nodeEvent.graphId}:${nodeEvent.nodeId}:${nodeEvent.taskId}`;
+                        const recordPromise = nodeRecordIds.get(key);
+                        if (!recordPromise) {
+                            console.warn(`Activix node activity: no start record for graphId=${nodeEvent.graphId} nodeId=${nodeEvent.nodeId}`);
+                            return;
+                        }
+                        const output = nodeEvent.data?.output ?? nodeEvent.result;
+                        const { narrixSummary } = extractNarrixOutcome ? extractNarrixSummary(nodeEvent) : { narrixSummary: undefined };
+                        const outputSummary = summarizeValueForRecord(output);
+                        const outerResponse = nodeEvent.data?.response;
+                        const outerMemoryEnd = nodeEvent.data?.memoryAfter;
+                        const recordId = await recordPromise;
+                        await ax.completeRecord(recordId, {
+                            completedAt: nodeEvent.timestamp,
+                            outputSummary,
+                            ...(narrixSummary ? { narrixSummary } : {}),
+                            outer: {
+                                output: {
+                                    response: outerResponse,
+                                },
+                                memory: {
+                                    end: outerMemoryEnd,
+                                },
+                            },
+                        }, colOpts);
+                        nodeRecordIds.delete(key);
+                    }
+                    else if (event.type === 'node:fail') {
+                        const nodeEvent = event;
+                        const key = `${nodeEvent.graphId}:${nodeEvent.nodeId}:${nodeEvent.taskId}`;
+                        const recordPromise = nodeRecordIds.get(key);
+                        if (!recordPromise) {
+                            console.warn(`Activix node activity: no start record for graphId=${nodeEvent.graphId} nodeId=${nodeEvent.nodeId}`);
+                            return;
+                        }
+                        const err = nodeEvent.error ?? nodeEvent.data?.error;
+                        const message = err instanceof Error
+                            ? err.message
+                            : typeof err === 'object' && err && 'message' in err
+                                ? String(err.message)
+                                : String(err ?? 'unknown error');
+                        const outerResponse = nodeEvent.data?.response;
+                        const outerMemoryEnd = nodeEvent.data?.memoryAfter;
+                        const recordId = await recordPromise;
+                        await ax.failRecord(recordId, message, {
+                            failedAt: nodeEvent.timestamp,
+                            outer: {
+                                output: {
+                                    response: outerResponse,
+                                },
+                                memory: {
+                                    end: outerMemoryEnd,
+                                },
+                            },
+                        }, colOpts);
+                        nodeRecordIds.delete(key);
+                    }
+                }
+                catch (error) {
+                    console.error('Activix node activity error (non-fatal):', error);
+                }
+            });
+        },
+    };
+    return { eventEmitter, nodeRecordIds };
+}
+function extractNarrixSummary(nodeEvent) {
+    const node = nodeEvent.node;
+    const output = nodeEvent.data?.output ?? nodeEvent.result;
+    const questionId = node?.taskConfiguration?.narrix?.questionId;
+    const datasetId = nodeEvent.data?.memoryAfter?.jobMemory?.execution?.input?.metadata?.datasetId;
+    if (output == null || typeof output !== 'object') {
+        return { narrixSummary: undefined };
+    }
+    const outObj = output;
+    const hasShortAnswer = 'shortAnswer' in outObj;
+    const hasEvidence = 'evidence' in outObj;
+    const hasFullAnswer = 'fullAnswer' in outObj;
+    if (!hasShortAnswer && !hasFullAnswer && !hasEvidence) {
+        return { narrixSummary: undefined };
+    }
+    const narrixSummary = {
+        ...(datasetId ? { datasetId } : {}),
+        ...(questionId ? { questionId } : {}),
+        ...(outObj.shortAnswer !== undefined ? { shortAnswer: outObj.shortAnswer } : {}),
+        ...(outObj.fullAnswer !== undefined ? { fullAnswer: outObj.fullAnswer } : {}),
+        ...(outObj.evidence !== undefined ? { evidence: outObj.evidence } : {}),
+    };
+    return { narrixSummary };
+}

package/dist/src/integrations/cataloxGraphCatalog.d.ts

@@ -0,0 +1,21 @@
+import type { Catalox, CataloxContext } from '@x12i/catalox';
+import type { Graph } from '../types/refs.js';
+/**
+ * Issue from {@link validateGraphPlanningCatalogDescriptorsInCatalox}.
+ */
+export type GraphCatalogValidationIssue = {
+    code: 'descriptor_missing';
+    message: string;
+    catalogId?: string;
+};
+/**
+ * For each planning `catalogId` referenced on the graph (scoped-question + discovery-definition),
+ * checks that a Catalox catalog descriptor exists for the tenant `ctx.appId`.
+ *
+ * Callers supply a {@link Catalox} instance (for example from their own Firebase / env wiring
+ * or via helpers re-exported from `@exellix/ai-tasks`).
+ */
+export declare function validateGraphPlanningCatalogDescriptorsInCatalox(graph: Graph, catalox: Catalox, ctx: CataloxContext): Promise<{
+    ok: boolean;
+    issues: GraphCatalogValidationIssue[];
+}>;

package/dist/src/integrations/cataloxGraphCatalog.js

@@ -0,0 +1,30 @@
+import { getGraphCatalogs } from '../inspection/graphInspection.js';
+import { assertCanonicalGraphDocument } from '../runtime/validateCanonicalGraphDocument.js';
+/**
+ * For each planning `catalogId` referenced on the graph (scoped-question + discovery-definition),
+ * checks that a Catalox catalog descriptor exists for the tenant `ctx.appId`.
+ *
+ * Callers supply a {@link Catalox} instance (for example from their own Firebase / env wiring
+ * or via helpers re-exported from `@exellix/ai-tasks`).
+ */
+export async function validateGraphPlanningCatalogDescriptorsInCatalox(graph, catalox, ctx) {
+    assertCanonicalGraphDocument(graph, { graphId: graph?.id });
+    const cats = getGraphCatalogs(graph);
+    const ids = new Set();
+    for (const id of cats.scopedQuestionCatalogIds)
+        ids.add(id);
+    for (const id of cats.discoveryDefinitionCatalogIds)
+        ids.add(id);
+    const issues = [];
+    for (const catalogId of ids) {
+        const desc = await catalox.getCatalogDescriptor(ctx, catalogId);
+        if (desc == null) {
+            issues.push({
+                code: 'descriptor_missing',
+                message: `No Catalox catalog descriptor for catalogId "${catalogId}" (appId=${String(ctx.appId ?? '')})`,
+                catalogId,
+            });
+        }
+    }
+    return { ok: issues.length === 0, issues };
+}

package/dist/src/integrations/createActivixExellixIntegration.d.ts

@@ -0,0 +1,14 @@
+import type { Activix } from '@x12i/activix';
+import type { EventEmitter } from '../runtime/events.js';
+import { type CreateActivixNodeActivityIntegrationOptions } from './ActivixNodeActivityIntegration.js';
+import { type CreateActivixGraphRunIntegrationOptions } from './ActivixGraphRunIntegration.js';
+export interface CreateActivixExellixIntegrationOptions {
+    activixNodeActivity?: CreateActivixNodeActivityIntegrationOptions;
+    activixGraphRun?: CreateActivixGraphRunIntegrationOptions;
+}
+/**
+ * Combines node + graph lifecycle persistence into a single `eventEmitter`.
+ */
+export declare function createActivixExellixIntegration(ax: Activix, options?: CreateActivixExellixIntegrationOptions): {
+    eventEmitter: EventEmitter | undefined;
+};

package/dist/src/integrations/createActivixExellixIntegration.js

@@ -0,0 +1,16 @@
+import { composeEventEmitters } from '../runtime/events.js';
+import { createActivixNodeActivityIntegration, } from './ActivixNodeActivityIntegration.js';
+import { createActivixGraphRunIntegration, } from './ActivixGraphRunIntegration.js';
+/**
+ * Combines node + graph lifecycle persistence into a single `eventEmitter`.
+ */
+export function createActivixExellixIntegration(ax, options) {
+    const node = options?.activixNodeActivity
+        ? createActivixNodeActivityIntegration(ax, options.activixNodeActivity)
+        : undefined;
+    const graph = options?.activixGraphRun
+        ? createActivixGraphRunIntegration(ax, options.activixGraphRun)
+        : undefined;
+    const eventEmitter = composeEventEmitters(node?.eventEmitter, graph?.eventEmitter);
+    return { eventEmitter };
+}

package/dist/src/integrations/createActivixFromEnv.d.ts

@@ -0,0 +1,31 @@
+import { Activix } from '@x12i/activix';
+export interface CreateActivixFromEnvOptions {
+    /** When true, throws if required env vars are missing. Defaults to true. */
+    strict?: boolean;
+}
+/**
+ * MongoDB collection names for exellix-graph Activix streams. Must match the `collection` option passed to
+ * `createActivixGraphRunIntegration` / `createActivixNodeActivityIntegration` (Activix resolves by **name**, not an abstract role).
+ *
+ * Override with `ACTIVIX_GRAPH_RUNS_COLLECTION` / `ACTIVIX_NODE_ACTIVITY_COLLECTION`.
+ */
+export declare function resolveActivixExellixCollectionNamesFromEnv(): {
+    graphRuns: string;
+    nodeActivity: string;
+};
+/**
+ * Creates a configured Activix instance from env.
+ *
+ * Uses:
+ * - `MONGO_URI` (or `MONGO_LOGS_URI`) for connection
+ * - Database selection is handled by Activix/environment resolution.
+ *
+ * Collections: two named streams (defaults `exellix-graph-runs`, `exellix-node-activity`). Use
+ * {@link resolveActivixExellixCollectionNamesFromEnv} when wiring integrations so names stay aligned.
+ *
+ * Activix 7+ multi-collection mode requires `defaultCollection`. We set it to the node-activity stream
+ * so node-activity integrations (and runtimes from `createExellixGraphRuntime`) that omit `collection`
+ * still land on the intended stream; graph-run integrations should pass `collection` explicitly when
+ * using both streams.
+ */
+export declare function createActivixFromEnv(options?: CreateActivixFromEnvOptions): Activix;

package/dist/src/integrations/createActivixFromEnv.js

@@ -0,0 +1,53 @@
+import { Activix } from '@x12i/activix';
+function requiredEnv(name, strict) {
+    const v = process.env[name];
+    if (v && v.trim().length > 0)
+        return v;
+    if (strict)
+        throw new Error(`Missing required env var: ${name}`);
+    return '';
+}
+/**
+ * MongoDB collection names for exellix-graph Activix streams. Must match the `collection` option passed to
+ * `createActivixGraphRunIntegration` / `createActivixNodeActivityIntegration` (Activix resolves by **name**, not an abstract role).
+ *
+ * Override with `ACTIVIX_GRAPH_RUNS_COLLECTION` / `ACTIVIX_NODE_ACTIVITY_COLLECTION`.
+ */
+export function resolveActivixExellixCollectionNamesFromEnv() {
+    const g = process.env.ACTIVIX_GRAPH_RUNS_COLLECTION?.trim();
+    const n = process.env.ACTIVIX_NODE_ACTIVITY_COLLECTION?.trim();
+    return {
+        graphRuns: g && g.length > 0 ? g : 'exellix-graph-runs',
+        nodeActivity: n && n.length > 0 ? n : 'exellix-node-activity',
+    };
+}
+/**
+ * Creates a configured Activix instance from env.
+ *
+ * Uses:
+ * - `MONGO_URI` (or `MONGO_LOGS_URI`) for connection
+ * - Database selection is handled by Activix/environment resolution.
+ *
+ * Collections: two named streams (defaults `exellix-graph-runs`, `exellix-node-activity`). Use
+ * {@link resolveActivixExellixCollectionNamesFromEnv} when wiring integrations so names stay aligned.
+ *
+ * Activix 7+ multi-collection mode requires `defaultCollection`. We set it to the node-activity stream
+ * so node-activity integrations (and runtimes from `createExellixGraphRuntime`) that omit `collection`
+ * still land on the intended stream; graph-run integrations should pass `collection` explicitly when
+ * using both streams.
+ */
+export function createActivixFromEnv(options) {
+    const strict = options?.strict !== false;
+    const mongoUri = process.env.MONGO_LOGS_URI && process.env.MONGO_LOGS_URI.trim().length > 0
+        ? process.env.MONGO_LOGS_URI
+        : requiredEnv('MONGO_URI', strict);
+    const { graphRuns: graphRunsCollection, nodeActivity: nodeActivityCollection } = resolveActivixExellixCollectionNamesFromEnv();
+    return new Activix({
+        mongoUri,
+        defaultCollection: nodeActivityCollection,
+        collections: [
+            { name: graphRunsCollection },
+            { name: nodeActivityCollection },
+        ],
+    });
+}

package/dist/src/loaders/FileGraphLoader.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Graph loader that loads graph JSON from the filesystem.
+ * Use for loading NARRIX triage graphs from a graphs/ directory.
+ */
+import type { Graph } from '../types/refs.js';
+import type { GraphLoader as RuntimeGraphLoader } from '../runtime/ExellixGraphRuntime.js';
+export interface FileGraphLoaderOptions {
+    /** Base directory for graph JSON files (default: process.cwd() + '/graphs') */
+    baseDir?: string;
+    /** Optional map of graphId -> relative path from baseDir (default: graphId + '.json') */
+    graphIdToPath?: Record<string, string>;
+}
+/**
+ * Loads a graph by graphId from the filesystem.
+ * - If graphIdToPath[graphId] is set, uses that path relative to baseDir.
+ * - Otherwise resolves to baseDir/graphId.json.
+ */
+export declare class FileGraphLoader implements RuntimeGraphLoader {
+    private baseDir;
+    private graphIdToPath;
+    constructor(options?: FileGraphLoaderOptions);
+    loadGraph(graphId: string): Promise<Graph>;
+}

package/dist/src/loaders/FileGraphLoader.js

@@ -0,0 +1,31 @@
+/**
+ * Graph loader that loads graph JSON from the filesystem.
+ * Use for loading NARRIX triage graphs from a graphs/ directory.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * Loads a graph by graphId from the filesystem.
+ * - If graphIdToPath[graphId] is set, uses that path relative to baseDir.
+ * - Otherwise resolves to baseDir/graphId.json.
+ */
+export class FileGraphLoader {
+    baseDir;
+    graphIdToPath;
+    constructor(options = {}) {
+        this.baseDir =
+            options.baseDir ??
+                path.join(process.cwd(), 'graphs');
+        this.graphIdToPath = options.graphIdToPath ?? {};
+    }
+    async loadGraph(graphId) {
+        const relativePath = this.graphIdToPath[graphId] ?? `${graphId}.json`;
+        const fullPath = path.resolve(this.baseDir, relativePath);
+        const raw = await readFile(fullPath, 'utf-8');
+        const graph = JSON.parse(raw);
+        if (graph.id !== graphId && !this.graphIdToPath[graphId]) {
+            graph.id = graphId;
+        }
+        return graph;
+    }
+}

package/dist/src/playground/PlaygroundReporter.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Playground reporter: collects execution steps and in-memory debug artifacts
+ * for full visibility (graph start, plan rounds, node request/response/outputMapping, graph end).
+ *
+ * Each reporter instance corresponds to ONE graph execution.
+ * It never writes to the filesystem; callers can inspect artifacts via getArtifacts/getDebugSnapshot.
+ */
+export interface CreatePlaygroundReporterOptions {
+    /** Short run id for report header (e.g. folder name) */
+    runId?: string;
+}
+export interface PlaygroundReporter {
+    step(name: string, data?: Record<string, unknown>): void;
+    getSteps(): PlaygroundStep[];
+    getArtifacts(): PlaygroundDebugArtifact[];
+    getDebugSnapshot(): PlaygroundDebugSnapshot;
+    getMarkdown(): string;
+}
+export interface PlaygroundStep {
+    name: string;
+    data?: Record<string, unknown>;
+    ts: number;
+}
+export type PlaygroundDebugArtifactKind = 'request' | 'response';
+export interface PlaygroundDebugArtifact {
+    /** Stable in-memory identifier for UI/debug lookup. This is not a file path. */
+    artifactId: string;
+    kind: PlaygroundDebugArtifactKind;
+    nodeId: string;
+    stepNumber?: number;
+    payload: unknown;
+    ts: number;
+}
+export interface PlaygroundDebugSnapshot {
+    runId?: string;
+    steps: PlaygroundStep[];
+    artifacts: PlaygroundDebugArtifact[];
+    markdown: string;
+}
+export declare function createPlaygroundReporter(options?: CreatePlaygroundReporterOptions): PlaygroundReporter;