@spendgraph/graph 0.2.0

package/README.md

@@ -0,0 +1,87 @@
+# @spendgraph/graph
+
+Wire nodes into a graph, run it, and get back a rollout with every step.
+
+```sh
+npm install @spendgraph/graph
+```
+
+Four things are exported. Everything else hangs off what they return.
+
+```ts
+import { graph, node, edge, end } from "@spendgraph/graph";
+```
+
+## A node
+
+One unit of work. `input` is what makes it reusable: the node says what it
+needs, the graph says where it comes from. Without that, every node has to know
+about the whole run.
+
+```ts
+const classify = node({
+  name: "classify",
+  args: [
+    { name: "text", type: "string", required: true },
+    { name: "top_k", type: "number", required: false },
+  ] as const,
+  input: (ctx) => ({ text: ctx.values.question }),
+  run: ({ text, top_k }) => model.classify(text, top_k ?? 3),
+});
+```
+
+**Write `as const` and `run` types itself** from the args — `text` a string,
+`top_k` a number, optionals optional. Rename an argument and the handler stops
+compiling, rather than being handed `undefined` halfway through a graph, which
+is the most expensive place to find a typo.
+
+Args are validated before `run` does any work.
+
+## Wiring
+
+```ts
+const flow = graph({
+  start: "classify",
+  nodes: [classify, lookup, answer],
+  edges: [
+    edge("classify", (ctx) => (ctx.outputs.classify === "billing" ? "lookup" : "answer")),
+    edge("lookup", "answer"),
+    end("answer"),
+  ],
+});
+
+const result = await flow.execute({ question: "Why was I charged twice?" });
+```
+
+An edge says what runs next; a node's `input` says on what. Compilation checks
+the wiring — an edge to a node that does not exist, a node nothing reaches, a
+cycle — before anything runs.
+
+## What comes back
+
+```ts
+result.status;    // "completed" | "failed"
+result.output;    // the last node's return, stringified
+result.steps;     // every node that ran, in order
+result.outputs;   // each node's return, by name
+result.latencyMs;
+```
+
+A graph run is a rollout with several steps, so `GraphResult` hands straight to
+`@spendgraph/prompt`'s `report` and `call` without being translated first:
+
+```ts
+await prompt.call(values, () => flow.execute(values));
+```
+
+## Context
+
+`outputs` is the only channel between nodes. A shared mutable bag would let node
+four depend on a key node two happens to set — a dependency the graph does not
+declare and compilation cannot check.
+
+```ts
+ctx.values;   // what execute() was called with
+ctx.outputs;  // what each finished node returned, by name
+ctx.steps;    // the steps so far; a copy, so writing to it does nothing
+```

package/dist/compile/compile.d.ts

@@ -0,0 +1,29 @@
+import { type GraphStream } from "../execute/index.js";
+import type { Edge, GraphResult, GraphSpec, Node } from "../types/index.js";
+export interface GraphOptions {
+    /** Injectable clock, so tests do not measure real time. */
+    now?: () => number;
+}
+/** Compiles a graph, refusing one that cannot run as written. */
+export declare function graph(spec: GraphSpec, opts?: GraphOptions): {
+    entry: string;
+    maxSteps: number;
+    /** Every node, in declaration order. */
+    nodes: () => Node<never>[];
+    /** Edges leaving a node, in the order they will be tried. */
+    edgesFrom: (name: string) => Edge[];
+    /**
+     * Runs it once. Never throws — the result carries every step taken, so a
+     * run that stopped at node three still says which three and why.
+     */
+    execute: (values?: Record<string, unknown>) => Promise<GraphResult>;
+    /**
+     * The same run, narrated. Yields a node's start and end, whatever its nodes
+     * emit while running, and the finished result last.
+     *
+     * The run begins on the call, not on the first read, so `result` is there
+     * for the caller who wants the rollout and not the commentary.
+     */
+    stream: (values?: Record<string, unknown>) => GraphStream;
+};
+export type Graph = ReturnType<typeof graph>;

package/dist/compile/compile.js

@@ -0,0 +1,31 @@
+import { executeGraph, streamGraph } from "../execute/index.js";
+import { assertAllReachable, indexEdges, indexNodes } from "./validate.js";
+/** Compiles a graph, refusing one that cannot run as written. */
+export function graph(spec, opts = {}) {
+    const now = opts.now ?? (() => Date.now());
+    const maxSteps = Math.max(1, spec.maxSteps ?? 25);
+    const byName = indexNodes(spec);
+    const edgesFrom = indexEdges(spec.edges ?? [], byName);
+    assertAllReachable(spec.entry, byName, edgesFrom);
+    return {
+        entry: spec.entry,
+        maxSteps,
+        /** Every node, in declaration order. */
+        nodes: () => [...byName.values()],
+        /** Edges leaving a node, in the order they will be tried. */
+        edgesFrom: (name) => [...(edgesFrom.get(name) ?? [])],
+        /**
+         * Runs it once. Never throws — the result carries every step taken, so a
+         * run that stopped at node three still says which three and why.
+         */
+        execute: (values = {}) => executeGraph(byName, edgesFrom, spec.entry, maxSteps, values, now),
+        /**
+         * The same run, narrated. Yields a node's start and end, whatever its nodes
+         * emit while running, and the finished result last.
+         *
+         * The run begins on the call, not on the first read, so `result` is there
+         * for the caller who wants the rollout and not the commentary.
+         */
+        stream: (values = {}) => streamGraph(byName, edgesFrom, spec.entry, maxSteps, values, now),
+    };
+}

package/dist/compile/index.d.ts

@@ -0,0 +1 @@
+export { type Graph, type GraphOptions, graph } from "./compile.js";

package/dist/compile/index.js

@@ -0,0 +1 @@
+export { graph } from "./compile.js";

package/dist/compile/validate.d.ts

@@ -0,0 +1,17 @@
+import type { Edge, GraphSpec, Node } from "../types/index.js";
+/**
+ * Everything about a graph that is wrong without running it.
+ *
+ * The argument for a graph over a hand-written loop: the shape is data, so it
+ * can be wrong at build time rather than on the branch nobody exercised. What
+ * no static check catches is a loop that never exits — that is `maxSteps`.
+ */
+export declare function indexNodes(spec: GraphSpec): Map<string, Node<never>>;
+export declare function indexEdges(edges: Edge[], byName: Map<string, Node<never>>): Map<string, Edge[]>;
+/**
+ * Refuses a node nothing reaches.
+ *
+ * Refused rather than warned about: the usual cause is a typo in an edge, and
+ * the usual symptom is a branch that quietly never runs.
+ */
+export declare function assertAllReachable(entry: string, byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>): void;

package/dist/compile/validate.js

@@ -0,0 +1,66 @@
+/**
+ * Everything about a graph that is wrong without running it.
+ *
+ * The argument for a graph over a hand-written loop: the shape is data, so it
+ * can be wrong at build time rather than on the branch nobody exercised. What
+ * no static check catches is a loop that never exits — that is `maxSteps`.
+ */
+export function indexNodes(spec) {
+    if (spec.nodes.length === 0)
+        throw new Error("A graph needs at least one node.");
+    const byName = new Map();
+    for (const n of spec.nodes) {
+        if (byName.has(n.name))
+            throw new Error(`Two nodes are called "${n.name}".`);
+        byName.set(n.name, n);
+    }
+    if (!byName.has(spec.entry)) {
+        throw new Error(`The entry node "${spec.entry}" is not in this graph. Known: ${[...byName.keys()].join(", ")}.`);
+    }
+    return byName;
+}
+export function indexEdges(edges, byName) {
+    const edgesFrom = new Map();
+    for (const e of edges) {
+        if (!byName.has(e.from)) {
+            throw new Error(`An edge starts at "${e.from}", which is not a node in this graph.`);
+        }
+        if (e.to !== null && !byName.has(e.to)) {
+            throw new Error(`An edge from "${e.from}" points at "${e.to}", which is not a node in this graph.`);
+        }
+        const list = edgesFrom.get(e.from) ?? [];
+        // First match wins, so anything after an unconditional edge is dead. The
+        // graph would look like it handles a case it does not.
+        const open = list.find((prior) => !prior.when);
+        if (open) {
+            throw new Error(`The edge from "${e.from}" to "${open.to ?? "the end"}" has no condition, so the edge ` +
+                `to "${e.to ?? "the end"}" declared after it can never be taken. Put the unconditional edge last.`);
+        }
+        list.push(e);
+        edgesFrom.set(e.from, list);
+    }
+    return edgesFrom;
+}
+/**
+ * Refuses a node nothing reaches.
+ *
+ * Refused rather than warned about: the usual cause is a typo in an edge, and
+ * the usual symptom is a branch that quietly never runs.
+ */
+export function assertAllReachable(entry, byName, edgesFrom) {
+    const reached = new Set([entry]);
+    const queue = [entry];
+    while (queue.length) {
+        for (const e of edgesFrom.get(queue.shift()) ?? []) {
+            if (e.to && !reached.has(e.to)) {
+                reached.add(e.to);
+                queue.push(e.to);
+            }
+        }
+    }
+    const orphans = [...byName.keys()].filter((n) => !reached.has(n));
+    if (orphans.length) {
+        throw new Error(`Nothing reaches ${orphans.map((n) => `"${n}"`).join(", ")} from "${entry}". ` +
+            `Add an edge, or take the node out.`);
+    }
+}

package/dist/execute/execute.d.ts

@@ -0,0 +1,16 @@
+import type { Edge, GraphEvent, GraphResult, Node } from "../types/index.js";
+/**
+ * Runs a compiled graph.
+ *
+ * Never throws, for the reason `invoke` never throws: an exception discards the
+ * two steps that worked along with the evidence of where it stopped. Every exit
+ * here is a `GraphResult` carrying the steps taken.
+ *
+ * A failed node halts the run. Continuing would leave every later node reading
+ * `outputs` for something that is not there.
+ *
+ * `sink` is how a run narrates itself. It is called as the run proceeds and its
+ * absence changes nothing, so the streamed and unstreamed paths stay one piece
+ * of code rather than two that drift.
+ */
+export declare function executeGraph(byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>, entry: string, maxSteps: number, values: Record<string, unknown>, now: () => number, sink?: (event: GraphEvent) => void): Promise<GraphResult>;

package/dist/execute/execute.js

@@ -0,0 +1,108 @@
+import { FieldValidationError, validateFields } from "@spendgraph/sdk";
+import { nestedSteps, outputOf, tokensOf, totalTokens } from "./outcome.js";
+import { failedStep, message } from "./step.js";
+function ended(node, index, status, latencyMs, output, error) {
+    return { type: "node_end", node, index, status, output, error, latencyMs };
+}
+/**
+ * Runs a compiled graph.
+ *
+ * Never throws, for the reason `invoke` never throws: an exception discards the
+ * two steps that worked along with the evidence of where it stopped. Every exit
+ * here is a `GraphResult` carrying the steps taken.
+ *
+ * A failed node halts the run. Continuing would leave every later node reading
+ * `outputs` for something that is not there.
+ *
+ * `sink` is how a run narrates itself. It is called as the run proceeds and its
+ * absence changes nothing, so the streamed and unstreamed paths stay one piece
+ * of code rather than two that drift.
+ */
+export async function executeGraph(byName, edgesFrom, entry, maxSteps, values, now, sink = () => { }) {
+    const startedAt = now();
+    const steps = [];
+    const outputs = {};
+    const context = (node) => ({
+        values,
+        outputs,
+        steps: [...steps],
+        emit: (text) => sink({ type: "token", node, text }),
+    });
+    const finish = (status, error) => ({
+        status,
+        output: status === "completed" ? (steps.at(-1)?.output ?? "") : "",
+        error,
+        steps,
+        outputs,
+        latencyMs: now() - startedAt,
+        ...totalTokens(steps),
+    });
+    let current = entry;
+    while (current) {
+        if (steps.length >= maxSteps) {
+            return finish("failed", `Ran ${maxSteps} steps without reaching an end, stopping at "${current}". ` +
+                `Either a conditional edge never turns false, or maxSteps is too low for this graph.`);
+        }
+        const node = byName.get(current);
+        const startedNode = now();
+        const ctx = context(current);
+        const index = steps.length;
+        let input;
+        try {
+            input = node.input ? node.input(ctx) : values;
+        }
+        catch (err) {
+            steps.push(failedStep(index, node.name, {}, now() - startedNode, message(err)));
+            sink(ended(node.name, index, "failed", now() - startedNode, undefined, message(err)));
+            return finish("failed", `Building the input for "${node.name}" threw: ${message(err)}`);
+        }
+        sink({ type: "node_start", node: node.name, index, input });
+        if (node.args?.length) {
+            const errors = validateFields(input, node.args);
+            if (errors.length > 0) {
+                const detail = new FieldValidationError(errors).message;
+                steps.push(failedStep(index, node.name, input, now() - startedNode, detail));
+                sink(ended(node.name, index, "failed", now() - startedNode, undefined, detail));
+                return finish("failed", `"${node.name}" was given ${detail}`);
+            }
+        }
+        let value;
+        try {
+            value = await node.run(input, ctx);
+        }
+        catch (err) {
+            steps.push(failedStep(index, node.name, input, now() - startedNode, message(err)));
+            sink(ended(node.name, index, "failed", now() - startedNode, undefined, message(err)));
+            return finish("failed", `"${node.name}" failed: ${message(err)}`);
+        }
+        outputs[node.name] = value;
+        steps.push({
+            index,
+            source: node.name,
+            input,
+            output: outputOf(value),
+            status: "completed",
+            latencyMs: now() - startedNode,
+            ...tokensOf(value),
+        });
+        steps.push(...nestedSteps(value, steps.length, node.name));
+        sink(ended(node.name, index, "completed", now() - startedNode, value));
+        // First match wins, so an unconditional edge is the default branch. No match
+        // is an end, which is what a node with no outgoing edges already means.
+        let next = null;
+        try {
+            const after = context(node.name);
+            for (const e of edgesFrom.get(node.name) ?? []) {
+                if (e.when && !e.when(after))
+                    continue;
+                next = e.to;
+                break;
+            }
+        }
+        catch (err) {
+            return finish("failed", `Choosing what runs after "${node.name}" threw: ${message(err)}`);
+        }
+        current = next;
+    }
+    return finish("completed");
+}

package/dist/execute/index.d.ts

@@ -0,0 +1,4 @@
+export { executeGraph } from "./execute.js";
+export type { NodeOutcome } from "./outcome.js";
+export type { GraphStream } from "./stream.js";
+export { streamGraph } from "./stream.js";

package/dist/execute/index.js

@@ -0,0 +1,2 @@
+export { executeGraph } from "./execute.js";
+export { streamGraph } from "./stream.js";

package/dist/execute/outcome.d.ts

@@ -0,0 +1,46 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+/**
+ * What a node returned, when it returned the shape a model call produces.
+ *
+ * Recognised structurally rather than declared: a node may return anything, and
+ * a plain object is the common case. But a node that called a model, ran a
+ * prompt or nested another workflow returns tokens and sometimes its own steps,
+ * and both used to be flattened into the output string and lost — which made a
+ * graph run report as costing nothing.
+ */
+export interface NodeOutcome {
+    output?: string;
+    model?: string;
+    status?: "completed" | "failed";
+    error?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** A nested run's own steps, spliced in rather than stringified away. */
+    steps?: RolloutStep[];
+}
+/** The text a step should carry: an outcome's own output, or the whole value. */
+export declare function outputOf(value: unknown): string;
+/**
+ * The token counts a node reported, or nothing when it reported none.
+ *
+ * A node that also returns nested steps reports none here: its own totals are
+ * the sum of those steps, and counting both makes a graph inside a graph cost
+ * exactly twice what it did.
+ */
+export declare function tokensOf(value: unknown): Pick<RolloutStep, "inputTokens" | "outputTokens"> & {
+    model?: string;
+};
+/**
+ * A nested run's steps, renumbered to sit in this run's sequence.
+ *
+ * Prefixed with the node that produced them, so a step from a refine loop
+ * inside a router still says which branch it came from.
+ */
+export declare function nestedSteps(value: unknown, from: number, source: string): RolloutStep[];
+/** What every step in a run adds up to. */
+export declare function totalTokens(steps: RolloutStep[]): {
+    inputTokens: number;
+    outputTokens: number;
+};

package/dist/execute/outcome.js

@@ -0,0 +1,59 @@
+import { stringify } from "./step.js";
+function isOutcome(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const v = value;
+    return (typeof v.output === "string" ||
+        typeof v.inputTokens === "number" ||
+        typeof v.outputTokens === "number" ||
+        Array.isArray(v.steps));
+}
+/** The text a step should carry: an outcome's own output, or the whole value. */
+export function outputOf(value) {
+    const outcome = isOutcome(value) ? value : undefined;
+    return outcome && typeof outcome.output === "string" ? outcome.output : stringify(value);
+}
+/**
+ * The token counts a node reported, or nothing when it reported none.
+ *
+ * A node that also returns nested steps reports none here: its own totals are
+ * the sum of those steps, and counting both makes a graph inside a graph cost
+ * exactly twice what it did.
+ */
+export function tokensOf(value) {
+    if (!isOutcome(value))
+        return {};
+    const nested = Array.isArray(value.steps) && value.steps.length > 0;
+    return {
+        ...(!nested && typeof value.inputTokens === "number" ? { inputTokens: value.inputTokens } : {}),
+        ...(!nested && typeof value.outputTokens === "number"
+            ? { outputTokens: value.outputTokens }
+            : {}),
+        ...(value.model ? { model: value.model } : {}),
+    };
+}
+/**
+ * A nested run's steps, renumbered to sit in this run's sequence.
+ *
+ * Prefixed with the node that produced them, so a step from a refine loop
+ * inside a router still says which branch it came from.
+ */
+export function nestedSteps(value, from, source) {
+    if (!isOutcome(value) || !Array.isArray(value.steps))
+        return [];
+    return value.steps.map((step, at) => ({
+        ...step,
+        index: from + at,
+        source: `${source}.${step.source}`,
+    }));
+}
+/** What every step in a run adds up to. */
+export function totalTokens(steps) {
+    let inputTokens = 0;
+    let outputTokens = 0;
+    for (const step of steps) {
+        inputTokens += step.inputTokens ?? 0;
+        outputTokens += step.outputTokens ?? 0;
+    }
+    return { inputTokens, outputTokens };
+}

package/dist/execute/step.d.ts

@@ -0,0 +1,5 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+/** Same convention as a tool result: a string is itself, anything else is JSON. */
+export declare function stringify(value: unknown): string;
+export declare function failedStep(index: number, source: string, input: Record<string, unknown>, latencyMs: number, error: string): RolloutStep;
+export declare function message(err: unknown): string;

package/dist/execute/step.js

@@ -0,0 +1,20 @@
+/** Same convention as a tool result: a string is itself, anything else is JSON. */
+export function stringify(value) {
+    if (value === undefined || value === null)
+        return "";
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+export function failedStep(index, source, input, latencyMs, error) {
+    return {
+        index,
+        source,
+        input,
+        output: "",
+        status: "failed",
+        error,
+        latencyMs,
+    };
+}
+export function message(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/execute/stream.d.ts

@@ -0,0 +1,19 @@
+import type { Edge, GraphEvent, GraphResult, Node } from "../types/index.js";
+/** A run as it happens, and the same run once it is over. */
+export interface GraphStream extends AsyncIterable<GraphEvent> {
+    /**
+     * The finished run.
+     *
+     * Resolves whether or not anyone iterated, so a caller can pipe the events to
+     * a client and still record the rollout from the same run.
+     */
+    result: Promise<GraphResult>;
+}
+/**
+ * Runs a compiled graph, narrating it as it goes.
+ *
+ * The run starts immediately rather than on the first read: a caller who only
+ * wants the result should not have to iterate to get one, and a client that
+ * connects late should see what already happened.
+ */
+export declare function streamGraph(byName: Map<string, Node<never>>, edgesFrom: Map<string, Edge[]>, entry: string, maxSteps: number, values: Record<string, unknown>, now: () => number): GraphStream;

package/dist/execute/stream.js

@@ -0,0 +1,63 @@
+import { executeGraph } from "./execute.js";
+/**
+ * Events held between the run and whoever is reading them.
+ *
+ * A queue rather than a callback because the two sides move at different
+ * speeds: a graph does not wait for a slow reader, and a reader must not miss
+ * what arrived before it asked.
+ */
+class Events {
+    waiting = [];
+    wake = null;
+    closed = false;
+    push(event) {
+        this.waiting.push(event);
+        this.release();
+    }
+    close() {
+        this.closed = true;
+        this.release();
+    }
+    release() {
+        const wake = this.wake;
+        this.wake = null;
+        wake?.();
+    }
+    async *drain() {
+        while (true) {
+            while (this.waiting.length > 0) {
+                yield this.waiting.shift();
+            }
+            if (this.closed)
+                return;
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+    }
+}
+/**
+ * Runs a compiled graph, narrating it as it goes.
+ *
+ * The run starts immediately rather than on the first read: a caller who only
+ * wants the result should not have to iterate to get one, and a client that
+ * connects late should see what already happened.
+ */
+export function streamGraph(byName, edgesFrom, entry, maxSteps, values, now) {
+    const events = new Events();
+    const result = (async () => {
+        try {
+            const finished = await executeGraph(byName, edgesFrom, entry, maxSteps, values, now, (e) => events.push(e));
+            events.push({ type: "result", result: finished });
+            return finished;
+        }
+        finally {
+            events.close();
+        }
+    })();
+    void result.catch(() => { });
+    return {
+        result,
+        [Symbol.asyncIterator]: () => events.drain(),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { type Graph, type GraphOptions, graph } from "./compile/index.js";
+export type { GraphStream } from "./execute/index.js";
+export type { NodeSpec } from "./node/index.js";
+export { edge, end, node } from "./node/index.js";
+export type { ArgSpec, ArgsOf, ArgValue, Edge, Emit, GraphContext, GraphEvent, GraphResult, GraphSpec, Node, } from "./types/index.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { graph } from "./compile/index.js";
+export { edge, end, node } from "./node/index.js";

package/dist/node/edge.d.ts

@@ -0,0 +1,10 @@
+import type { Edge } from "../types/index.js";
+/**
+ * An edge from one node to the next, or to the end of the run.
+ *
+ * A helper so the argument order is fixed by something other than memory:
+ * `edge("a", "b")` reads in the direction the run travels.
+ */
+export declare function edge(from: string, to: string | null, when?: Edge["when"]): Edge;
+/** Ends the run after `from`. The same as `edge(from, null)`, said out loud. */
+export declare function end(from: string, when?: Edge["when"]): Edge;

package/dist/node/edge.js

@@ -0,0 +1,13 @@
+/**
+ * An edge from one node to the next, or to the end of the run.
+ *
+ * A helper so the argument order is fixed by something other than memory:
+ * `edge("a", "b")` reads in the direction the run travels.
+ */
+export function edge(from, to, when) {
+    return when ? { from, to, when } : { from, to };
+}
+/** Ends the run after `from`. The same as `edge(from, null)`, said out loud. */
+export function end(from, when) {
+    return edge(from, null, when);
+}

package/dist/node/index.d.ts

@@ -0,0 +1,3 @@
+export { edge, end } from "./edge.js";
+export type { NodeSpec } from "./node.js";
+export { node } from "./node.js";

package/dist/node/index.js

@@ -0,0 +1,2 @@
+export { edge, end } from "./edge.js";
+export { node } from "./node.js";

package/dist/node/node.d.ts

@@ -0,0 +1,15 @@
+import type { ArgSpec, ArgsOf, GraphContext, Node } from "../types/index.js";
+export interface NodeSpec<T extends readonly ArgSpec[]> {
+    name: string;
+    args?: T;
+    input?: (ctx: GraphContext) => Record<string, unknown>;
+    run(input: ArgsOf<T>, ctx: GraphContext): Promise<unknown> | unknown;
+}
+/**
+ * Declares a node, checking what a graph cannot check later.
+ *
+ * The same argument as `tool()`: a duplicated argument silently loses one, and a
+ * hyphenated name reads badly in the step record that is the only trace of a
+ * failed run.
+ */
+export declare function node<const T extends readonly ArgSpec[]>(spec: NodeSpec<T>): Node<ArgsOf<T>>;

package/dist/node/node.js

@@ -0,0 +1,33 @@
+/** Names that read back cleanly in a step record and a compile error. */
+const VALID_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Declares a node, checking what a graph cannot check later.
+ *
+ * The same argument as `tool()`: a duplicated argument silently loses one, and a
+ * hyphenated name reads badly in the step record that is the only trace of a
+ * failed run.
+ */
+export function node(spec) {
+    if (!VALID_NAME.test(spec.name)) {
+        throw new Error(`Node name "${spec.name}" must be letters, digits and underscores, starting with a letter.`);
+    }
+    const seen = new Set();
+    for (const arg of spec.args ?? []) {
+        if (!VALID_NAME.test(arg.name)) {
+            throw new Error(`Node "${spec.name}" argument "${arg.name}" is not a usable name.`);
+        }
+        if (seen.has(arg.name)) {
+            throw new Error(`Node "${spec.name}" declares "${arg.name}" twice.`);
+        }
+        seen.add(arg.name);
+        if (arg.type === "enum" && !arg.options?.length) {
+            throw new Error(`Node "${spec.name}" argument "${arg.name}" is an enum with no options, so nothing can satisfy it.`);
+        }
+    }
+    return {
+        name: spec.name,
+        args: spec.args?.map((a) => ({ ...a, options: a.options ? [...a.options] : undefined })),
+        input: spec.input,
+        run: spec.run,
+    };
+}

package/dist/types/args.d.ts

@@ -0,0 +1,56 @@
+import type { FieldType } from "@spendgraph/sdk";
+/**
+ * A declared argument, as written.
+ *
+ * Structurally a `FieldSpec` with every field readonly, because that is what an
+ * `as const` array produces — and `FieldSpec.options` being a mutable `string[]`
+ * is enough to make the whole tuple fail the constraint and inference fall back
+ * to nothing, silently.
+ */
+export interface ArgSpec {
+    readonly name: string;
+    readonly type: FieldType;
+    readonly required: boolean;
+    readonly default?: string;
+    readonly description?: string;
+    readonly options?: readonly string[];
+    readonly separator?: string;
+    readonly min?: number;
+    readonly max?: number;
+    readonly maxLength?: number;
+    readonly trueText?: string;
+    readonly falseText?: string;
+    readonly datasetKey?: boolean;
+}
+/** What one declared argument is worth at runtime. */
+export type ArgValue<F> = F extends {
+    type: "number";
+} ? number : F extends {
+    type: "boolean";
+} ? boolean : F extends {
+    type: "list";
+} ? string[] : F extends {
+    type: "json";
+} ? unknown : F extends {
+    type: "enum";
+    options: readonly (infer O)[];
+} ? O : string;
+type Required<T> = T extends {
+    required: true;
+} ? T : never;
+type Optional<T> = T extends {
+    required: true;
+} ? never : T;
+/**
+ * The object `run` is handed, derived from the args you declared.
+ *
+ * Declare `args` with `as const` and the handler's parameter types follow, so a
+ * renamed argument is a compile error rather than an `undefined` discovered
+ * halfway through a graph.
+ */
+export type ArgsOf<T extends readonly ArgSpec[]> = {
+    [F in Required<T[number]> as F["name"]]: ArgValue<F>;
+} & {
+    [F in Optional<T[number]> as F["name"]]?: ArgValue<F>;
+};
+export {};

package/dist/types/args.js

@@ -0,0 +1 @@
+export {};

package/dist/types/context.d.ts

@@ -0,0 +1,25 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { Emit } from "./event.js";
+/**
+ * What a node can see while it decides and while it runs.
+ *
+ * `outputs` is the only channel between nodes. A shared mutable bag would let
+ * node four depend on a key node two happens to set — a dependency the graph
+ * does not declare and compilation cannot check.
+ */
+export interface GraphContext {
+    /** The object `execute` was called with. */
+    values: Record<string, unknown>;
+    /** What each node that has finished returned, by name. */
+    outputs: Record<string, unknown>;
+    /** The steps recorded so far, in order. A copy; writing to it does nothing. */
+    steps: RolloutStep[];
+    /**
+     * Sends a token out of the run, tagged with the node that emitted it.
+     *
+     * Hand it straight to a model call as its `onText` and the deltas leave the
+     * graph as they arrive. Always present, and a no-op unless someone is
+     * streaming, so a node never has to ask whether anyone is listening.
+     */
+    emit: Emit;
+}

package/dist/types/context.js

@@ -0,0 +1 @@
+export {};

package/dist/types/edge.d.ts

@@ -0,0 +1,12 @@
+import type { GraphContext } from "./context.js";
+/** What runs after what, and whether it runs at all. */
+export interface Edge {
+    from: string;
+    /** The next node, or null to end the run here. */
+    to: string | null;
+    /**
+     * Taken only when true. Tried in declaration order, first match wins — so an
+     * unconditional edge is the default branch and belongs last.
+     */
+    when?: (ctx: GraphContext) => boolean;
+}

package/dist/types/edge.js

@@ -0,0 +1 @@
+export {};

package/dist/types/event.d.ts

@@ -0,0 +1,32 @@
+import type { GraphResult } from "./result.js";
+/**
+ * What a run says about itself while it is still running.
+ *
+ * Every event names the node it came from, because a stream carrying tokens
+ * from four nodes is unreadable without it — and which nodes are worth showing
+ * is the consumer's decision, not the graph's.
+ */
+export type GraphEvent = {
+    type: "node_start";
+    node: string;
+    /** The step index this node will occupy. */
+    index: number;
+    input: Record<string, unknown>;
+} | {
+    type: "token";
+    node: string;
+    text: string;
+} | {
+    type: "node_end";
+    node: string;
+    index: number;
+    status: "completed" | "failed";
+    output?: unknown;
+    error?: string;
+    latencyMs: number;
+} | {
+    type: "result";
+    result: GraphResult;
+};
+/** Where a node's tokens go. A run that nobody is streaming drops them. */
+export type Emit = (text: string) => void;

package/dist/types/event.js

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,7 @@
+export type { ArgSpec, ArgsOf, ArgValue } from "./args.js";
+export type { GraphContext } from "./context.js";
+export type { Edge } from "./edge.js";
+export type { Emit, GraphEvent } from "./event.js";
+export type { Node } from "./node.js";
+export type { GraphResult } from "./result.js";
+export type { GraphSpec } from "./spec.js";

package/dist/types/index.js

@@ -0,0 +1 @@
+export {};

package/dist/types/node.d.ts

@@ -0,0 +1,20 @@
+import type { FieldSpec } from "@spendgraph/sdk";
+import type { GraphContext } from "./context.js";
+/**
+ * One unit of work in a graph.
+ *
+ * `input` is what makes a node reusable: the node says what it needs, the graph
+ * says where it comes from. Without it every node has to know the whole run.
+ */
+export interface Node<Args = Record<string, unknown>> {
+    /** Unique in the graph, and the key its output is stored under. */
+    name: string;
+    /**
+     * What this node needs, validated before `run` does any work. Halfway through
+     * a graph is the most expensive place to discover a typo.
+     */
+    args?: FieldSpec[];
+    /** The edge's data half: an edge says what runs next, this says on what. */
+    input?: (ctx: GraphContext) => Record<string, unknown>;
+    run(input: Args, ctx: GraphContext): Promise<unknown> | unknown;
+}

package/dist/types/node.js

@@ -0,0 +1 @@
+export {};

package/dist/types/result.d.ts

@@ -0,0 +1,20 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+/**
+ * What one run produced, in the shape of a rollout.
+ *
+ * A graph run is a rollout with several steps, so this hands straight to
+ * `report()` rather than being translated first.
+ */
+export interface GraphResult {
+    status: "completed" | "failed";
+    /** The last node's return, stringified the way a tool result is. */
+    output: string;
+    error?: string;
+    steps: RolloutStep[];
+    /** Every node's return, by name, for reading a run apart afterwards. */
+    outputs: Record<string, unknown>;
+    latencyMs: number;
+    /** Summed across every step, nested ones included. */
+    inputTokens: number;
+    outputTokens: number;
+}

package/dist/types/result.js

@@ -0,0 +1 @@
+export {};

package/dist/types/spec.d.ts

@@ -0,0 +1,15 @@
+import type { Edge } from "./edge.js";
+import type { Node } from "./node.js";
+export interface GraphSpec {
+    /** Where a run starts. */
+    entry: string;
+    nodes: Node<never>[];
+    edges?: Edge[];
+    /**
+     * How many nodes a run may execute before it is called a loop. Default 25.
+     *
+     * A backwards edge is a feature and also how a graph hangs. Nothing tells the
+     * two apart statically, so the guard is a count and a clear failure.
+     */
+    maxSteps?: number;
+}

package/dist/types/spec.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@spendgraph/graph",
+  "version": "0.2.0",
+  "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/graph"
+  },
+  "homepage": "https://github.com/fnLog0/spendgraph#readme",
+  "bugs": {
+    "url": "https://github.com/fnLog0/spendgraph/issues"
+  },
+  "keywords": [
+    "llm",
+    "agent",
+    "graph",
+    "workflow",
+    "orchestration"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@spendgraph/sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}