@spendgraph/harness 0.1.0 → 0.2.0

package/dist/stream/stream.d.ts

@@ -0,0 +1,19 @@
+import type { Emit, HarnessStream } from "./types.js";
+/**
+ * Any workflow, watched while it runs.
+ *
+ * One helper rather than a streaming variant of each of the seven: every
+ * workflow already takes an `emit`, so wrapping the call is all it takes, and a
+ * `stream()` per pattern would be seven places for the same queue to go wrong.
+ *
+ *     const run = streamed((emit, note) =>
+ *       cascade(values, { ...opts, emit, onTier: note })
+ *     );
+ *     for await (const event of run) { ... }
+ *     const result = await run.result;
+ *
+ * The run starts on the call, not on the first read, so a caller who wants only
+ * the result never has to iterate, and a client that connects late still sees
+ * what already happened.
+ */
+export declare function streamed<T>(run: (emit: Emit, note: (data: unknown) => void) => Promise<T>): HarnessStream<T>;

package/dist/stream/stream.js

@@ -0,0 +1,65 @@
+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;
+            });
+        }
+    }
+}
+/**
+ * Any workflow, watched while it runs.
+ *
+ * One helper rather than a streaming variant of each of the seven: every
+ * workflow already takes an `emit`, so wrapping the call is all it takes, and a
+ * `stream()` per pattern would be seven places for the same queue to go wrong.
+ *
+ *     const run = streamed((emit, note) =>
+ *       cascade(values, { ...opts, emit, onTier: note })
+ *     );
+ *     for await (const event of run) { ... }
+ *     const result = await run.result;
+ *
+ * The run starts on the call, not on the first read, so a caller who wants only
+ * the result never has to iterate, and a client that connects late still sees
+ * what already happened.
+ */
+export function streamed(run) {
+    const events = new Events();
+    const result = (async () => {
+        try {
+            const finished = await run((text, stage) => events.push({ type: "token", text, stage }), (data) => events.push({ type: "note", data }));
+            events.push({ type: "result", result: finished });
+            return finished;
+        }
+        finally {
+            events.close();
+        }
+    })();
+    void result.catch(() => { });
+    return {
+        result,
+        [Symbol.asyncIterator]: () => events.drain(),
+    };
+}

package/dist/stream/types.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Where a workflow's tokens go.
+ *
+ * `stage` is which part of the workflow produced them — a tier, a task, a node.
+ * A fan-out interleaves, and without it a stream of four workers reads as one
+ * confused voice. Assignable to a model client's `onText` either way, so a
+ * callback can pass it straight down.
+ */
+export type Emit = (text: string, stage?: string) => void;
+/** What a streamed workflow says while it runs, and what it ends with. */
+export type HarnessEvent<T> = {
+    type: "token";
+    text: string;
+    stage?: string;
+} | {
+    type: "note";
+    data: unknown;
+} | {
+    type: "result";
+    result: T;
+};
+/** A workflow as it happens, and the same run once it is over. */
+export interface HarnessStream<T> extends AsyncIterable<HarnessEvent<T>> {
+    /**
+     * The finished run.
+     *
+     * Resolves whether or not anyone iterated, and rejects where the workflow
+     * itself would have — streaming changes what you can watch, not what happens.
+     */
+    result: Promise<T>;
+}

package/dist/stream/types.js

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

package/docs/README.md

@@ -0,0 +1,41 @@
+# Workflows
+
+A workflow is a wiring pattern that keeps being rediscovered. Each one is a
+graph you would otherwise hand-roll, with the pricing and the rollout already
+attached, so a run is recorded rather than reconstructed afterwards.
+
+| | | Built |
+| --- | --- | --- |
+| [`refine`](./refine.md) | draft, judge, revise until a bar is met | ✓ |
+| [`route`](./route.md) | classify first, then dispatch to a specialist | ✓ |
+| [`chain`](./chain.md) | steps in sequence, each on the last's output, with a gate between | ✓ |
+| [`parallel`](./parallel.md) | the same call N times, or N sections at once | ✓ |
+| [`orchestrate`](./orchestrate.md) | a lead decomposes and delegates to workers | ✓ |
+| [`loop`](./loop.md) | tools in a loop until the model stops asking | ✓ |
+| [`cascade`](./cascade.md) | try the cheap model, escalate only when it will not do | ✓ |
+
+## What every one of them owes you
+
+**A rollout shape.** The result hands to `prompt.report()` without being
+translated, because a workflow run *is* a rollout with several steps.
+
+**Every step, including the rejected ones.** A refine loop that keeps only the
+winner cannot say what the answer cost. A router that records only the branch it
+ran cannot tell a missing branch from a miscalibrated one.
+
+**A ceiling.** Each of these spends more than one call, and the interesting ones
+spend an unbounded amount. The ceiling is in **tokens**, not money: this package
+cannot price a call — that happens on the server, after the fact — so a budget in
+micro-dollars here would be a guess.
+
+## Why they are not in `graph`
+
+`graph` is the mechanism: nodes, edges, a run. These are the arrangements of it
+worth naming, each with its own failure mode — a chain needs a gate or one bad
+step poisons the rest, voting needs an odd N, a loop needs a ceiling. Putting
+them beside the mechanism would suggest the mechanism is opinionated. It is not.
+
+`route` compiles down to a graph and adds nothing to it. `refine` does not,
+because it is a **loop**: `graph` is a DAG whose `maxSteps` error reads "a
+conditional edge never turns false", so a cycle there is a runaway to be stopped
+rather than a shape to express.

package/docs/cascade.md

@@ -0,0 +1,165 @@
+# `cascade`
+
+Try the cheap model. Escalate only when its answer will not do.
+
+```ts
+const result = await cascade(values, {
+  tiers: [
+    { name: "haiku", run: (v) => haiku.bind(prompt).invoke(v) },
+    { name: "opus", run: (v) => opus.bind(prompt).invoke(v) },
+  ],
+  accept: (answer) => (answer.data as Reply).confidence >= 0.8,
+});
+
+result.tier;        // "haiku" — who answered
+result.escalated;   // [] — who did not
+result.accepted;    // true
+```
+
+---
+
+## The flow
+
+```
+                         values
+                           │
+                           ▼
+                  ┌─────────────────┐
+                  │  tier 1  haiku  │   cheap, tried first
+                  └────────┬────────┘
+                           │
+                    ┌──────┴──────┐
+                    │  accept()?  │
+                    └──────┬──────┘
+              yes ─────────┼───────── no, or it threw
+               │           │                │
+               │           │                ▼
+               │           │       ┌─────────────────┐
+               │           │       │  tier 2  opus   │   the fallback
+               │           │       └────────┬────────┘
+               │           │                │
+               │           │         ┌──────┴──────┐
+               │           │         │  accept()?  │
+               │           │         └──────┬──────┘
+               ▼           ▼                ▼        no → returned anyway,
+            ┌──────────────────────────────────┐        accepted: false
+            │  tier · escalated · accepted     │
+            └──────────────────────────────────┘
+```
+
+---
+
+## What it is not
+
+**Not `route`.** A router classifies *before* it has seen an answer, and commits.
+A cascade judges the answer itself, which is the only evidence that actually
+says whether the cheap model coped.
+
+**Not `refine`.** Refining revises with the same model and feeds back what was
+wrong. Cascading changes the model and asks again from scratch. Use `refine`
+when the draft is nearly right; use `cascade` when the model is out of its depth.
+
+---
+
+## `accept` is required
+
+There is no default and there cannot be one. Without `accept` this is a list of
+models with no reason to stop at any of them — the first would always answer, and
+the rest would be decoration.
+
+It runs on the answer, so it can read anything the tier returned:
+
+```ts
+accept: (answer) => (answer.data as Reply).confidence >= 0.8   // a self-report
+accept: (answer) => answer.output.length > 200                  // a floor
+accept: (answer) => schema.safeParse(answer.data).success       // a shape
+accept: async (answer) => (await judge(answer)).ok              // another model
+```
+
+The last one costs a call per tier and is usually worth it only when the tiers
+are far apart in price.
+
+---
+
+## A tier that throws escalates
+
+An overloaded cheap model is the case this exists for, so a throw hands on to the
+next rung rather than ending the run. So does a reply with `status: "failed"`.
+
+Both are recorded **distinguishably**:
+
+```ts
+result.history.map((r) => r.escalatedBy);
+// ["failed", "rejected", undefined]
+```
+
+`failed` is the call falling over. `rejected` is `accept` saying no. They want
+opposite fixes — a model that is down against a bar set too high — and a record
+that collapsed them into "escalated" could not tell you which you have.
+
+---
+
+## When nothing is accepted
+
+The **last tier that produced an answer** comes back, with `accepted: false`. The
+tiers are ordered by capability, so the most capable answer is the closest thing
+to a best effort, and throwing it away to return an error would waste the
+expensive call you just paid for.
+
+A tier that threw produced nothing, so it cannot be the fallback however late it
+ran:
+
+```
+  haiku  → "weak"      rejected
+  opus   → threw       failed
+  ────────────────────────────────
+  tier: "haiku", accepted: false
+```
+
+Only when **no** tier produced anything at all does the run fail, with
+`stoppedBy: "failed"` and the last error.
+
+---
+
+## The honest caveat
+
+**A cascade can cost more than not having one.** If the cheap tier is rejected
+most of the time, every run pays for it and then pays for the expensive model
+anyway.
+
+Which is why the totals count every tier tried:
+
+```ts
+result.inputTokens;   // haiku's and opus's, not the winner's
+```
+
+and why the thing to watch in production is the distribution of `result.tier`:
+
+```
+  tier=haiku  91%   ← paying off
+  tier=haiku  22%   ← paying for two calls to do one model's work
+```
+
+At the second number, delete the cascade and call the expensive model directly.
+There is no threshold that is right for everyone: it depends on the price gap
+between the tiers and on how much a rejected cheap answer costs relative to the
+expensive one.
+
+---
+
+## The ceiling
+
+`maxTokens` is checked before each tier, so it is never crossed rather than
+merely noticed. A cascade that has spent its budget stops with
+`stoppedBy: "tokens"` and returns the best answer it has — which is the fallback
+rule again, not a special case.
+
+---
+
+## How the files fit
+
+| | |
+| --- | --- |
+| `cascade.ts` | the walk down the tiers, and the result |
+| `tier.ts` | running one tier, turning a throw into an escalation, choosing the fallback |
+| `types.ts` | `Tier`, `Answer`, `TierRecord`, the options and the result |

package/docs/chain.md

@@ -0,0 +1,134 @@
+# chain
+
+Steps in sequence, each on the last one's output, with a gate between.
+
+```ts
+import { chain } from "@spendgraph/harness";
+
+const result = await chain(
+  { transcript },
+  {
+    steps: [
+      {
+        name: "extract",
+        run: ({ transcript }) => llm.call(extractPrompt(transcript), { schema: CHANGES }),
+        gate: (output) =>
+          JSON.parse(output.output).items.length > 0
+            ? { ok: true }
+            : { ok: false, reason: "found no changes to write about" },
+      },
+      {
+        name: "write",
+        run: (previous) => llm.call(writePrompt(previous)),
+        gate: (output) =>
+          output.output.length <= 1200
+            ? { ok: true }
+            : { ok: false, reason: `${output.output.length} characters, limit is 1200` },
+      },
+      { name: "translate", run: (previous) => llm.call(translatePrompt(previous)) },
+    ],
+  }
+);
+
+result.ran;        // ["extract", "write", "translate"]
+result.stoppedAt;  // null, or the step whose gate refused
+result.reason;     // what the gate said
+```
+
+`run` is handed whatever the step before it returned — the values the chain was
+called with, for the first one.
+
+---
+
+## The gate is the point
+
+Without one, a stage that produced nothing useful is passed to the next stage,
+which confidently works on it, and the stage after that works on *that*. You get
+a polished paragraph three calls later that is about nothing, and no indication
+which stage went wrong.
+
+```
+   extract ──► gate ──► write ──► gate ──► translate ──► output
+                 │                  │
+                 └── refuses ───────┴──► stops, and says which
+```
+
+A refused gate stops the chain and names the step. The tests pin the thing that
+matters: the next step **is not called**.
+
+**The output the gate refused is kept.** It is recorded as a completed step with
+whatever it produced, and the gate is recorded separately as the failure. The
+rejected output is the evidence for why the gate fired at all — losing it leaves
+you with "extract failed" and nothing to look at.
+
+```
+  steps:  extract (completed, "nothing found")
+          gate_extract (failed, "no items")
+```
+
+---
+
+## Why not one prompt
+
+Each call gets simpler instructions and does its one job better. Splitting trades
+latency for accuracy — and you find out *which* stage went wrong instead of
+receiving one bad paragraph with no explanation.
+
+The cost is real: three sequential calls is three times the wall-clock, and they
+cannot be parallelised because each needs the last. `chain` buys accuracy with
+latency, where `parallel` buys latency with tokens.
+
+---
+
+## When it wins
+
+The task decomposes into stages you can name **in advance**, and each stage's
+output is checkable.
+
+- extract → validate → transform
+- outline → check it covers the brief → draft
+- draft → translate → verify the placeholders survived
+
+## When it does not
+
+**The stages are only separable on paper.** If each one needs the full context
+anyway, you have paid for three calls to do one call's work.
+
+**You do not know the stages until you have read the input.** That is
+`orchestrate`, not `chain`.
+
+**Nothing between the stages is checkable.** Without gates this is a `graph` with
+extra ceremony — use `graph` directly.
+
+---
+
+## How it differs from its neighbours
+
+`refine` loops on the **same** step until it is good enough. `chain` moves
+**forward** through different steps. Refine asks "is this good yet?"; chain asks
+"is this good enough to continue?"
+
+`graph` can already express a chain — it is a line of nodes. `chain` is the named
+case with the gate built in, the way `route` is the named case for branching. The
+value is not the mechanism; it is that the gate is on by default rather than
+something you remember to add.
+
+---
+
+## How the files fit
+
+```
+   types.ts     the contract
+        ▲
+   step.ts      a stage as a node
+   gate.ts      a gate as its own node, and the refusal it throws
+        ▲
+   chain.ts     compile · run · shape
+```
+
+`step.ts` and `gate.ts` are siblings — neither knows about the other. `chain.ts`
+is the only file that knows they alternate.
+
+A stage reads its input from `ctx.outputs` rather than having it threaded in,
+because a gate may sit between two stages and the gate's return is not what the
+next stage wants — the stage before it is.