@spendgraph/harness 0.2.0 → 0.2.1

package/README.md

@@ -9,7 +9,11 @@ your provider ships. It is built on `@spendgraph/prompt`, `@spendgraph/tools`
 and `@spendgraph/graph`, and none of it reasons — every workflow here directs a
 model call you supply.
 
-Six shapes, all built. Each is a graph you would otherwise hand-roll, with the
+```sh
+npm install @spendgraph/harness
+```
+
+Seven shapes, all built. Each 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.
 
@@ -23,6 +27,117 @@ reconstructed afterwards.
 | **`loop`** | tools in a loop until the model stops asking | open-ended work with a tool surface and a step ceiling |
 | **`cascade`** | try the cheap model, escalate only when it will not do | most inputs are easy and a few are not, and you can tell which |
 
+## Two of them, in full
+
+`refine` is generate and critique until it passes:
+
+```ts
+import { refine } from "@spendgraph/harness";
+
+const result = await refine({
+  attempt: (feedback) =>
+    llm.call([{ role: "user", content: feedback ? `${brief}\n\nFix: ${feedback}` : brief }]),
+  judge: (attempt) =>
+    attempt.output.length < 900
+      ? { accepted: true }
+      : { accepted: false, feedback: "Cut it to under 900 characters." },
+  rounds: 3,
+  maxTokens: 40_000,
+});
+
+result.output;      // the winning draft
+result.accepted;    // false when the rounds or the ceiling ran out first
+result.stoppedBy;   // "accepted" | "rounds" | "tokens" | "failed"
+result.history;     // every attempt, including the rejected ones
+```
+
+One `attempt` callback rather than separate generate and revise, because in
+practice they are the same prompt with one extra paragraph. `feedback` is null
+on the first round and the judge's note after it.
+
+`route` classifies, then dispatches:
+
+```ts
+import { route } from "@spendgraph/harness";
+
+const result = await route(
+  { subject, body },
+  {
+    classify: ({ subject }) => (/refund|charge/i.test(String(subject)) ? "billing" : "general"),
+    routes: {
+      billing: (values) => billingAgent(values),
+      general: (values) => generalAgent(values),
+    },
+    fallback: (values) => humanQueue(values),
+  }
+);
+
+result.route;      // the branch that ran, or null when the fallback did
+result.classified; // what the classifier said, whether or not it was used
+```
+
+**`fallback` is required.** A router that can fail to route fails in production
+at 3am, and "unknown" is a class every classifier eventually returns. `classify`
+is often better as plain code than a model — the regex above is free and never
+invents a category.
+
+## Calling convention
+
+Five take the run's values first; two have nothing to substitute into and take
+options alone.
+
+```ts
+await chain(values, opts);
+await route(values, opts);
+await parallel(values, opts);
+await orchestrate(values, opts);
+await cascade(values, opts);
+
+await refine(opts);
+await loop(opts);
+```
+
+## What every one of them owes you
+
+Each result is a `GraphResult` first, so it reports as a rollout without
+translation:
+
+```ts
+result.status;       // "completed" | "failed"
+result.output;
+result.steps;        // every step, the rejected ones included
+result.inputTokens;  // summed across the whole run
+result.outputTokens;
+result.stoppedBy;    // never the same value as "it finished"
+```
+
+- Every step recorded, including the ones that were rejected — a refine loop that
+  keeps only the winner cannot say what it cost.
+- A budget ceiling, because each of these spends more than one call and the
+  interesting ones spend an unbounded amount.
+- A `stoppedBy`, because "it finished" and "it gave up" must never look the same.
+
+Tokens are summed across **every** attempt rather than the winning one. The only
+question a refine loop has to answer is whether refining paid, and a total that
+counted the winner alone would always say yes.
+
+## Watching one run
+
+`streamed()` wraps any workflow and hands it an `emit`, so the tokens go
+somewhere while it runs instead of arriving all at once at the end.
+
+```ts
+import { streamed } from "@spendgraph/harness";
+
+const running = streamed((emit) => refine({ attempt, judge, emit }));
+
+for await (const event of running) {
+  if (event.type === "token") res.write(event.text);
+}
+
+const result = await running.result;
+```
+
 ## Inner and outer
 
 The provider's SDK is the **inner** harness: it drives one model call, and on
@@ -47,15 +162,6 @@ step poisons the rest, voting needs an odd N, a loop needs a ceiling and every
 one of them needs a budget. Putting them beside the mechanism would suggest the
 mechanism is opinionated. It is not.
 
-## What every one of them owes you
-
-- A `GraphResult`, so the run reports as a rollout without translation.
-- Every step recorded, including the ones that were rejected — a refine loop that
-  keeps only the winner cannot say what it cost.
-- A budget ceiling, because each of these spends more than one call and the
-  interesting ones spend an unbounded amount.
-- A `stoppedBy`, because "it finished" and "it gave up" must never look the same.
-
 ## What is missing
 
 Every workflow here is **single-run**: it starts, it finishes, and it holds
@@ -67,13 +173,6 @@ That needs somewhere to persist a run, which is a decision about the product and
 not a wiring pattern. It is written up in [`PLAN.md`](./PLAN.md) rather than
 quietly folded in.
 
-## What is next
-
-Phase one is done: the context manager (`compact`), lifecycle hooks, tool
-annotations, budget signalling and `cascade`. What is left is **durable state** —
-a run that can wait for a person and be resumed — which [`PLAN.md`](./PLAN.md)
-plans with the decisions and the tests it needs.
-
 ## Documentation
 
 Each built workflow has a page with worked examples, the cases it suits, and the
@@ -87,3 +186,7 @@ cases it does not.
 - [`docs/orchestrate.md`](./docs/orchestrate.md) — a lead decomposes and delegates
 - [`docs/cascade.md`](./docs/cascade.md) — cheap first, escalate on rejection
 - [`docs/README.md`](./docs) — the seven patterns, and what each owes you
+
+## License
+
+MIT

package/dist/cascade/cascade.js

@@ -11,17 +11,6 @@ function checkTiers(tiers) {
         seen.add(tier.name);
     }
 }
-/**
- * Try the cheap model, and escalate only when its answer will not do.
- *
- * Not `route`, which chooses before it has seen an answer. Not `refine`, which
- * revises with the same model. This is the one lever that spends less by
- * default and more only on the inputs that turn out to need it.
- *
- * Whether it pays depends entirely on how often the first tier is accepted, so
- * every tier tried is recorded and its tokens counted — a total that hid the
- * rejected attempts would report a saving on every run.
- */
 export async function cascade(values, opts) {
     const startedAt = Date.now();
     checkTiers(opts.tiers);

package/dist/cascade/tier.js

@@ -1,15 +1,8 @@
-/** What one tier consumed, both halves, whether or not its answer was used. */
 export function tokensOf(answer) {
     if (!answer)
         return 0;
     return (answer.inputTokens ?? 0) + (answer.outputTokens ?? 0);
 }
-/**
- * One tier as a step, named for the tier rather than its position.
- *
- * A rollout that read `tier_0` would need the config beside it to mean anything,
- * and the config is the thing most likely to have changed since.
- */
 export function tierStep(index, record) {
     return {
         index,
@@ -22,13 +15,6 @@ export function tierStep(index, record) {
         outputTokens: record.answer?.outputTokens,
     };
 }
-/**
- * Runs one tier, turning a throw into an escalation.
- *
- * An overloaded cheap model is the case this workflow exists for, so a tier that
- * falls over must hand on rather than end the run. The next rung is the whole
- * point of having one.
- */
 export async function attempt(run, values, emit) {
     try {
         const answer = await run(values, emit);
@@ -41,13 +27,6 @@ export async function attempt(run, values, emit) {
         return { answer: null, error: cause instanceof Error ? cause.message : String(cause) };
     }
 }
-/**
- * The tier to fall back to when nothing was accepted.
- *
- * The last that produced anything, because the tiers are ordered by capability
- * and the most capable answer is the closest thing to a best effort. A tier that
- * threw produced nothing, so it cannot be the fallback however late it ran.
- */
 export function fallback(history) {
     return [...history].reverse().find((record) => record.answer !== null);
 }

package/dist/chain/chain.js

@@ -12,7 +12,6 @@ function assertNamed(steps) {
         seen.add(step.name);
     }
 }
-/** Every node in order: a stage, then its gate when it has one. */
 function nodesFor(steps) {
     const nodes = [];
     const order = [];
@@ -28,13 +27,6 @@ function nodesFor(steps) {
     }
     return { nodes, order };
 }
-/**
- * Steps in sequence, each on the last one's output, with a gate between.
- *
- * Compiled to a graph, which already stops at the node that failed and records
- * every node that ran before it — which is the whole reason to gate a chain
- * rather than let it run to the end and hand back something plausible.
- */
 export async function chain(values, opts) {
     assertNamed(opts.steps);
     const { nodes, order } = nodesFor(opts.steps);

package/dist/chain/gate.js

@@ -1,5 +1,4 @@
 import { node } from "@spendgraph/graph";
-/** The gate node's name for a stage, and the key its verdict is stored under. */
 export function gateName(step) {
     return `gate_${step}`;
 }
@@ -13,13 +12,6 @@ export class GateRefused extends Error {
         this.name = "GateRefused";
     }
 }
-/**
- * A gate as its own node, so a refusal is a step of its own.
- *
- * Folding the check into the stage would lose the output it refused — and the
- * rejected output is the evidence for why the gate fired at all. This way the
- * stage records what it produced and the gate records what was wrong with it.
- */
 export function gateNode(step) {
     return node({
         name: gateName(step.name),

package/dist/chain/step.js

@@ -1,11 +1,4 @@
 import { node } from "@spendgraph/graph";
-/**
- * A stage as a node.
- *
- * `previous` is read from the context rather than threaded through the input,
- * because a gate may sit between two stages and its return is not what the next
- * stage wants — the stage before it is.
- */
 export function stepNode(step, previous) {
     return node({
         name: step.name,

package/dist/loop/act.js

@@ -1,6 +1,5 @@
 import { answerOf, isFinished } from "@spendgraph/tools";
 import { ask, blockedResult, tell } from "./hooks.js";
-/** One tool call as a step, failures included. */
 export function callStep(index, result) {
     return {
         index,
@@ -12,13 +11,6 @@ export function callStep(index, result) {
         latencyMs: result.latencyMs,
     };
 }
-/**
- * Runs what the model asked for, in the order it asked.
- *
- * Never throws — `invoke` returns a failed result rather than raising, so a
- * tool that fell over is something the model can read and try around, not
- * something that ends the run.
- */
 export async function act(tools, calls, hooks = {}) {
     const results = [];
     for (const call of calls) {
@@ -31,12 +23,6 @@ export async function act(tools, calls, hooks = {}) {
     }
     return results;
 }
-/**
- * The answer, when the model said it was done.
- *
- * Reading `finish` here is what separates "it is done" from "it stopped asking",
- * which otherwise look identical from outside and are opposite problems.
- */
 export function finished(results) {
     const done = results.find((result) => isFinished(result));
     return done ? answerOf(done) : null;

package/dist/loop/compact.js

@@ -1,17 +1,7 @@
 const DEFAULT_AT = 0.7;
 const DEFAULT_KEEP = 4;
-/**
- * Whether the context is big enough to be worth summarising.
- *
- * Measured on the **last turn's input tokens**, not on what the run has spent.
- * Spend only ever rises, so a threshold on it fires once and then every turn
- * after; the input count is the size of what is actually being resent, and it
- * falls the moment a compaction lands — which is what stops this firing twice
- * for the same reason.
- */
 export function shouldCompact(compact, last, results, maxTokens) {
     const keep = compact.keep ?? DEFAULT_KEEP;
-    // Nothing to gain: everything left would be kept anyway.
     if (results.length <= keep)
         return false;
     if (compact.after !== undefined && results.length > compact.after)
@@ -21,7 +11,6 @@ export function shouldCompact(compact, last, results, maxTokens) {
     const context = last.inputTokens ?? 0;
     return context >= (compact.at ?? DEFAULT_AT) * maxTokens;
 }
-/** The summary as a tool result, so the next turn reads it like any other. */
 export function summaryResult(summary, replaced) {
     return {
         name: "compacted",
@@ -31,7 +20,6 @@ export function summaryResult(summary, replaced) {
         latencyMs: 0,
     };
 }
-/** The summarising call as a step, because deciding what to forget is not free. */
 export function compactStep(index, summary, replaced) {
     return {
         index,
@@ -44,12 +32,6 @@ export function compactStep(index, summary, replaced) {
         outputTokens: summary.outputTokens,
     };
 }
-/**
- * Replaces the older results with one summary, in place.
- *
- * The most recent `keep` survive verbatim: summarising what just happened is
- * how a loop forgets what it was in the middle of doing.
- */
 export function applyCompaction(results, summary, keep) {
     const older = results.splice(0, results.length - keep);
     const summarised = summaryResult(summary, older.length);

package/dist/loop/hooks.js

@@ -1,10 +1,3 @@
-/**
- * Runs a hook that can refuse, treating its own failure as permission.
- *
- * A hook that throws is a bug in the guardrail, and taking the run down with it
- * is worse than the thing it was guarding against — the call it was checking
- * has not happened yet, and the next hook still gets its say.
- */
 export async function ask(hook, ...args) {
     if (!hook)
         return null;
@@ -17,7 +10,6 @@ export async function ask(hook, ...args) {
         return null;
     }
 }
-/** Runs an observing hook. Its failure changes nothing; it was only watching. */
 export async function tell(hook, arg) {
     if (!hook)
         return;
@@ -25,10 +17,8 @@ export async function tell(hook, arg) {
         await hook(arg);
     }
     catch {
-        // Observation only.
     }
 }
-/** A refused call, in the shape the model already knows how to read. */
 export function blockedResult(call, reason) {
     return {
         name: call.name,

package/dist/loop/loop.js

@@ -3,17 +3,6 @@ import { applyCompaction, compactStep, DEFAULT_KEEP, shouldCompact } from "./com
 import { ask, tell } from "./hooks.js";
 import { tokensOf, turnStep } from "./turn.js";
 const DEFAULT_MAX_TURNS = 8;
-/**
- * Model, tools, model again, until it stops asking.
- *
- * Not compiled to a graph: this is a cycle, and `@spendgraph/graph` is a DAG
- * whose step ceiling exists to stop one. Same reasoning as `refine`.
- *
- * What this adds over a provider SDK's own tool loop is the part that is always
- * hand-rolled and always wrong the same way: a ceiling that is checked before
- * the spend rather than after, every turn and every tool call recorded, and
- * `finished` told apart from `quiet`.
- */
 export async function loop(opts) {
     const startedAt = Date.now();
     const maxTurns = Math.max(1, opts.maxTurns ?? DEFAULT_MAX_TURNS);
@@ -25,13 +14,6 @@ export async function loop(opts) {
     let answer = null;
     let stoppedBy = "turns";
     const compactions = { count: 0, replaced: 0 };
-    /**
-     * Summarise the older results, if the context has grown enough to be worth it.
-     *
-     * Failing is survivable: the run carries on with the history it has rather
-     * than ending over a summary it could not write. Losing the compaction costs
-     * tokens; losing the run costs the work.
-     */
     const compactIfNeeded = async () => {
         if (!opts.compact || !shouldCompact(opts.compact, last, results, opts.maxTokens))
             return;
@@ -46,7 +28,6 @@ export async function loop(opts) {
             compactions.replaced += replaced;
         }
         catch {
-            // Carry on uncompacted.
         }
     };
     const finish = (status, error) => ({
@@ -110,8 +91,6 @@ export async function loop(opts) {
             break;
         }
         if (calls.length === 0) {
-            // It said something and asked for nothing. Done, or lost — the caller
-            // cannot tell, which is why `finish` is worth offering it.
             stoppedBy = "quiet";
             break;
         }

package/dist/loop/turn.js

@@ -1,8 +1,6 @@
-/** What one turn consumed. Both halves, since the history is resent every time. */
 export function tokensOf(turn) {
     return (turn.inputTokens ?? 0) + (turn.outputTokens ?? 0);
 }
-/** One model call as a step. */
 export function turnStep(index, at, turn) {
     return {
         index,

package/dist/orchestrate/orchestrate.js

@@ -9,16 +9,6 @@ function tokens(steps) {
     }
     return { inputTokens, outputTokens };
 }
-/**
- * A lead decomposes, workers do the pieces, the lead puts it back together.
- *
- * The workflow for work whose shape is not known until the input is read — the
- * difference from `chain`, where the stages are named in advance.
- *
- * It is also the one that can spend the most: the lead decides how many calls
- * to make, so `maxWorkers` is a cap on something a model chose rather than on
- * something you did.
- */
 export async function orchestrate(values, opts) {
     const startedAt = Date.now();
     const steps = [];
@@ -44,8 +34,6 @@ export async function orchestrate(values, opts) {
     steps.push(planStep(steps.length, plan, dropped));
     opts.onPlan?.(plan, dropped);
     if (subtasks.length === 0) {
-        // Nothing to delegate. Handing back the lead's own words beats synthesising
-        // over an empty list, which invents an answer from nothing.
         return finish("completed", "planned-nothing", plan.output ?? "");
     }
     const spentOnPlan = (plan.inputTokens ?? 0) + (plan.outputTokens ?? 0);

package/dist/orchestrate/plan.js

@@ -1,14 +1,4 @@
 const DEFAULT_MAX_WORKERS = 5;
-/**
- * The subtasks that will run, and the ones the cap refused.
- *
- * Dropping the tail rather than the head: a lead asked for the most important
- * piece first usually gives it first, and truncating from the front would throw
- * away exactly what it thought mattered.
- *
- * Duplicated names are made unique rather than rejected — a lead naming two
- * sections "summary" is a wording problem, not a reason to lose the run.
- */
 export function capped(plan, max = DEFAULT_MAX_WORKERS) {
     const limit = Math.max(1, max);
     const seen = new Map();
@@ -19,7 +9,6 @@ export function capped(plan, max = DEFAULT_MAX_WORKERS) {
     });
     return { subtasks: named.slice(0, limit), dropped: named.slice(limit) };
 }
-/** The lead's own call as a step, because deciding is not free. */
 export function planStep(index, plan, dropped) {
     return {
         index,

package/dist/orchestrate/work.js

@@ -1,11 +1,4 @@
 import { parallel } from "../parallel/index.js";
-/**
- * Every worker at once.
- *
- * Delegated to `parallel` rather than fanned out again here: it already caps the
- * concurrency, already turns a thrown worker into a result so the others land,
- * and already numbers the steps by declaration so two runs can be compared.
- */
 export function work(subtasks, values, opts) {
     return parallel(values, {
         tasks: subtasks.map((subtask) => ({
@@ -16,12 +9,9 @@ export function work(subtasks, values, opts) {
         concurrency: opts.concurrency,
         minSuccess: opts.minSuccess ?? subtasks.length,
         onTask: opts.onWork,
-        // `orchestrate` synthesises with the lead rather than merging here, so this
-        // only has to hand the results back untouched.
         merge: (results) => results,
     });
 }
-/** The lead's second call as a step. */
 export function synthesisStep(index, outcome) {
     return {
         index,

package/dist/parallel/merge.js

@@ -1,9 +1,3 @@
-/**
- * The same task, N times over, for voting.
- *
- * An odd N on purpose — an even one ties, and a tie has no answer that is not
- * arbitrary. Ask for an even number and you get the next one up.
- */
 export function repeat(name, times, run) {
     const odd = Math.max(1, times % 2 === 0 ? times + 1 : times);
     return Array.from({ length: odd }, (_, at) => ({
@@ -11,7 +5,6 @@ export function repeat(name, times, run) {
         run: (values) => run(values, at),
     }));
 }
-/** How a value is compared when voting. Its own text, or the whole thing. */
 function ballot(value) {
     if (value &&
         typeof value === "object" &&
@@ -20,16 +13,6 @@ function ballot(value) {
     }
     return typeof value === "string" ? value : JSON.stringify(value);
 }
-/**
- * The answer most of them gave.
- *
- * Voting is worth the tokens where a model is right most of the time and wrong
- * differently each time — the wrong answers scatter and the right one repeats.
- * It buys nothing where the model is confidently wrong the same way every time,
- * which is the failure it is easiest to mistake it for a fix for.
- *
- * Ties go to the first declared, so the result is the same on every run.
- */
 export function majority(results) {
     const done = results.filter((r) => r.status === "completed");
     if (done.length === 0)

package/dist/parallel/parallel.js

@@ -15,16 +15,6 @@ function stringify(value) {
         return "";
     return typeof value === "string" ? value : JSON.stringify(value);
 }
-/**
- * Every task at once, then one answer out of what came back.
- *
- * Not compiled to a graph like `route` and `chain`: `@spendgraph/graph` walks one
- * node at a time and picks a single edge, so a fan-out is not a shape it can
- * express. The concurrency comes from `mapLimit`, which already exists.
- *
- * A task that throws is a result, not an exception — the point of running five
- * is that the other four still land.
- */
 export async function parallel(values, opts) {
     if (opts.tasks.length === 0)
         throw new Error("A parallel run needs at least one task.");

package/dist/parallel/task.js

@@ -1,7 +1,6 @@
 function counted(value) {
     return value && typeof value === "object" ? value : {};
 }
-/** Runs one task. Never throws — a failure is a result, so the others still land. */
 export async function runTask(task, values, emit) {
     try {
         const value = await task.run(values, (text, stage) => emit?.(text, stage ?? task.name));
@@ -18,13 +17,6 @@ export async function runTask(task, values, emit) {
         };
     }
 }
-/**
- * One task as a step.
- *
- * Indexed by where it was declared rather than when it landed: a fan-out that
- * numbered its steps by completion order would record a different run every
- * time for the same work, which makes two runs impossible to compare.
- */
 export function taskStep(index, result) {
     const { output, model } = counted(result.value);
     return {

package/dist/refine/attempt.js

@@ -1,19 +1,6 @@
-/**
- * What one attempt consumed.
- *
- * Both halves, because a refine loop's cost is dominated by the input it resends
- * every round — the draft, the critique and the instruction to try again.
- */
 export function tokensOf(attempt) {
     return (attempt.inputTokens ?? 0) + (attempt.outputTokens ?? 0);
 }
-/**
- * One attempt as a step.
- *
- * Recorded whether it was accepted or not: the rejected drafts are the evidence
- * for whether refining paid at all, and a loop that keeps only the winner cannot
- * say what the answer cost.
- */
 export function attemptStep(index, round, attempt) {
     return {
         index,
@@ -26,7 +13,6 @@ export function attemptStep(index, round, attempt) {
         outputTokens: attempt.outputTokens,
     };
 }
-/** Both halves of every attempt so far, for the result's totals. */
 export function totalTokens(steps) {
     let inputTokens = 0;
     let outputTokens = 0;

package/dist/refine/judge.js

@@ -1,4 +1,3 @@
-/** One verdict as a step, so a run says why each draft was turned down. */
 export function judgeStep(index, round, verdict) {
     return {
         index,
@@ -7,16 +6,6 @@ export function judgeStep(index, round, verdict) {
         status: "completed",
     };
 }
-/**
- * The attempt to hand back when nothing was accepted.
- *
- * Highest score wins, and the last attempt wins when nothing was scored — a loop
- * that improves each round has its best work at the end, and returning the first
- * draft after three revisions would throw the work away.
- *
- * Here rather than in the loop because the choice is the judge's: it is made on
- * the verdicts, and a judge that never scores gets the fallback.
- */
 export function best(history) {
     const scored = history.filter((r) => typeof r.verdict.score === "number");
     if (scored.length === 0)

package/dist/refine/refine.js

@@ -1,14 +1,6 @@
 import { attemptStep, tokensOf, totalTokens } from "./attempt.js";
 import { best, judgeStep } from "./judge.js";
 const DEFAULT_ROUNDS = 3;
-/**
- * Draft, judge, revise, until it is good enough or the budget is out.
- *
- * The pattern worth naming when there is a clear criterion and a first draft
- * rarely meets it. Every attempt and every judgement is recorded, the rejected
- * ones included: a loop that keeps only the winner cannot say what the answer
- * cost, and the rejected drafts are the evidence for whether refining paid.
- */
 export async function refine(opts) {
     const startedAt = Date.now();
     const rounds = Math.max(1, opts.rounds ?? DEFAULT_ROUNDS);

package/dist/route/classify.js

@@ -1,25 +1,9 @@
 import { node } from "@spendgraph/graph";
-/** The classifier's node name, and the key its decision is stored under. */
 export const CLASSIFY = "classify";
-/**
- * The branch that runs when no other one does.
- *
- * Declared here rather than beside the dispatch it names, because `decide` is
- * what produces it — and the other way round leaves the two files importing
- * each other, which is the thing a reader has to stop and untangle.
- */
 export const FALLBACK = "fallback";
-/** A bare string is shorthand for `{ route }`. */
 export function normalise(value) {
     return typeof value === "string" ? { route: value } : value;
 }
-/**
- * Which branch runs.
- *
- * A class no branch handles falls back, and so does one the classifier is not
- * sure enough about — a hedged guess sent to the wrong specialist is worse than
- * the general path.
- */
 export function decide(said, names, minConfidence) {
     const known = names.includes(said.route);
     const confident = minConfidence === undefined ||
@@ -32,13 +16,6 @@ export function decide(said, names, minConfidence) {
         reason: said.reason,
     };
 }
-/**
- * The entry node.
- *
- * Its return is what the edges read, so the decision travels through the graph's
- * own context rather than a variable closed over from outside — which means a
- * finished run can be read apart from `outputs.classify` alone.
- */
 export function classifier(opts, names) {
     return node({
         name: CLASSIFY,
@@ -46,7 +23,6 @@ export function classifier(opts, names) {
             const said = normalise(await opts.classify(input, ctx));
             return {
                 ...decide(said, names, opts.minConfidence),
-                // The step records what the classifier said, not what we did about it.
                 output: said.route,
                 model: said.model,
                 inputTokens: said.inputTokens,

package/dist/route/dispatch.js

@@ -6,7 +6,6 @@ function handler(name, run) {
         run: (input, ctx) => run(input, ctx),
     });
 }
-/** One node per branch, plus the fallback. */
 export function branches(opts, names) {
     return [
         ...names.map((name) => handler(name, opts.routes[name])),
@@ -16,13 +15,6 @@ export function branches(opts, names) {
 function taken(ctx) {
     return ctx.outputs.classify?.taken ?? FALLBACK;
 }
-/**
- * Classify, then exactly one branch, then stop.
- *
- * Conditional edges first and the fallback unconditional last, because `graph`
- * refuses the other order — an unconditional edge ahead of a conditional one is
- * a router whose default hides a branch, and it would never be reached.
- */
 export function edgesTo(names) {
     return [
         ...names.map((name) => edge("classify", name, (ctx) => taken(ctx) === name)),

package/dist/route/route.js

@@ -2,15 +2,6 @@ import { graph } from "@spendgraph/graph";
 import { runGraph } from "../stream/graph.js";
 import { CLASSIFY, classifier, FALLBACK } from "./classify.js";
 import { branches, edgesTo } from "./dispatch.js";
-/**
- * Classify once, then hand the work to the branch built for it.
- *
- * Compiled to a graph rather than looped here: `@spendgraph/graph` already
- * validates that every branch is reachable and that no default sits in front of
- * one, already records a step per node with its tokens, and already returns the
- * rollout shape. A second execution engine in this package would be a second
- * thing to keep right.
- */
 export async function route(values, opts) {
     const names = Object.keys(opts.routes);
     const flow = graph({

package/dist/stream/graph.js

@@ -1,9 +1,3 @@
-/**
- * Runs a compiled graph, forwarding what its nodes emit.
- *
- * Streamed only when someone is listening: an unread stream is a queue nothing
- * drains, and `execute` is the same run without one.
- */
 export async function runGraph(flow, values, emit) {
     if (!emit)
         return flow.execute(values);

package/dist/stream/stream.js

@@ -28,23 +28,6 @@ class Events {
         }
     }
 }
-/**
- * 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 () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/harness",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Workflows: the shapes an LLM app takes, built on prompts, tools and graphs.",
   "license": "MIT",
   "repository": {
@@ -32,14 +32,14 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
     "prebuild": "npm run build --workspace @spendgraph/graph --workspace @spendgraph/tools --workspace @spendgraph/prompt",
     "test": "vitest run",
     "pretest": "npm run build --workspace @spendgraph/graph --workspace @spendgraph/prompt --workspace @spendgraph/tools --workspace @spendgraph/llms",
     "examples": "npm run build && node examples/run-all.mjs"
   },
   "devDependencies": {
-    "@spendgraph/llms": "^0.2.0",
+    "@spendgraph/llms": "^0.2.1",
     "typescript": "^5"
   },
   "engines": {
@@ -49,9 +49,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@spendgraph/graph": "^0.2.0",
-    "@spendgraph/prompt": "^0.2.0",
-    "@spendgraph/sdk": "^0.2.0",
-    "@spendgraph/tools": "^0.2.0"
+    "@spendgraph/graph": "^0.2.1",
+    "@spendgraph/prompt": "^0.2.1",
+    "@spendgraph/sdk": "^0.2.1",
+    "@spendgraph/tools": "^0.2.1"
   }
 }