@ellyco/agentic 0.1.0

package/dist/graphs/iterator.d.ts

@@ -0,0 +1,138 @@
+import { ContextLayer, RuntimeContext } from ".";
+import { NodeLike } from "../nodes";
+import { TypedKeys } from "../types";
+import { Graph } from "./graph";
+import { z } from "zod";
+/**
+ * Type representing state with an index for tracking iteration position.
+ *
+ * @template Prefix - The prefix for the index key (e.g., "item" -> "itemIndex")
+ */
+type IndexState<Prefix extends string> = {
+    [K in `${Prefix}Index`]: number;
+};
+/**
+ * Type representing state with the current item being iterated over.
+ *
+ * @template Prefix - The prefix for the item key (e.g., "item" -> "itemItem")
+ * @template Item - The type of items in the array
+ */
+type ItemState<Prefix extends string, Item extends any = any> = {
+    [K in `${Prefix}Item`]: Item;
+};
+/**
+ * Type representing the complete state for iterator nodes.
+ * Combines the base state with index and item tracking.
+ *
+ * @template T - The base state object type
+ * @template Prefix - Prefix for index/item keys
+ * @template Item - Type of items being iterated
+ */
+export type IteratorNodeState<T extends object, Prefix extends string, Item extends any = any> = IndexState<Prefix> & ItemState<Prefix, Item> & T;
+/**
+ * Zod schema for index state
+ */
+type ZodIndexState<Prefix extends string> = z.ZodObject<{
+    [K in `${Prefix}Index`]: z.ZodNumber;
+}>;
+/**
+ * Zod schema for item state
+ */
+type ZodItemState<Prefix extends string, Item extends any = any> = z.ZodObject<{
+    [K in `${Prefix}Item`]: z.ZodType<Item>;
+}>;
+/**
+ * Zod schema for complete iterator node state
+ */
+type ZodIteratorNodeState<T extends z.ZodObject, Prefix extends string, Item extends any = any> = ZodIndexState<Prefix> & ZodItemState<Prefix, Item> & T;
+/**
+ * Helper type to extract keys that have array values from state
+ */
+type ArrayKeys<T> = TypedKeys<T, any[]>;
+/**
+ * A graph that iterates over an array in state, running a looped node for each item.
+ * Manages index tracking and item extraction automatically.
+ *
+ * @class Iterator
+ * @extends {Graph<T, S, NS>}
+ * @template Item - The type of items in the array
+ * @template T - The Zod schema for base state
+ * @template Prefix - Prefix for index/item state keys
+ * @template S - The inferred state type from T
+ * @template NS - The node state type including index and item
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   items: z.array(z.object({ name: z.string(), value: z.number() }))
+ * });
+ *
+ * const iterator = new Iterator(schema, "item", "items");
+ * const looped = new NodeSequence(iterator.getNodeSchema());
+ * looped.next(new FunctionNode((state) => ({
+ *   itemValue: state.itemItem.value * 2
+ * })));
+ *
+ * iterator.setLoopedNode(looped);
+ *
+ * const result = await iterator.invoke({
+ *   items: [{ name: "a", value: 1 }, { name: "b", value: 2 }]
+ * });
+ * ```
+ */
+export declare class Iterator<Item extends any, T extends z.ZodObject, Prefix extends string, S extends Record<string, unknown> = z.infer<T>, NS extends Record<string, unknown> = IteratorNodeState<S, Prefix, Item>> extends Graph<T, S, NS> {
+    protected readonly schema: T;
+    private readonly prefix;
+    private readonly iteratorKey;
+    /**
+     * Creates an iterator graph.
+     *
+     * @param {T} schema - The base state schema
+     * @param {Prefix} prefix - Prefix for index and item keys
+     * @param {ArrayKeys<z.infer<T>>} iteratorKey - The state key containing the array to iterate
+     */
+    constructor(schema: T, prefix: Prefix, iteratorKey: ArrayKeys<z.infer<T>>);
+    /**
+     * Sets the node to be executed for each item in the array.
+     *
+     * @param {NodeLike<NS> | Graph<ZodIteratorNodeState<T, Prefix, Item>, NS>} loopedNode - The node to loop
+     * @returns {this} The iterator instance for method chaining
+     */
+    setLoopedNode(loopedNode: NodeLike<NS> | Graph<ZodIteratorNodeState<T, Prefix, Item>, NS>): this;
+    /**
+     * Gets the schema for nodes being looped over.
+     * Extends the base schema with index and item tracking.
+     *
+     * @returns {ZodIteratorNodeState<T, Prefix, Item>} Schema for looped nodes
+     */
+    getNodeSchema(): ZodIteratorNodeState<T, Prefix, Item>;
+    /**
+     * Converts the graph state to node state by extracting the current item.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @param {ContextLayer} context - The execution context
+     * @returns {NS} The node state with current index and item
+     */
+    protected stateToNodeState(state: S, context: ContextLayer): NS;
+    /**
+     * Converts node state back to graph state, updating the array with modified item.
+     *
+     * @protected
+     * @param {Partial<NS>} nodeState - The partial node state
+     * @param {ContextLayer} context - The execution context
+     * @returns {S} The partial graph state
+     */
+    protected nodeStateToState(nodeState: Partial<NS>, context: ContextLayer): S;
+    /**
+     * Runs the iterator over all items in the array.
+     * Manages index tracking and item extraction for looped node execution.
+     *
+     * @param {S} input - Initial state
+     * @param {ContextLayer | RuntimeContext} contextOrRuntime - Execution context
+     * @returns {Promise<Partial<S>>} Final state with updated array
+     */
+    run(input: S, contextOrRuntime: ContextLayer | RuntimeContext): Promise<Partial<S>>;
+}
+export {};
+//# sourceMappingURL=iterator.d.ts.map

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

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

package/dist/graphs/iterator.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Iterator = void 0;
+const nodes_1 = require("../nodes");
+const graph_1 = require("./graph");
+const zod_1 = require("zod");
+/**
+ * Node name for the loop body
+ */
+const ITERATOR_LOOP_NODE = "iterator-loop";
+/**
+ * Node name for incrementing the index
+ */
+const INCREMENT_INDEX_NODE = "increment-index";
+/**
+ * A graph that iterates over an array in state, running a looped node for each item.
+ * Manages index tracking and item extraction automatically.
+ *
+ * @class Iterator
+ * @extends {Graph<T, S, NS>}
+ * @template Item - The type of items in the array
+ * @template T - The Zod schema for base state
+ * @template Prefix - Prefix for index/item state keys
+ * @template S - The inferred state type from T
+ * @template NS - The node state type including index and item
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   items: z.array(z.object({ name: z.string(), value: z.number() }))
+ * });
+ *
+ * const iterator = new Iterator(schema, "item", "items");
+ * const looped = new NodeSequence(iterator.getNodeSchema());
+ * looped.next(new FunctionNode((state) => ({
+ *   itemValue: state.itemItem.value * 2
+ * })));
+ *
+ * iterator.setLoopedNode(looped);
+ *
+ * const result = await iterator.invoke({
+ *   items: [{ name: "a", value: 1 }, { name: "b", value: 2 }]
+ * });
+ * ```
+ */
+class Iterator extends graph_1.Graph {
+    schema;
+    prefix;
+    iteratorKey;
+    /**
+     * Creates an iterator graph.
+     *
+     * @param {T} schema - The base state schema
+     * @param {Prefix} prefix - Prefix for index and item keys
+     * @param {ArrayKeys<z.infer<T>>} iteratorKey - The state key containing the array to iterate
+     */
+    constructor(schema, prefix, 
+    // Disabled for now, until I can figure out a better approach for this
+    // private readonly iteratorSelector: (state: S | NS) => Item[],
+    iteratorKey) {
+        super(schema);
+        this.schema = schema;
+        this.prefix = prefix;
+        this.iteratorKey = iteratorKey;
+        this.nodes[INCREMENT_INDEX_NODE] = new nodes_1.FunctionNode((_, context) => {
+            const indexContext = context.custom.indexCtx;
+            indexContext.currentNode = (Number(indexContext.currentNode) + 1).toString();
+            return {};
+        });
+        this.conditionalEdges[graph_1.START] = [ITERATOR_LOOP_NODE, graph_1.END];
+        this.conditionalFuncs[graph_1.START] = (state) => {
+            const iterator = state[this.iteratorKey];
+            return iterator.length > 0 ? ITERATOR_LOOP_NODE : graph_1.END;
+        };
+        this.conditionalEdges[ITERATOR_LOOP_NODE] = [INCREMENT_INDEX_NODE, graph_1.END];
+        this.conditionalFuncs[ITERATOR_LOOP_NODE] = (state, context) => {
+            const indexContext = context.custom.indexCtx;
+            const index = Number(indexContext.currentNode);
+            const iterator = state[this.iteratorKey];
+            return index < iterator.length - 1 ? INCREMENT_INDEX_NODE : graph_1.END;
+        };
+        this.edges[INCREMENT_INDEX_NODE] = ITERATOR_LOOP_NODE;
+    }
+    /**
+     * Sets the node to be executed for each item in the array.
+     *
+     * @param {NodeLike<NS> | Graph<ZodIteratorNodeState<T, Prefix, Item>, NS>} loopedNode - The node to loop
+     * @returns {this} The iterator instance for method chaining
+     */
+    setLoopedNode(loopedNode) {
+        this.nodes[ITERATOR_LOOP_NODE] = loopedNode;
+        return this;
+    }
+    /**
+     * Gets the schema for nodes being looped over.
+     * Extends the base schema with index and item tracking.
+     *
+     * @returns {ZodIteratorNodeState<T, Prefix, Item>} Schema for looped nodes
+     */
+    getNodeSchema() {
+        return zod_1.z.object({
+            [`${this.prefix}Index`]: zod_1.z.number(),
+            [`${this.prefix}Item`]: this.schema.shape[this.iteratorKey],
+        });
+    }
+    /**
+     * Converts the graph state to node state by extracting the current item.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @param {ContextLayer} context - The execution context
+     * @returns {NS} The node state with current index and item
+     */
+    stateToNodeState(state, context) {
+        const indexContext = context.custom.indexCtx;
+        const index = Number(indexContext.currentNode);
+        const iterator = state[this.iteratorKey];
+        if (iterator === undefined) {
+            throw new Error(`Selected iterator is not found`);
+        }
+        if (!Array.isArray(iterator)) {
+            throw new Error(`Seletected iterator is not an array`);
+        }
+        const item = iterator[index];
+        if (item === undefined) {
+            throw new Error(`Item ${index} not found`);
+        }
+        return {
+            ...state,
+            [`${this.prefix}Index`]: index,
+            [`${this.prefix}Item`]: item,
+        };
+    }
+    /**
+     * Converts node state back to graph state, updating the array with modified item.
+     *
+     * @protected
+     * @param {Partial<NS>} nodeState - The partial node state
+     * @param {ContextLayer} context - The execution context
+     * @returns {S} The partial graph state
+     */
+    nodeStateToState(nodeState, context) {
+        const arr = context.custom.arr;
+        const indexContext = context.custom.indexCtx;
+        const index = Number(indexContext.currentNode);
+        if (`${this.prefix}Item` in nodeState) {
+            const { [`${this.prefix}Item`]: item, ...rest } = nodeState;
+            arr[index] = item;
+            delete rest[`${this.prefix}Index`];
+            return rest;
+        }
+        return nodeState;
+    }
+    /**
+     * Runs the iterator over all items in the array.
+     * Manages index tracking and item extraction for looped node execution.
+     *
+     * @param {S} input - Initial state
+     * @param {ContextLayer | RuntimeContext} contextOrRuntime - Execution context
+     * @returns {Promise<Partial<S>>} Final state with updated array
+     */
+    async run(input, contextOrRuntime) {
+        let state = structuredClone(input);
+        if (this.nodes[ITERATOR_LOOP_NODE] === undefined) {
+            throw new Error(`Looped node is not set`);
+        }
+        const indexContext = contextOrRuntime.nextLayer();
+        if (indexContext.currentNode === undefined) {
+            indexContext.currentNode = "0";
+        }
+        const context = indexContext.nextLayer();
+        if (context.currentNode === undefined) {
+            context.currentNode = graph_1.START;
+        }
+        context.custom.indexCtx = indexContext;
+        context.custom.arr = state[this.iteratorKey];
+        const result = await this.runInternal(state, context);
+        context.done();
+        indexContext.done();
+        return { ...result, [this.iteratorKey]: structuredClone(context.custom.arr) };
+    }
+}
+exports.Iterator = Iterator;
+//# sourceMappingURL=iterator.js.map

package/dist/graphs/iterator.js.map

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

package/dist/graphs/merge-state.d.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+/**
+ * Merges partial state updates into a base state object.
+ * Uses registered custom merge strategies for specific types.
+ * Falls back to standard object/array merge behavior.
+ *
+ * @template T - The state object type
+ * @param {T} base - The base state to merge into
+ * @param {Partial<T>} changes - Partial state with updates
+ * @param {z.ZodObject} schema - Zod schema for the state type
+ * @returns {T} Merged state object
+ *
+ * @example
+ * ```typescript
+ * const base = { count: 5, items: [1, 2, 3] };
+ * const changes = { count: 10, items: [4] };
+ * const merged = mergeState(base, changes, schema);
+ * // Results in { count: 10, items: [4] }
+ * ```
+ */
+export declare function mergeState<T extends Record<string, any>>(base: T, changes: Partial<T>, schema: z.ZodObject): T;
+//# sourceMappingURL=merge-state.d.ts.map

package/dist/graphs/merge-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-state.d.ts","sourceRoot":"","sources":["../../src/graphs/merge-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,SAAS,GAAG,CAAC,CA4B9G"}

package/dist/graphs/merge-state.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeState = mergeState;
+const registry_1 = require("./registry");
+/**
+ * Merges partial state updates into a base state object.
+ * Uses registered custom merge strategies for specific types.
+ * Falls back to standard object/array merge behavior.
+ *
+ * @template T - The state object type
+ * @param {T} base - The base state to merge into
+ * @param {Partial<T>} changes - Partial state with updates
+ * @param {z.ZodObject} schema - Zod schema for the state type
+ * @returns {T} Merged state object
+ *
+ * @example
+ * ```typescript
+ * const base = { count: 5, items: [1, 2, 3] };
+ * const changes = { count: 10, items: [4] };
+ * const merged = mergeState(base, changes, schema);
+ * // Results in { count: 10, items: [4] }
+ * ```
+ */
+function mergeState(base, changes, schema) {
+    const acc = structuredClone(base);
+    for (const [key, value] of Object.entries(changes)) {
+        // if there's nothing already present for the key, then we just set the value
+        if (acc[key] === undefined || acc[key] === null) {
+            acc[key] = value;
+            continue;
+        }
+        // if there's a registered merge function, then we assume the function handles the entirety of the value, including any nested values
+        if (registry_1.STATE_MERGE.has(schema.shape[key])) {
+            acc[key] = registry_1.STATE_MERGE.get(schema.shape[key]).merge(acc[key], value);
+            continue;
+        }
+        if (typeof value === "object") {
+            if (Array.isArray(acc[key])) {
+                acc[key] = value;
+            }
+            else {
+                acc[key] = mergeState(acc[key], value, schema.shape[key]);
+            }
+        }
+        else {
+            if (registry_1.STATE_MERGE.has(schema.shape[key]) && acc[key] !== undefined) {
+                acc[key] = registry_1.STATE_MERGE.get(schema.shape[key]).merge(acc[key], value);
+            }
+            else {
+                acc[key] = value;
+            }
+        }
+    }
+    return acc;
+}
+//# sourceMappingURL=merge-state.js.map

package/dist/graphs/merge-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-state.js","sourceRoot":"","sources":["../../src/graphs/merge-state.ts"],"names":[],"mappings":";;AAsBA,gCA4BC;AAjDD,yCAAyC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAgB,UAAU,CAAgC,IAAO,EAAE,OAAmB,EAAE,MAAmB;IACvG,MAAM,GAAG,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IAClC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACjD,6EAA6E;QAC7E,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC;YAC7C,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC1C,SAAS;QACb,CAAC;QACD,qIAAqI;QACrI,IAAI,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;YACpC,GAA2B,CAAC,GAAG,CAAC,GAAG,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YAC/F,SAAS;QACb,CAAC;QACD,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBACzB,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACH,GAA2B,CAAC,GAAG,CAAC,GAAG,UAAU,CAAE,GAA2B,CAAC,GAAG,CAAC,EAAE,KAAmB,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC,CAAC;YAC7I,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,IAAI,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,SAAS,EAAE,CAAC;gBAC9D,GAA2B,CAAC,GAAG,CAAC,GAAG,sBAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;YACnG,CAAC;iBAAM,CAAC;gBACH,GAA2B,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC9C,CAAC;QACL,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/graphs/node-sequence.d.ts

@@ -0,0 +1,63 @@
+import { type NodeLike } from "../nodes";
+import { Graph } from "./graph";
+import { z } from "zod";
+/**
+ * A graph that executes a sequence of nodes linearly.
+ * Nodes are executed one after another without branching.
+ * Each call to next() adds a node to the sequence.
+ *
+ * @class NodeSequence
+ * @extends {Graph<T, S>}
+ * @template T - The Zod schema for state
+ * @template S - The inferred state type from T
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ count: z.number() });
+ * const sequence = new NodeSequence(schema);
+ *
+ * sequence
+ *   .next(new FunctionNode((state) => ({ count: state.count + 1 })))
+ *   .next(new FunctionNode((state) => ({ count: state.count * 2 })));
+ *
+ * const result = await sequence.invoke({ count: 5 });
+ * // State transitions: 5 -> 6 -> 12
+ * ```
+ */
+export declare class NodeSequence<T extends z.ZodObject, S extends Record<string, unknown> = z.infer<T>> extends Graph<T, S> {
+    /**
+     * NodeSequence doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @returns {S} The same state (no transformation)
+     */
+    protected stateToNodeState(state: S): S;
+    /**
+     * NodeSequence doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {Partial<S>} nodeState - The partial node state
+     * @returns {Partial<S>} The same partial state (no transformation)
+     */
+    protected nodeStateToState(nodeState: Partial<S>): Partial<S>;
+    /**
+     * Adds the next node in the sequence.
+     * Automatically wires up edges from START to the first node,
+     * between sequential nodes, and from the last node to END.
+     *
+     * @param {NodeLike<S> | Graph<T, S>} node - The node to add
+     * @returns {this} The sequence instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const sequence = new NodeSequence(schema);
+     * sequence
+     *   .next(node1)
+     *   .next(node2)
+     *   .next(node3);
+     * ```
+     */
+    next(node: NodeLike<S> | Graph<T, S>): this;
+}
+//# sourceMappingURL=node-sequence.d.ts.map

package/dist/graphs/node-sequence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sequence.d.ts","sourceRoot":"","sources":["../../src/graphs/node-sequence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAO,KAAK,EAAS,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,CAAC,CAAC,SAAS,EAAE,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC;IAEhH;;;;;;OAMG;IACH,SAAS,CAAC,gBAAgB,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC;IAIvC;;;;;;OAMG;IACH,SAAS,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAI7D;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,IAAI;CAgB9C"}

package/dist/graphs/node-sequence.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NodeSequence = void 0;
+const graph_1 = require("./graph");
+/**
+ * A graph that executes a sequence of nodes linearly.
+ * Nodes are executed one after another without branching.
+ * Each call to next() adds a node to the sequence.
+ *
+ * @class NodeSequence
+ * @extends {Graph<T, S>}
+ * @template T - The Zod schema for state
+ * @template S - The inferred state type from T
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({ count: z.number() });
+ * const sequence = new NodeSequence(schema);
+ *
+ * sequence
+ *   .next(new FunctionNode((state) => ({ count: state.count + 1 })))
+ *   .next(new FunctionNode((state) => ({ count: state.count * 2 })));
+ *
+ * const result = await sequence.invoke({ count: 5 });
+ * // State transitions: 5 -> 6 -> 12
+ * ```
+ */
+class NodeSequence extends graph_1.Graph {
+    /**
+     * NodeSequence doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {S} state - The graph state
+     * @returns {S} The same state (no transformation)
+     */
+    stateToNodeState(state) {
+        return state;
+    }
+    /**
+     * NodeSequence doesn't transform state, so node state is the same as graph state.
+     *
+     * @protected
+     * @param {Partial<S>} nodeState - The partial node state
+     * @returns {Partial<S>} The same partial state (no transformation)
+     */
+    nodeStateToState(nodeState) {
+        return nodeState;
+    }
+    /**
+     * Adds the next node in the sequence.
+     * Automatically wires up edges from START to the first node,
+     * between sequential nodes, and from the last node to END.
+     *
+     * @param {NodeLike<S> | Graph<T, S>} node - The node to add
+     * @returns {this} The sequence instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const sequence = new NodeSequence(schema);
+     * sequence
+     *   .next(node1)
+     *   .next(node2)
+     *   .next(node3);
+     * ```
+     */
+    next(node) {
+        const nodeCount = Object.keys(this.nodes).length;
+        const name = `node-${nodeCount}`;
+        const isFirstNode = nodeCount === 0;
+        this.nodes[name] = node;
+        if (isFirstNode) {
+            this.edges[graph_1.START] = name;
+            this.edges[name] = graph_1.END;
+        }
+        else {
+            const previousNodeName = `node-${nodeCount - 1}`;
+            this.edges[previousNodeName] = name;
+            this.edges[name] = graph_1.END;
+        }
+        return this;
+    }
+}
+exports.NodeSequence = NodeSequence;
+//# sourceMappingURL=node-sequence.js.map

package/dist/graphs/node-sequence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-sequence.js","sourceRoot":"","sources":["../../src/graphs/node-sequence.ts"],"names":[],"mappings":";;;AACA,mCAA4C;AAG5C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAa,YAAoF,SAAQ,aAAW;IAEhH;;;;;;OAMG;IACO,gBAAgB,CAAC,KAAQ;QAC/B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;OAMG;IACO,gBAAgB,CAAC,SAAqB;QAC5C,OAAO,SAAS,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CAAC,IAA+B;QAChC,MAAM,SAAS,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;QACjD,MAAM,IAAI,GAAG,QAAQ,SAAS,EAAE,CAAC;QACjC,MAAM,WAAW,GAAG,SAAS,KAAK,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAExB,IAAI,WAAW,EAAE,CAAC;YACd,IAAI,CAAC,KAAK,CAAC,aAAK,CAAC,GAAG,IAAI,CAAC;YACzB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,WAAG,CAAC;QAC3B,CAAC;aAAM,CAAC;YACJ,MAAM,gBAAgB,GAAG,QAAQ,SAAS,GAAG,CAAC,EAAE,CAAC;YACjD,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC;YACpC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,WAAG,CAAC;QAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IAChB,CAAC;CACJ;AAzDD,oCAyDC"}

package/dist/graphs/registry.d.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const STATE_MERGE: z.core.$ZodRegistry<{
+    merge: (old: z.$output, change: Partial<z.$output>) => z.$output;
+}, z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/graphs/registry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,WAAW;WAAuB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,OAAO;iFAAK,CAAC"}

package/dist/graphs/registry.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATE_MERGE = void 0;
+const zod_1 = require("zod");
+exports.STATE_MERGE = zod_1.z.registry();
+//# sourceMappingURL=registry.js.map

package/dist/graphs/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/graphs/registry.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAEX,QAAA,WAAW,GAAG,OAAC,CAAC,QAAQ,EAAwE,CAAC"}