npm - @spendgraph/graph - Versions diffs - 0.8.1 → 0.8.3 - Mend

@spendgraph/graph 0.8.1 → 0.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/graph",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "description": "Wire nodes into a graph, run it, and get back a rollout with every step.",
   "license": "Apache-2.0",
   "repository": {
@@ -27,19 +27,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./docs/*": "./docs/*",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "docs",
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/sdk": "^0.8.1"
+    "@spendgraph/sdk": "^0.8.3"
   },
   "devDependencies": {
-    "@spendgraph/config": "0.8.1",
+    "@spendgraph/config": "0.8.3",
     "typescript": "^5"
   },
   "engines": {

package/docs/nodes.mdx DELETED Viewed

@@ -1,59 +0,0 @@
-export const meta = {
-  title: "Nodes: spendgraph docs",
-  description:
-    "One unit of work. Declare its arguments with `as const` and the handler types itself; say where they come from with `input`, and the node stays reusable.",
-};
-# Nodes
-A node is one unit of work: a name, the arguments it needs, where they come from, and what to do with them.
-```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),
-});
-```
-## `input` is what makes it reusable
-The node says what it **needs**; the graph says where it **comes from**. Without that split, every node has to know about the whole run, and a node that reads `ctx.values.question` directly is a node you cannot drop into a second graph where the question is called something else.
-```ts
-input: (ctx) => ({ text: ctx.values.question });        // from the run's values
-input: (ctx) => ({ text: String(ctx.outputs.draft) });  // from an earlier node
-```
-Leave `input` off and the node is handed the run's values as they are.
-## Write `as const`
-```ts
-args: [{ name: "text", type: "string", required: true }] as const,
-run: ({ text }) => text.toUpperCase(),   // `text` is a string, here and now
-```
-The handler types itself from the args: `text` a string, a `number` arg a number, an optional one optional. Rename an argument and the handler stops compiling.
-**Without `as const` inference falls back to `Record<string, unknown>` silently.** Nothing errors; the types simply stop meaning anything, and a typo that used to be a compile error becomes `undefined` halfway through a graph, the most expensive place to find one.
-<Callout tone="trap" title="A node cannot rewrite what an earlier node did">
-  The steps a node is handed are a frozen copy: writing to one changes nothing, and it will not throw to tell you so. Pass what the next node needs through the return value, which is what `input` reads.
-</Callout>
-## What is checked, and when
-Arguments are validated **before `run` does any work**, against the same `FieldSpec` types the SDK, tools and prompts all use. A node handed something that does not validate fails the run rather than being let through to fail further in.
-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.
-## Returning something
-Whatever `run` returns becomes the node's output: a string is itself, anything else is JSON.
-A value that cannot be written down, a circular object, a `BigInt`, something whose own `toJSON` throws, is recorded as `[not recordable: …]` rather than `""`. An empty output reads as a node that produced nothing, and this is a node that produced something the record could not hold. The two are different facts and the step keeps them apart.

package/docs/overview.mdx DELETED Viewed

@@ -1,98 +0,0 @@
-export const meta = {
-  title: "Graph: spendgraph docs",
-  description:
-    "Wire nodes into a graph, run it, and get back a rollout with every step priced. Four exports, compilation that catches the wiring mistakes, and a run that never throws.",
-};
-# Graph
-Multi-step work hand-rolled in `if`/`await` runs fine and leaves nothing behind: when step four fails at 2am, what ran, in what order, and what it cost are all gone.
-A graph is nodes and the edges between them. You describe the units of work and where control goes next; running it hands back a rollout: every step, in order, with what each one cost.
-```sh
-npm install @spendgraph/graph
-```
-<GraphToRollout />
-Four things are exported. Everything else hangs off what they return.
-```ts
-import { graph, node, edge, end } from "@spendgraph/graph";
-```
-## The whole thing
-```ts
-const classify = node({
-  name: "classify",
-  args: [{ name: "text", type: "string", required: true }] as const,
-  input: (ctx) => ({ text: ctx.values.question }),
-  run: ({ text }) => model.classify(text),
-});
-const lookup = node({
-  name: "lookup",
-  args: [{ name: "ref", type: "string", required: true }] as const,
-  input: (ctx) => ({ ref: ctx.values.question }),
-  run: ({ ref }) => contracts.find(ref),
-});
-const answer = node({
-  name: "answer",
-  run: (values) => llm.call([{ role: "user", content: String(values.question) }]),
-});
-const flow = graph({
-  entry: "classify",
-  nodes: [classify, lookup, answer],
-  edges: [
-    edge("classify", "lookup", (ctx) => ctx.outputs.classify === "billing"),
-    edge("classify", "answer"),
-    edge("lookup", "answer"),
-    end("answer"),
-  ],
-});
-const result = await flow.execute({ question: "Why was I charged twice?" });
-```
-## What you get back
-```ts
-result.status;        // "completed" | "failed"
-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 it hands straight to `@spendgraph/prompt` without being translated first:
-```ts
-await prompt.call(values, () => flow.execute(values));
-```
-## Three things worth knowing up front
-**Compilation is the one place this package throws.** 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, a node whose edges are all conditional, all of it is checked before anything runs. See [wiring](/spendgraph/graph/wiring).
-**A run never throws.** A node that fails halts the run and comes back as a result with the steps that did run and the failed one last. A thrown exception cannot tell you which three nodes ran; a result can. See [running a graph](/spendgraph/graph/running).
-**`outputs` is the only channel between nodes.** No shared mutable bag, so node four cannot come to depend on a key node two happens to set: a dependency the graph does not declare and compilation cannot check.
-<Callout tone="trap" title="Compilation is the only place mistakes are cheap">
-  An edge pointing at a node that does not exist, an entry that is not a node, a node nothing reaches, all refused by `graph()`, before a single model call. The same mistakes found at run time are found on the branch that reaches them, which may be the one that only runs at month end.
-</Callout>
-## Where to go next
-| | |
-| --- | --- |
-| [Nodes](/spendgraph/graph/nodes) | declaring one, and the types you get for free |
-| [Wiring](/spendgraph/graph/wiring) | edges, branching, and what compilation refuses |
-| [Running a graph](/spendgraph/graph/running) | failure, the step ceiling, and what comes back |
-| [Streaming](/spendgraph/graph/streaming) | the same run, narrated |

package/docs/pausing.mdx DELETED Viewed

@@ -1,109 +0,0 @@
-export const meta = {
-  title: "Pausing a graph: spendgraph docs",
-  description:
-    "A node that runs something needing a person stops the graph rather than walking past the question. The pause arrives as an event, and `entry` picks the run back up where it stopped.",
-};
-# Stopping to ask
-Some work needs a person: an approval, a choice between plans, a number nobody
-can infer. A node that runs something like that comes back with a **question
-rather than an answer**, and the graph stops there.
-```ts
-const stopped = await flow.execute({ expression: "12 / 0" });
-stopped.waitingOn;   // { question: "12 / 0 — what should this return?", detail }
-stopped.waitingFor;  // the nested run to resume, where it named one
-```
-Nothing downstream runs. Walking on would put every later node to work against a
-value nobody has supplied, and report the run as done while it is parked.
-## Recognised by shape, not by a marker
-A node returning a value that carries `waitingOn` **is** a pause. There is no
-wrapper to remember.
-That is the same argument as reading a node's outcome structurally: a node may
-return anything, and a rule to wrap a paused run is one you learn by having the
-graph walk past the question and call it success. Every node's return goes
-through it, so a `waitingOn` that is data rather than a question stops the run
-too, nothing else in a reply has that shape, and the alternative fails the
-other way, silently.
-The check itself is exported, so your own code can ask the same question the
-graph asks:
-```ts
-import { pausedInside } from "@spendgraph/graph";
-const paused = pausedInside(result);   // Paused, or null
-paused?.waitingOn.question;
-paused?.runId;                         // the inner run to resume, where there is one
-```
-Reach for it inside a node that runs a nested graph, or in a harness of your
-own. `Wait` is declared here rather than imported for the same reason: harness
-owns durability and depends on this package, so the shape lives on this side and
-harness's own `Wait` satisfies it.
-## Streaming, it is an event
-```ts
-for await (const event of flow.stream(values)) {
-  if (event.type === "paused") ask(event.waitingOn, event.node);
-}
-```
-The event carries the `Wait` whole, the question, and whatever answering it
-needs. A thrown error would carry only its message, which is why this is an
-event and not an exception.
-<Callout tone="trap" title="Whatever a node returned has to survive JSON">
-  A paused run is stored and handed back to running code. A `Date` comes back a string, a `Map` comes back `{}`, and neither throws, so the refusal happens at the pause, naming the node whose return would not survive, rather than three days later in whatever read it.
-</Callout>
-## The graph owns no durability
-It reports the pause and stops. Storing the run, holding it while somebody
-thinks, and handing the answer back is `@spendgraph/harness`'s job: it has the
-store, the expiry and the resume.
-## Picking it back up
-`entry` starts the walk somewhere other than the compiled entry, and `outputs`
-seeds what already ran. The `paused` event says which node stopped; this says
-where to start again.
-```ts
-await flow.execute(values, {
-  entry: "divide",             // the node that asked
-  outputs: stopped.outputs,    // what already ran, so nothing runs twice
-  steps: stopped.steps,        // the run so far, so it comes back as one rollout
-});
-```
-`steps` is the history rather than the values. Leave it out and the resumed run
-numbers its steps from 0 and shows a node an empty `ctx.steps`, so an edge like
-`(ctx) => ctx.steps.length < 3` is true all over again and two halves of one run
-cannot be stitched without renumbering them.
-Only existence is checked. Reachability was settled from the compiled entry at
-build time, and whatever a resume entry leaves unreachable has already run.
-```ts
-result.status;  // "failed"
-result.error;   // 'No node is called "divid", so there is nowhere to start. Known: parse, divide, format.'
-```
-**`maxSteps` counts one run**, so a resumed one starts its budget over. A caller
-resuming a cyclic graph again and again is the one holding the ceiling.
-## A run that paused still ran
-`status` says whether the graph itself ran, and a paused run ran correctly as
-far as it got, so it comes back `completed`, carrying the question.
-Every workflow in this repo signals a pause the same way: not with a status, but
-by carrying what it stopped to ask.

package/docs/running.mdx DELETED Viewed

@@ -1,71 +0,0 @@
-export const meta = {
-  title: "Running a graph: spendgraph docs",
-  description:
-    "A run never throws: a failed node halts it and comes back as a result with the steps that did run. The step ceiling, the context between nodes, and what a rollout carries.",
-};
-# Running a graph
-```ts
-const result = await flow.execute({ question: "Why was I charged twice?" });
-```
-## 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.
-## The step ceiling
-`maxSteps` bounds the run and defaults to **25**. It counts the nodes a run visits: a node that returns a nested run folds that run's steps into the rollout, and none of those count against the ceiling.
-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.
-```ts
-graph({ entry: "draft", nodes, edges, maxSteps: 50 });
-```
-A ceiling that is not finite is **refused at compile time**. `NaN` would make the count never fire, and `Number(process.env.MAX_STEPS)` on an unset variable is `NaN`, which is how an unbounded run arrives without anyone typing one.
-<Callout tone="trap" title="The ceiling counts nodes, and defaults to 25">
-  `maxSteps` bounds how many nodes a run may visit, not how many tokens it may spend, a cycle between two cheap nodes hits it, an expensive straight line never does. It defaults to 25, and a run that reaches it comes back as a *failed* result rather than a truncated success.
-</Callout>
-## What comes back
-```ts
-result.status;    // "completed" | "failed"
-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;
-result.waitingOn;     // the question a node stopped to ask, where one did
-result.waitingFor;    // the nested run to resume, where it named one
-```
-A graph run is a rollout with several steps, so `GraphResult` hands straight to `@spendgraph/prompt`'s `report` and `call` without being translated:
-```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
-```
-Both halves of `steps` are sealed: the array is a copy, so pushing to it changes nothing, and each step is frozen, so a node cannot rewrite what an earlier one produced or what it cost.

package/docs/streaming.mdx DELETED Viewed

@@ -1,62 +0,0 @@
-export const meta = {
-  title: "Streaming a graph: spendgraph docs",
-  description:
-    "The same run, narrated: each node's start and end, whatever its nodes emit while running, and the finished rollout last.",
-};
-# Streaming
-`stream` is the same run as `execute`, 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 emits without knowing what a token is
-A node is handed an `emit`, and writes into the stream through it. A node wrapping a streaming model call forwards deltas that way, and the graph never has to know what it is forwarding.
-```ts
-const answer = node({
-  name: "answer",
-  run: (values, ctx) => llm.stream(messages, { onText: ctx.emit }),
-});
-```
-`emit` takes the text and nothing else, the graph tags it with the node it came
-from, because a stream carrying tokens from four nodes is unreadable without it.
-It is always present and does nothing when nobody is listening, so a node never
-has to ask whether anyone is.
-## The run starts on the call, not the first read
-```ts
-const running = flow.stream(values);
-const result = await running.result;   // no iteration, and it still ran
-```
-A caller who wants the rollout and not the commentary gets it. Nothing is deferred until somebody reads the stream, so a run cannot sit there un-started because a `for await` was never reached.
-<Callout tone="trap" title="One stream has one reader">
-  Two `for await` loops over the same `graph.stream()` take from the same queue, so each sees roughly half the run, which reads as a graph dropping tokens rather than as the mistake it is. A second reader is refused. More than one watcher wants one reader writing into something they can both read.
-</Callout>
-## What the events are
-| | |
-| --- | --- |
-| a node starting | its name, and the step it is |
-| a node finishing | what it returned, what it cost, how long it took |
-| whatever a node emitted | passed through untouched: tokens, progress, anything |
-| a node stopping to ask | the question, and the nested run to resume. See [pausing](/spendgraph/graph/pausing) |
-| the result | last, and the same object `execute` would have returned |
-One reader. Events are handed out and dropped, so a second `for await` over the
-same stream takes half of them rather than seeing the run twice: fan out
-downstream of it, not by iterating it twice.

package/docs/wiring.mdx DELETED Viewed

@@ -1,76 +0,0 @@
-export const meta = {
-  title: "Wiring: spendgraph docs",
-  description:
-    "Edges say what runs next. Branching is several edges tried in order, not one clever edge, and compilation refuses the wiring mistakes before anything runs.",
-};
-# Wiring
-An edge says what runs **next**. A node's `input` says on **what**. Keeping those separate is what lets the same node sit in two graphs.
-```ts
-const flow = graph({
-  entry: "classify",
-  nodes: [classify, lookup, answer],
-  edges: [
-    edge("classify", "lookup", (ctx) => ctx.outputs.classify === "billing"),
-    edge("classify", "answer"),
-    edge("lookup", "answer"),
-    end("answer"),
-  ],
-});
-```
-## Branching is several edges, not one clever edge
-`edge(from, to, when)` takes a predicate. The edges leaving a node are tried **in declaration order**, and the first match wins, so an unconditional edge is the default branch and belongs last.
-```ts
-edge("triage", "refund", (ctx) => ctx.outputs.triage === "billing"),
-edge("triage", "escalate", (ctx) => ctx.outputs.triage === "abuse"),
-edge("triage", "answer"),   // the default, and it goes last
-```
-`end(from)` is `edge(from, null)` said out loud: the run finishes here.
-## What compilation refuses
-Compilation happens once, when you call `graph()`, and it is the one place this package throws. Everything it catches is a wiring mistake that would otherwise show up as a run that quietly did the wrong thing.
-| | |
-| --- | --- |
-| an edge to a node that does not exist | usually a typo, so the message lists the names that do |
-| an entry that is not a node | the run would have nowhere to start |
-| two nodes with the same name | one of them silently shadows the other |
-| a node nothing reaches | a branch that never runs, and nothing would say so |
-| a node whose edges are **all conditional** | the half-specified case, below |
-<Callout tone="trap" title="A second default edge is refused, not ignored">
-  Edges are tried in order and a default matches everything, so a second one after it can never be taken. That reads as a branch you wired and never see fire: compilation refuses it instead, naming the node.
-</Callout>
-## The half-specified node
-A node with **no** edges is the end of the run: the author wrote none and meant it.
-A node whose edges are *all* conditional is different. A run arriving there when no condition matches has nowhere to go, so it would stop, and report **success**, having skipped every node after it. Saying half of it is the mistake, and compilation refuses it:
-```ts
-edges: [
-  edge("triage", "refund", (ctx) => ctx.outputs.triage === "billing"),
-  // and nothing else leaving "triage" — refused
-];
-```
-Add the default edge, or add `end("triage")` if stopping there is what you meant. Either is a decision; the missing one was not.
-## Inspecting a compiled graph
-A graph answers questions about itself, which is what the workflows in `@spendgraph/harness` are built 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
-```