@spendgraph/graph 0.2.0 → 0.3.0

package/README.md

@@ -35,16 +35,19 @@ const classify = node({
 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.
+Args are validated before `run` does any work. A node name must be letters,
+digits and underscores starting with a letter, and that is checked at import
+rather than on the first run.
 
 ## Wiring
 
 ```ts
 const flow = graph({
-  start: "classify",
+  entry: "classify",
   nodes: [classify, lookup, answer],
   edges: [
-    edge("classify", (ctx) => (ctx.outputs.classify === "billing" ? "lookup" : "answer")),
+    edge("classify", "lookup", (ctx) => ctx.outputs.classify === "billing"),
+    edge("classify", "answer"),
     edge("lookup", "answer"),
     end("answer"),
   ],
@@ -53,18 +56,66 @@ const flow = graph({
 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.
+An edge says what runs next; a node's `input` says on what.
+
+**Branching is several edges, not one clever edge.** `edge(from, to, when)`
+takes a predicate, and the edges leaving a node are tried in declaration order
+with the first match winning — so an unconditional edge is the default branch
+and belongs last. `end(from)` is `edge(from, null)` said out loud.
+
+Compilation checks the wiring — an edge to a node that does not exist, an entry
+that is not a node, two nodes with the same name, a node nothing reaches —
+before anything runs. Those are the one place this package throws.
+
+## When a node fails
+
+A run never throws. A node that throws, or is handed an argument that does not
+validate, halts the run and comes back as a result:
+
+```ts
+result.status;  // "failed"
+result.error;   // '"lookup" failed: contract MSA 2.4 not found'
+result.steps;   // the steps that did run, with the failed one last
+```
+
+Continuing would leave every later node reading an output that was never
+written. Stopping with the steps intact is what lets a failed run say which
+three nodes ran and where it stopped, which a thrown exception cannot.
+
+`maxSteps` bounds the run and defaults to 25. A backwards edge is a feature and
+also how a graph hangs, and nothing tells the two apart statically, so the guard
+is a count and a clear failure rather than a hung process.
+
+## Watching it run
+
+`stream` is the same run, narrated — a node's start and end, whatever its nodes
+emit while running, and the finished result last.
+
+```ts
+const running = flow.stream({ question });
+
+for await (const event of running) {
+  if (event.type === "token") process.stdout.write(event.text);
+}
+
+const result = await running.result;
+```
+
+A node writes into the stream through the `emit` it is handed, so a node that
+wraps a streaming model call can forward deltas without the graph knowing what a
+token is. The run begins on the call rather than on the first read, so
+`result` is there for a caller who wants the rollout and not the commentary.
 
 ## What comes back
 
 ```ts
 result.status;    // "completed" | "failed"
-result.output;    // the last node's return, stringified
+result.output;    // the last node's return, stringified; "" on a failure
 result.steps;     // every node that ran, in order
 result.outputs;   // each node's return, by name
 result.latencyMs;
+result.inputTokens;   // summed across every step, nested ones included
+result.outputTokens;
 ```
 
 A graph run is a rollout with several steps, so `GraphResult` hands straight to
@@ -85,3 +136,19 @@ 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
 ```
+
+## Inspecting one
+
+A compiled graph answers questions about itself, which is what the workflows in
+`@spendgraph/harness` build on.
+
+```ts
+flow.entry;               // where a run starts
+flow.maxSteps;
+flow.nodes();             // every node, in declaration order
+flow.edgesFrom("classify"); // the edges leaving it, in the order they are tried
+```
+
+## License
+
+MIT

package/dist/compile/compile.js

@@ -1,6 +1,5 @@
 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);
@@ -10,22 +9,9 @@ export function graph(spec, opts = {}) {
     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/validate.js

@@ -1,10 +1,3 @@
-/**
- * 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.");
@@ -29,8 +22,6 @@ export function indexEdges(edges, byName) {
             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 ` +
@@ -41,12 +32,6 @@ export function indexEdges(edges, byName) {
     }
     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];

package/dist/execute/execute.js

@@ -4,20 +4,6 @@ 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 = [];
@@ -87,8 +73,6 @@ export async function executeGraph(byName, edgesFrom, entry, maxSteps, values, n
         });
         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);

package/dist/execute/outcome.js

@@ -8,18 +8,10 @@ function isOutcome(value) {
         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 {};
@@ -32,12 +24,6 @@ export function tokensOf(value) {
         ...(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 [];
@@ -47,7 +33,6 @@ export function nestedSteps(value, from, source) {
         source: `${source}.${step.source}`,
     }));
 }
-/** What every step in a run adds up to. */
 export function totalTokens(steps) {
     let inputTokens = 0;
     let outputTokens = 0;

package/dist/execute/step.js

@@ -1,4 +1,3 @@
-/** Same convention as a tool result: a string is itself, anything else is JSON. */
 export function stringify(value) {
     if (value === undefined || value === null)
         return "";

package/dist/execute/stream.js

@@ -1,11 +1,4 @@
 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;
@@ -36,13 +29,6 @@ class Events {
         }
     }
 }
-/**
- * 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 () => {

package/dist/node/edge.js

@@ -1,13 +1,6 @@
-/**
- * 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/node.js

@@ -1,12 +1,4 @@
-/** 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.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/graph",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
   "license": "MIT",
   "repository": {
@@ -34,11 +34,11 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
     "test": "vitest run"
   },
   "dependencies": {
-    "@spendgraph/sdk": "^0.2.0"
+    "@spendgraph/sdk": "^0.3.0"
   },
   "devDependencies": {
     "typescript": "^5"