@ellyco/agentic 0.1.0

package/dist/graphs/graph.d.ts

@@ -0,0 +1,218 @@
+import { type NodeLike } from "../nodes/types";
+import { type GraphResult } from "./types";
+import { ContextLayer, RuntimeContext } from "./runtime-context";
+import { BaseStore } from "./store/base-store";
+import { z } from "zod";
+/**
+ * Utility type to get all but the first element of a tuple.
+ */
+export type Tail<T extends unknown[]> = T extends [unknown, ...infer R] ? R : [];
+/**
+ * Special node name indicating the start of graph execution
+ */
+export declare const START = "start";
+/**
+ * Special node name indicating the end of graph execution
+ */
+export declare const END = "end";
+/**
+ * Configuration for invoking a graph without persistence.
+ *
+ * @interface RunConfig
+ * @property {string} [resumeFrom] - Cursor to resume from a previous interruption
+ * @property {string} [runId] - Custom run ID (generated if not provided)
+ */
+export interface RunConfig {
+    resumeFrom?: string;
+    runId?: string;
+}
+/**
+ * Configuration for invoking a graph with persistence to a store.
+ *
+ * @interface StoredRunConfig
+ * @property {BaseStore} store - Store to persist run state to
+ * @property {string} [runId] - Custom run ID (generated if not provided)
+ * @property {boolean} [deleteAfterEnd] - If true, delete the run from store when graph completes
+ */
+export interface StoredRunConfig {
+    store: BaseStore;
+    runId?: string;
+    deleteAfterEnd?: boolean;
+}
+/**
+ * Type for a constructor that derives schema from a base schema.
+ * Used to mark constructors that can generate derived schemas for specific purposes.
+ */
+export type DerivedSchemaConstructorType<T> = ((schema: z.ZodObject) => T) & {
+    derives: true;
+};
+/**
+ * Marks a constructor function as deriving a schema from a base schema.
+ *
+ * @template T - The type returned by the constructor
+ * @param {(schema: z.ZodObject) => T} constructor - The constructor function
+ * @returns {DerivedSchemaConstructorType<T>} The marked constructor
+ *
+ * @example
+ * ```typescript
+ * const myConstructor = DerivedSchemaConstructor((schema) => {
+ *   return new MyClass(schema);
+ * });
+ * ```
+ */
+export declare const DerivedSchemaConstructor: <T>(constructor: (schema: z.ZodObject) => T) => DerivedSchemaConstructorType<T>;
+/**
+ * Abstract base class for stateful graphs consisting of nodes and edges.
+ * Graphs orchestrate execution flow through nodes, managing state transformations.
+ * Supports conditional edges, nesting of graphs, and checkpointing via interrupts.
+ *
+ * @abstract
+ * @template Z - The Zod schema for graph state
+ * @template S - The inferred state type from Z (defaults to z.infer<Z>)
+ * @template NS - The node-state type for internal node operations (defaults to S)
+ *
+ * @property {boolean} isGraph - Always true, used to identify graph instances
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   input: z.string(),
+ *   output: z.string().optional()
+ * });
+ *
+ * class MyGraph extends Graph<typeof schema> {
+ *   protected stateToNodeState(state) { return state; }
+ *   protected nodeStateToState(nodeState) { return nodeState; }
+ *
+ *   constructor() {
+ *     super(schema);
+ *     this.addNode("process", new FunctionNode(...));
+ *     this.addEdge("start", "process");
+ *     this.addEdge("process", "end");
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class Graph<Z extends z.ZodObject, S extends Record<string, unknown> = z.infer<Z>, NS extends Record<string, unknown> = S> implements NodeLike<S> {
+    protected readonly schema: Z;
+    /**
+     * Marker property to identify Graph instances
+     */
+    readonly isGraph = true;
+    /**
+     * Mapping of node names to node implementations
+     */
+    protected nodes: Record<string, NodeLike<NS>>;
+    /**
+     * Mapping of source nodes to destination nodes for simple edges
+     */
+    protected edges: Record<string, string>;
+    /**
+     * Mapping of source nodes to possible destination nodes for conditional edges
+     */
+    protected conditionalEdges: Record<string, string[]>;
+    /**
+     * Mapping of source nodes to functions that determine the destination for conditional edges
+     */
+    protected conditionalFuncs: Record<string, (state: NS, context: ContextLayer) => string>;
+    /**
+     * Converts graph state to node state before passing to nodes.
+     * Useful for normalizing state across graph boundaries.
+     *
+     * @protected
+     * @abstract
+     * @param {S} state - The graph state
+     * @param {ContextLayer} context - The execution context
+     * @returns {NS} The node state
+     */
+    protected abstract stateToNodeState(state: S, context: ContextLayer): NS;
+    /**
+     * Converts node state back to graph state after node execution.
+     *
+     * @protected
+     * @abstract
+     * @param {Partial<NS>} nodeState - The partial node state from a node
+     * @param {ContextLayer} context - The execution context
+     * @returns {Partial<S>} The partial graph state
+     */
+    protected abstract nodeStateToState(nodeState: Partial<NS>, context: ContextLayer): Partial<S>;
+    /**
+     * Creates a new graph instance.
+     *
+     * @param {Z} schema - Zod schema for validating and typing the graph state
+     */
+    constructor(schema: Z);
+    /**
+     * Determines the next node based on current node and state.
+     * Handles both simple edges and conditional edges.
+     *
+     * @protected
+     * @param {S} state - Current state
+     * @param {ContextLayer} context - Execution context
+     * @throws {Error} If no edge is found from current node
+     */
+    protected transition(state: S, context: ContextLayer): void;
+    /**
+     * Executes a single node and merges its output into the state.
+     *
+     * @protected
+     * @param {S} state - Current state
+     * @param {ContextLayer} context - Execution context
+     * @returns {Promise<S>} Updated state
+     * @throws {Error} If node is not found
+     */
+    protected step(state: S, context: ContextLayer): Promise<S>;
+    /**
+     * Validates the graph structure.
+     * Ensures START and END nodes have proper connections.
+     *
+     * @throws {Error} If graph structure is invalid
+     */
+    validate(): void;
+    /**
+     * Internal execution loop for the graph.
+     * Runs nodes in sequence following edges until END is reached or interrupted.
+     *
+     * @protected
+     * @param {S} input - Initial state
+     * @param {ContextLayer} context - Execution context
+     * @returns {Promise<Partial<S>>} Final state changes
+     */
+    protected runInternal(input: S, context: ContextLayer): Promise<Partial<S>>;
+    /**
+     * Merges partial state into the base state using the schema.
+     *
+     * @protected
+     * @param {S} state - Base state
+     * @param {Partial<S>} partial - Partial updates
+     * @returns {S} Merged state
+     */
+    protected mergeState(state: S, partial: Partial<S>): S;
+    /**
+     * Runs the graph with the provided context.
+     * Sets up initial node if not already set, runs internal loop, and cleans up.
+     *
+     * @param {S} input - Initial state
+     * @param {ContextLayer | RuntimeContext} contextOrRuntime - Execution context or runtime
+     * @returns {Promise<Partial<S>>} Final state changes
+     */
+    run(input: S, contextOrRuntime: ContextLayer | RuntimeContext): Promise<Partial<S>>;
+    /**
+     * Invokes the graph and returns the final result.
+     * Supports both in-memory and stored (persistent) execution.
+     *
+     * @overload
+     * @param {S} input - Initial state
+     * @param {RunConfig} [config] - Run configuration
+     * @returns {Promise<GraphResult<S>>} Result with final state and exit reason
+     */
+    invoke(input: S, config?: RunConfig): Promise<GraphResult<S>>;
+    /**
+     * @overload
+     * @param {Partial<S>} input - Partial initial state (for stored runs)
+     * @param {StoredRunConfig} config - Configuration with store for persistence
+     * @returns {Promise<GraphResult<S>>} Result with final state and exit reason
+     */
+    invoke(input: Partial<S>, config?: StoredRunConfig): Promise<GraphResult<S>>;
+}
+//# sourceMappingURL=graph.d.ts.map

package/dist/graphs/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../../src/graphs/graph.ts"],"names":[],"mappings":"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"}

package/dist/graphs/graph.js

@@ -0,0 +1,334 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Graph = exports.DerivedSchemaConstructor = exports.END = exports.START = void 0;
+const runtime_context_1 = require("./runtime-context");
+const cuid2_1 = require("@paralleldrive/cuid2");
+const merge_state_1 = require("./merge-state");
+/**
+ * Special node name indicating the start of graph execution
+ */
+exports.START = "start";
+/**
+ * Special node name indicating the end of graph execution
+ */
+exports.END = "end";
+/**
+ * Type guard to check if config is StoredRunConfig
+ *
+ * @private
+ */
+function isStoredRunConfig(config) {
+    return "store" in config;
+}
+/**
+ * Marks a constructor function as deriving a schema from a base schema.
+ *
+ * @template T - The type returned by the constructor
+ * @param {(schema: z.ZodObject) => T} constructor - The constructor function
+ * @returns {DerivedSchemaConstructorType<T>} The marked constructor
+ *
+ * @example
+ * ```typescript
+ * const myConstructor = DerivedSchemaConstructor((schema) => {
+ *   return new MyClass(schema);
+ * });
+ * ```
+ */
+const DerivedSchemaConstructor = (constructor) => {
+    Object.defineProperty(constructor, "derives", { value: true });
+    return constructor;
+};
+exports.DerivedSchemaConstructor = DerivedSchemaConstructor;
+/**
+ * Abstract base class for stateful graphs consisting of nodes and edges.
+ * Graphs orchestrate execution flow through nodes, managing state transformations.
+ * Supports conditional edges, nesting of graphs, and checkpointing via interrupts.
+ *
+ * @abstract
+ * @template Z - The Zod schema for graph state
+ * @template S - The inferred state type from Z (defaults to z.infer<Z>)
+ * @template NS - The node-state type for internal node operations (defaults to S)
+ *
+ * @property {boolean} isGraph - Always true, used to identify graph instances
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   input: z.string(),
+ *   output: z.string().optional()
+ * });
+ *
+ * class MyGraph extends Graph<typeof schema> {
+ *   protected stateToNodeState(state) { return state; }
+ *   protected nodeStateToState(nodeState) { return nodeState; }
+ *
+ *   constructor() {
+ *     super(schema);
+ *     this.addNode("process", new FunctionNode(...));
+ *     this.addEdge("start", "process");
+ *     this.addEdge("process", "end");
+ *   }
+ * }
+ * ```
+ */
+class Graph {
+    schema;
+    /**
+     * Marker property to identify Graph instances
+     */
+    isGraph = true;
+    /**
+     * Mapping of node names to node implementations
+     */
+    nodes = {};
+    /**
+     * Mapping of source nodes to destination nodes for simple edges
+     */
+    edges = {};
+    /**
+     * Mapping of source nodes to possible destination nodes for conditional edges
+     */
+    conditionalEdges = {};
+    /**
+     * Mapping of source nodes to functions that determine the destination for conditional edges
+     */
+    conditionalFuncs = {};
+    /**
+     * Creates a new graph instance.
+     *
+     * @param {Z} schema - Zod schema for validating and typing the graph state
+     */
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /**
+     * Determines the next node based on current node and state.
+     * Handles both simple edges and conditional edges.
+     *
+     * @protected
+     * @param {S} state - Current state
+     * @param {ContextLayer} context - Execution context
+     * @throws {Error} If no edge is found from current node
+     */
+    transition(state, context) {
+        const currentNode = context.currentNode;
+        if (currentNode in this.edges) {
+            context.currentNode = this.edges[currentNode];
+        }
+        else if (currentNode in this.conditionalEdges) {
+            const conditionalEdges = this.conditionalEdges[currentNode];
+            const condition = this.conditionalFuncs[currentNode](this.stateToNodeState(state, context), context);
+            if (conditionalEdges.includes(condition)) {
+                context.currentNode = condition;
+            }
+            else {
+                throw new Error(`No edge found for after node ${currentNode} with condition ${condition}`);
+            }
+        }
+        else {
+            throw new Error(`No edge or conditional edge found for after node ${currentNode}`);
+        }
+    }
+    /**
+     * Executes a single node and merges its output into the state.
+     *
+     * @protected
+     * @param {S} state - Current state
+     * @param {ContextLayer} context - Execution context
+     * @returns {Promise<S>} Updated state
+     * @throws {Error} If node is not found
+     */
+    async step(state, context) {
+        const currentNode = context.currentNode;
+        const node = this.nodes[currentNode];
+        if (node === undefined) {
+            throw new Error(`Node ${currentNode} not found`);
+        }
+        const inputNodeState = this.stateToNodeState(structuredClone(state), context);
+        const result = await node.run(structuredClone(inputNodeState), context);
+        if (Object.keys(result).length === 0) {
+            return state;
+        }
+        return this.mergeState(state, this.nodeStateToState(result, context));
+    }
+    /**
+     * Validates the graph structure.
+     * Ensures START and END nodes have proper connections.
+     *
+     * @throws {Error} If graph structure is invalid
+     */
+    validate() {
+        if (!(exports.START in this.edges) && !(exports.START in this.conditionalEdges)) {
+            throw new Error(`No edge or conditional edge found for starting node ${exports.START}`);
+        }
+        let endIsSet = false;
+        for (const to of Object.values(this.edges)) {
+            if (to === exports.END) {
+                endIsSet = true;
+            }
+        }
+        for (const to of Object.values(this.conditionalEdges).flat()) {
+            if (to.includes(exports.END)) {
+                endIsSet = true;
+            }
+        }
+        if (!endIsSet) {
+            throw new Error(`No edge or conditional edge found for ending node ${exports.END}`);
+        }
+    }
+    /**
+     * Internal execution loop for the graph.
+     * Runs nodes in sequence following edges until END is reached or interrupted.
+     *
+     * @protected
+     * @param {S} input - Initial state
+     * @param {ContextLayer} context - Execution context
+     * @returns {Promise<Partial<S>>} Final state changes
+     */
+    async runInternal(input, context) {
+        let state = structuredClone(input);
+        let shouldContinue = true;
+        while (shouldContinue) {
+            const currentNode = context.currentNode;
+            // End is not a real node, it's just a way to stop the state machine.
+            if (currentNode === exports.END) {
+                shouldContinue = false;
+                break;
+            }
+            // Start is not a real node, it's just a way to start the state machine.
+            if (currentNode === exports.START) {
+                this.transition(input, context);
+                continue;
+            }
+            state = { ...state, ...(await this.step(structuredClone(state), context)) };
+            if (context.runtime.interrupted) {
+                shouldContinue = false;
+                break;
+            }
+            this.transition(state, context);
+        }
+        return state;
+    }
+    /**
+     * Merges partial state into the base state using the schema.
+     *
+     * @protected
+     * @param {S} state - Base state
+     * @param {Partial<S>} partial - Partial updates
+     * @returns {S} Merged state
+     */
+    mergeState(state, partial) {
+        return (0, merge_state_1.mergeState)(state, partial, this.schema);
+    }
+    /**
+     * Runs the graph with the provided context.
+     * Sets up initial node if not already set, runs internal loop, and cleans up.
+     *
+     * @param {S} input - Initial state
+     * @param {ContextLayer | RuntimeContext} contextOrRuntime - Execution context or runtime
+     * @returns {Promise<Partial<S>>} Final state changes
+     */
+    async run(input, contextOrRuntime) {
+        const context = contextOrRuntime.nextLayer();
+        if (context.currentNode === undefined) {
+            context.currentNode = exports.START;
+        }
+        const result = await this.runInternal(input, context);
+        context.done();
+        return result;
+    }
+    /**
+     * Invokes the graph with the given input and optional configuration.
+     * Handles both in-memory and stored (persistent) execution modes.
+     *
+     * For in-memory mode (RunConfig): State is not persisted between invocations.
+     * Can be resumed using a cursor from a previous interruption.
+     *
+     * For stored mode (StoredRunConfig): State is persisted to the provided store.
+     * Allows resuming execution from checkpoints across different invocations.
+     *
+     * @param {S | Partial<S>} input - Initial or partial state
+     * @param {RunConfig | StoredRunConfig} [config] - Configuration
+     * @returns {Promise<GraphResult<S>>} Result object containing final state and exit reason
+     * @throws {Error} If graph structure validation fails
+     *
+     * @example
+     * ```typescript
+     * // In-memory execution
+     * const result = await graph.invoke(initialState);
+     *
+     * // With resumption
+     * if (result.exitReason === "interrupt") {
+     *   const result2 = await graph.invoke(result.state, { resumeFrom: result.cursor });
+     * }
+     *
+     * // With persistence
+     * const result = await graph.invoke(state, { store: myStore });
+     * ```
+     */
+    async invoke(input, config) {
+        const runId = (config && "runId" in config ? config.runId : (0, cuid2_1.createId)());
+        if (config && isStoredRunConfig(config)) {
+            const partialInput = input;
+            const storedRun = config.store.getStoredRun(runId);
+            const runtime = new runtime_context_1.RuntimeContext(runId, storedRun);
+            let mergedState = partialInput;
+            const stateExists = await storedRun.exists();
+            if (stateExists) {
+                const load = await storedRun.load();
+                mergedState = this.mergeState(mergedState, load.state);
+                runtime.unwrapCursor(load.cursor);
+            }
+            const state = this.schema.parse(mergedState);
+            const result = await this.run(state, runtime);
+            const finalState = { ...state, ...result };
+            if (runtime.interrupted) {
+                await storedRun.save(runtime.wrapCursor(), finalState);
+                return {
+                    runId,
+                    state: finalState,
+                    exitReason: "interrupt",
+                    exitMessage: runtime.exitMessage,
+                    cursor: runtime.wrapCursor(),
+                };
+            }
+            if (config?.deleteAfterEnd) {
+                await storedRun.delete();
+            }
+            else {
+                await storedRun.save(exports.END, finalState);
+            }
+            return {
+                runId,
+                state: finalState,
+                exitReason: "end",
+            };
+        }
+        else {
+            const fullInput = input;
+            const runtime = new runtime_context_1.RuntimeContext(runId);
+            if (config?.resumeFrom) {
+                runtime.unwrapCursor(config.resumeFrom);
+            }
+            const state = this.schema.parse(fullInput);
+            const result = await this.run(state, runtime);
+            const finalState = { ...state, ...result };
+            if (runtime.interrupted) {
+                return {
+                    runId,
+                    state: finalState,
+                    exitReason: "interrupt",
+                    exitMessage: runtime.exitMessage,
+                    cursor: runtime.wrapCursor(),
+                };
+            }
+            return {
+                runId,
+                state: finalState,
+                exitReason: "end",
+            };
+        }
+    }
+}
+exports.Graph = Graph;
+//# sourceMappingURL=graph.js.map

package/dist/graphs/graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.js","sourceRoot":"","sources":["../../src/graphs/graph.ts"],"names":[],"mappings":"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"}

package/dist/graphs/index.d.ts

@@ -0,0 +1,7 @@
+export { StateMachine } from "./state-machine";
+export { type GraphResult } from "./types";
+export { NodeSequence } from "./node-sequence";
+export { Iterator } from "./iterator";
+export { RuntimeContext, ContextLayer } from "./runtime-context";
+export { STATE_MERGE } from "./registry";
+//# sourceMappingURL=index.d.ts.map

package/dist/graphs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/graphs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/graphs/index.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_MERGE = exports.ContextLayer = exports.RuntimeContext = exports.Iterator = exports.NodeSequence = exports.StateMachine = void 0;
+var state_machine_1 = require("./state-machine");
+Object.defineProperty(exports, "StateMachine", { enumerable: true, get: function () { return state_machine_1.StateMachine; } });
+var node_sequence_1 = require("./node-sequence");
+Object.defineProperty(exports, "NodeSequence", { enumerable: true, get: function () { return node_sequence_1.NodeSequence; } });
+var iterator_1 = require("./iterator");
+Object.defineProperty(exports, "Iterator", { enumerable: true, get: function () { return iterator_1.Iterator; } });
+var runtime_context_1 = require("./runtime-context");
+Object.defineProperty(exports, "RuntimeContext", { enumerable: true, get: function () { return runtime_context_1.RuntimeContext; } });
+Object.defineProperty(exports, "ContextLayer", { enumerable: true, get: function () { return runtime_context_1.ContextLayer; } });
+var registry_1 = require("./registry");
+Object.defineProperty(exports, "STATE_MERGE", { enumerable: true, get: function () { return registry_1.STATE_MERGE; } });
+//# sourceMappingURL=index.js.map

package/dist/graphs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/graphs/index.ts"],"names":[],"mappings":";;;AAAA,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AAErB,iDAA+C;AAAtC,6GAAA,YAAY,OAAA;AACrB,uCAAsC;AAA7B,oGAAA,QAAQ,OAAA;AACjB,qDAAiE;AAAxD,iHAAA,cAAc,OAAA;AAAE,+GAAA,YAAY,OAAA;AACrC,uCAAyC;AAAhC,uGAAA,WAAW,OAAA"}