@spendgraph/prompt 0.5.0 → 0.7.0

package/dist/prompt/factory.js

@@ -1,100 +1 @@
-import { serializeFields } from "@spendgraph/sdk";
-import { renderMessages } from "../render/index.js";
-import { newRolloutId } from "../run/id.js";
-import { bind } from "./bind.js";
-export const noRecorder = {
-    enabled: false,
-    write: () => { },
-};
-export const MAX_RECORDED_MESSAGES = 50;
-let warnedAboutLength = false;
-function warnIfUnrecordable(messages) {
-    if (warnedAboutLength || messages.length <= MAX_RECORDED_MESSAGES)
-        return;
-    warnedAboutLength = true;
-    console.warn(`[prompt] ${messages.length} messages is over the ${MAX_RECORDED_MESSAGES} a rollout ` +
-        "can record. The call still runs; the rollout will be rejected. Trim the history you pass.");
-}
-function lastUserMessage(messages) {
-    for (let i = messages.length - 1; i >= 0; i--) {
-        if (messages[i].role === "user")
-            return messages[i].content;
-    }
-    return "";
-}
-export function makePrompt(shape, source, recorder = noRecorder) {
-    const serialize = (values = {}) => serializeFields(values, shape.fields);
-    const format = (values = {}, opts = {}) => renderMessages(shape.blocks, shape.question, serialize(values), opts.history);
-    const built = {
-        id: shape.id,
-        name: shape.name,
-        slug: shape.slug,
-        fields: shape.fields,
-        versionId: shape.versionId,
-        models: shape.models,
-        source,
-        serialize,
-        format,
-        async call(values, run, opts = {}) {
-            const messages = format(values, { history: opts.history });
-            warnIfUnrecordable(messages);
-            const turn = opts.tools?.trace(opts.query ?? lastUserMessage(messages));
-            const rolloutId = opts.rolloutId ?? newRolloutId();
-            const recording = recorder.enabled && (opts.report ?? true);
-            const startedAt = Date.now();
-            const sent = {
-                rolloutId,
-                versionId: shape.versionId,
-                fields: serialize(values),
-                rendered: messages,
-            };
-            let outcome;
-            try {
-                outcome = await run({ messages, turn });
-            }
-            catch (err) {
-                if (recording) {
-                    const recorded = turn?.record();
-                    recorder.write(shape.id, {
-                        ...sent,
-                        model: "unknown",
-                        output: "",
-                        status: "failed",
-                        error: err instanceof Error ? err.message : String(err),
-                        latencyMs: Date.now() - startedAt,
-                        offeredTools: recorded?.offeredTools,
-                        steps: recorded?.steps,
-                    });
-                }
-                throw err;
-            }
-            const latencyMs = Date.now() - startedAt;
-            let pricing;
-            if (recording) {
-                const recorded = turn?.record();
-                const written = recorder.write(shape.id, {
-                    ...sent,
-                    model: outcome.model,
-                    output: outcome.output,
-                    status: outcome.status ?? "completed",
-                    error: outcome.error,
-                    inputTokens: outcome.inputTokens,
-                    outputTokens: outcome.outputTokens,
-                    cacheReadTokens: outcome.cacheReadTokens,
-                    cacheWriteTokens: outcome.cacheWriteTokens,
-                    citationTokens: outcome.citationTokens,
-                    reasoningTokens: outcome.reasoningTokens,
-                    latencyMs,
-                    caseId: outcome.caseId,
-                    seed: outcome.seed,
-                    offeredTools: outcome.offeredTools ?? recorded?.offeredTools,
-                    steps: outcome.steps ?? recorded?.steps,
-                });
-                pricing = written instanceof Promise ? written : undefined;
-            }
-            return { ...outcome, rolloutId, ...(pricing ? { pricing } : {}) };
-        },
-        bind: (model) => bind(built, model),
-    };
-    return built;
-}
+import{serializeFields as R}from"@spendgraph/sdk";import{findVariables as S,renderMessages as h}from"../render/index.js";import{recordable as v}from"../render/record.js";import{newRolloutId as E}from"../run/id.js";import{fingerprint as $}from"../fingerprint/index.js";import{bind as j}from"./bind.js";const x={enabled:!1,write:()=>{}},A=50;let D=!1;function z(e){D||e.length<=A||(D=!0,console.warn(`[prompt] ${e.length} messages is over the ${A} a rollout can record. The call still runs; the rollout will be rejected. Trim the history you pass.`))}function O(e,r,l){const s=Object.keys(e).filter(i=>l.has(i)&&!r.has(i));return s.length===0||console.warn(`[prompt] ${s.map(i=>`{${i}}`).join(", ")} appears in this prompt and you passed a value for it, but no field declares it, so it was not substituted and the placeholder goes to the model as written. Add it to the prompt's fields.`),s}function P(e){for(let r=e.length-1;r>=0;r--)if(e[r].role==="user")return e[r].content;return""}function L(e,r,l=x){const s=new Set(e.fields.map(t=>t.name)),i=new Set(S(e.blocks,e.question));let w=!1;const u=(t={})=>(w||(w=O(t,s,i).length>0),R(t,e.fields)),q=(t={},f={})=>h(e.blocks,e.question,u(t),f.history),b={id:e.id,name:e.name,slug:e.slug,fields:e.fields,versionId:e.versionId,fingerprint:$({name:e.name,blocks:e.blocks,question:e.question}),models:e.models,source:r,serialize:u,format:q,async call(t,f,d={}){const k=u(t),a=h(e.blocks,e.question,k,d.history);z(a);const m=d.tools?.trace(d.query??P(a)),T=d.rolloutId??E(),g=l.enabled&&(d.report??!0),y=Date.now(),I=()=>({rolloutId:T,versionId:e.versionId,fields:k,rendered:v(a)});let o;try{o=await f({messages:a,turn:m})}catch(n){if(g){const c=m?.record();l.write(e.id,{...I(),model:"unknown",output:"",status:"failed",error:n instanceof Error?n.message:String(n),latencyMs:Date.now()-y,offeredTools:c?.offeredTools,steps:c?.steps})}throw n}const M=Date.now()-y;let p;if(g){const n=m?.record(),c=l.write(e.id,{...I(),model:o.model,output:o.output,status:o.status??"completed",error:o.error,inputTokens:o.inputTokens,outputTokens:o.outputTokens,cacheReadTokens:o.cacheReadTokens,cacheWriteTokens:o.cacheWriteTokens,citationTokens:o.citationTokens,reasoningTokens:o.reasoningTokens,latencyMs:M,caseId:o.caseId,seed:o.seed,offeredTools:o.offeredTools??n?.offeredTools,steps:o.steps??n?.steps});p=c instanceof Promise?c:void 0}return{...o,rolloutId:T,...p?{pricing:p}:{}}},bind:t=>j(b,t)};return b}export{A as MAX_RECORDED_MESSAGES,L as makePrompt,x as noRecorder};

package/dist/prompt/index.js

@@ -1,2 +1 @@
-export { bind } from "./bind.js";
-export { MAX_RECORDED_MESSAGES, makePrompt, noRecorder } from "./factory.js";
+import{bind as e}from"./bind.js";import{MAX_RECORDED_MESSAGES as E,makePrompt as p,noRecorder as t}from"./factory.js";export{E as MAX_RECORDED_MESSAGES,e as bind,p as makePrompt,t as noRecorder};

package/dist/pull/index.js

@@ -1 +1 @@
-export { pullWithCache } from "./pull.js";
+import{pullWithCache as l}from"./pull.js";export{l as pullWithCache};

package/dist/pull/pull.js

@@ -1,19 +1 @@
-export async function pullWithCache(cache, key, fetchOne) {
-    const hit = cache.get(key);
-    if (hit && !hit.stale)
-        return hit.value;
-    if (hit) {
-        cache.refreshInBackground(key, fetchOne);
-        return hit.value;
-    }
-    const startedAt = cache.beginFetch();
-    try {
-        const value = await fetchOne();
-        cache.settle(key, value, startedAt);
-        return value;
-    }
-    catch (err) {
-        cache.abandon(key);
-        throw err;
-    }
-}
+async function o(t,n,e){const r=t.get(n);if(r&&!r.stale)return r.value;if(r)return t.refreshInBackground(n,e),r.value;const u=t.beginFetch();try{const a=await e();return t.settle(n,a,u),a}catch(a){throw t.abandon(n),a}}export{o as pullWithCache};

package/dist/render/index.d.ts

@@ -1,4 +1,4 @@
 export { renderMessages } from "./messages.js";
 export { compileSystemPrompt } from "./system.js";
-export type { Block, History, Message } from "./types.js";
+export type { Block, History, Message, MessageCall } from "./types.js";
 export { applyVariables, findVariables } from "./variables.js";

package/dist/render/index.js

@@ -1,3 +1 @@
-export { renderMessages } from "./messages.js";
-export { compileSystemPrompt } from "./system.js";
-export { applyVariables, findVariables } from "./variables.js";
+import{renderMessages as o}from"./messages.js";import{compileSystemPrompt as a}from"./system.js";import{applyVariables as s,findVariables as t}from"./variables.js";export{s as applyVariables,a as compileSystemPrompt,t as findVariables,o as renderMessages};

package/dist/render/messages.js

@@ -1,14 +1 @@
-import { compileSystemPrompt } from "./system.js";
-import { applyVariables } from "./variables.js";
-export function renderMessages(blocks, question, values, history = []) {
-    const system = compileSystemPrompt(blocks, values);
-    const user = applyVariables(question, values);
-    const turns = history.filter((m) => m.role !== "system");
-    return system
-        ? [
-            { role: "system", content: system },
-            ...turns,
-            { role: "user", content: user },
-        ]
-        : [...turns, { role: "user", content: user }];
-}
+import{compileSystemPrompt as l}from"./system.js";import{applyVariables as p}from"./variables.js";function y(s,n,e,m=[]){const t=l(s,e),r=p(n,e),o=m.filter(c=>c.role!=="system");return t?[{role:"system",content:t},...o,{role:"user",content:r}]:[...o,{role:"user",content:r}]}export{y as renderMessages};

package/dist/render/record.d.ts

@@ -0,0 +1,12 @@
+import type { RenderedMessage } from "@spendgraph/sdk";
+import type { Message } from "./types.js";
+/**
+ * The messages as a rollout can carry them.
+ *
+ * A `tool` turn is recorded as itself, carrying the name of whatever answered.
+ * What was called and with which arguments is still in `steps`, where it is
+ * queryable rather than embedded in a transcript — but the result the model
+ * read is part of the conversation, and rewriting it into a `user` message made
+ * the transcript claim a person said it.
+ */
+export declare function recordable(messages: Message[]): RenderedMessage[];

package/dist/render/record.js

@@ -0,0 +1 @@
+function n(t){return t.map(o=>o.role==="tool"?{role:"tool",content:o.content,name:o.name??"a tool"}:{role:o.role,content:o.content})}export{n as recordable};

package/dist/render/system.js

@@ -1,13 +1,4 @@
-import { applyVariables } from "./variables.js";
-export function compileSystemPrompt(blocks, values) {
-    const out = [];
-    for (const b of blocks ?? []) {
-        const body = b.body?.trim();
-        if (!body)
-            continue;
-        const title = b.title?.trim();
-        const text = applyVariables(body, values);
-        out.push(title ? `## ${applyVariables(title, values)}\n${text}` : text);
-    }
-    return out.join("\n\n");
-}
+import{applyVariables as e}from"./variables.js";function s(m,t){const o=[];for(const n of m??[]){const i=n.body?.trim();if(!i)continue;const r=n.title?.trim(),c=e(i,t);o.push(r?`## ${e(r,t)}
+${c}`:c)}return o.join(`
+
+`)}export{s as compileSystemPrompt};

package/dist/render/types.d.ts

@@ -3,13 +3,29 @@ export type Block = {
     title: string;
     body: string;
 };
+/** A tool call an assistant turn made, kept so its result can be paired back to it. */
+export interface MessageCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
 /**
- * One turn. `assistant` appears only in conversation history — a prompt's own
- * wording still renders a system turn and a user turn, never an answer.
+ * One turn. `assistant` and `tool` appear only in conversation history — a
+ * prompt's own wording still renders a system turn and a user turn, never an
+ * answer.
+ *
+ * Structurally the `PromptMessage` that `@spendgraph/llms` takes, so a
+ * conversation that used tools can be handed straight back as history rather
+ * than flattened into prose first. Nothing here templates it: history goes to
+ * the model as it arrived.
  */
-export type Message = {
-    role: "system" | "user" | "assistant";
+export interface Message {
+    role: "system" | "user" | "assistant" | "tool";
     content: string;
-};
+    toolCalls?: MessageCall[];
+    toolCallId?: string;
+    name?: string;
+    isError?: boolean;
+}
 /** Prior turns, oldest first, placed between the system turn and the question. */
 export type History = Message[];

package/dist/render/types.js

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

package/dist/render/variables.d.ts

@@ -3,6 +3,13 @@ import type { Block } from "./types.js";
  * Substitutes `{name}` placeholders, leaving unknown ones verbatim — emptying
  * one would send a prompt with a hole the caller cannot see.
  *
+ * `Object.hasOwn` rather than `in`, which walks the prototype chain: every
+ * object has `constructor`, `toString` and `valueOf`, so `in` counted those as
+ * supplied and a prompt reading "explain what {constructor} does" went to the
+ * model as "explain what function Object() { [native code] } does". A template
+ * about code is all it takes, and noise that looks like content is worse than
+ * the visible hole this function exists to avoid.
+ *
  * Mirrors `lib/prompt.ts` in the app. Duplicated because this package depends on
  * nothing; `rendered` on every rollout makes a divergence visible.
  */

package/dist/render/variables.js

@@ -1,20 +1 @@
-export function applyVariables(text, values) {
-    if (!text || !values)
-        return text;
-    return text.replace(/\{(\w+)\}/g, (whole, name) => name in values ? values[name] : whole);
-}
-export function findVariables(blocks, question) {
-    const seen = [];
-    const scan = (text) => {
-        for (const m of text.matchAll(/\{(\w+)\}/g)) {
-            if (!seen.includes(m[1]))
-                seen.push(m[1]);
-        }
-    };
-    for (const b of blocks ?? []) {
-        scan(b.title ?? "");
-        scan(b.body ?? "");
-    }
-    scan(question);
-    return seen;
-}
+function f(o,r){return!o||!r?o:o.replace(/\{(\w+)\}/g,(c,n)=>Object.hasOwn(r,n)?r[n]:c)}function i(o,r){const c=[],n=t=>{for(const e of t.matchAll(/\{(\w+)\}/g))c.includes(e[1])||c.push(e[1])};for(const t of o??[])n(t.title??""),n(t.body??"");return n(r),c}export{f as applyVariables,i as findVariables};

package/dist/run/across-models.d.ts

@@ -1,7 +1,17 @@
 import type { Prompts } from "@spendgraph/sdk";
 import type { Budget } from "../budget/index.js";
 import type { RunOptions, RunResult } from "../types/index.js";
-/** One rollout per model — the playground's comparison, headless. */
+/**
+ * One rollout per model — the playground's comparison, headless.
+ *
+ * Always one result per model, in the order given. A model that failed is
+ * present with `status: "failed"` rather than missing, for the same reason
+ * `sampleRuns` keeps a failed seed: this is a comparison, and throwing on the
+ * first bad model discards every model that answered — after paying for them,
+ * because the calls already in flight are not cancelled by the throw.
+ *
+ * A budget stop throws instead. Money running out says nothing about a model.
+ */
 export declare function runAcrossModels(prompts: Prompts, promptId: string, values: Record<string, unknown>, models: string[], opts?: RunOptions & {
     concurrency?: number;
 }, budget?: Budget): Promise<RunResult[]>;

package/dist/run/across-models.js

@@ -1,5 +1 @@
-import { mapLimit } from "./concurrency.js";
-import { runOnce } from "./once.js";
-export async function runAcrossModels(prompts, promptId, values, models, opts = {}, budget) {
-    return mapLimit(models, opts.concurrency ?? 4, (model) => runOnce(prompts, promptId, values, { ...opts, model, rolloutId: undefined }, budget));
-}
+import{BudgetExceededError as i}from"../budget/index.js";import{mapLimit as a}from"./concurrency.js";import{runOnce as d}from"./once.js";async function p(n,o,u,c,r={},s){return a(c,r.concurrency??4,async t=>{try{return await d(n,o,u,{...r,model:t,rolloutId:void 0},s)}catch(e){if(e instanceof i)throw e;return{id:null,model:t,status:"failed",output:"",error:e.message,costMicros:0,latencyMs:0,inputTokens:0,outputTokens:0,seed:r.seed??0}}})}export{p as runAcrossModels};

package/dist/run/concurrency.d.ts

@@ -1,7 +1 @@
-/**
- * Runs `fn` over `items`, at most `limit` in flight.
- *
- * Bounded on purpose: a whole dataset at once becomes 429s you still wait out,
- * so the unbounded version finishes later and flakier.
- */
-export declare function mapLimit<T, R>(items: T[], limit: number, fn: (item: T, index: number) => Promise<R>): Promise<R[]>;
+export { mapLimit } from "@spendgraph/sdk";

package/dist/run/concurrency.js

@@ -1,12 +1 @@
-export async function mapLimit(items, limit, fn) {
-    const out = new Array(items.length);
-    let next = 0;
-    const workers = Array.from({ length: Math.max(1, Math.min(limit, items.length)) }, async () => {
-        while (next < items.length) {
-            const i = next++;
-            out[i] = await fn(items[i], i);
-        }
-    });
-    await Promise.all(workers);
-    return out;
-}
+import{mapLimit as o}from"@spendgraph/sdk";export{o as mapLimit};

package/dist/run/id.js

@@ -1,3 +1 @@
-export function newRolloutId() {
-    return `ro_${crypto.randomUUID().replace(/-/g, "")}`;
-}
+function o(){return`ro_${crypto.randomUUID().replace(/-/g,"")}`}export{o as newRolloutId};

package/dist/run/index.js

@@ -1,5 +1 @@
-export { runAcrossModels } from "./across-models.js";
-export { mapLimit } from "./concurrency.js";
-export { newRolloutId } from "./id.js";
-export { runOnce } from "./once.js";
-export { sampleRuns } from "./sample.js";
+import{runAcrossModels as e}from"./across-models.js";import{mapLimit as p}from"./concurrency.js";import{newRolloutId as f}from"./id.js";import{runOnce as s}from"./once.js";import{sampleRuns as l}from"./sample.js";export{p as mapLimit,f as newRolloutId,e as runAcrossModels,s as runOnce,l as sampleRuns};

package/dist/run/once.js

@@ -1,21 +1 @@
-import { newRolloutId } from "./id.js";
-export async function runOnce(prompts, promptId, values, opts = {}, budget) {
-    budget?.assertAffordable();
-    const rolloutId = opts.rolloutId ?? newRolloutId();
-    const res = await prompts.run(promptId, {
-        rolloutId,
-        values,
-        model: opts.model,
-        temperature: opts.temperature,
-        maxTokens: opts.maxTokens,
-        seed: opts.seed ?? 0,
-        caseId: opts.caseId,
-        candidateId: opts.candidateId,
-        parentId: opts.parentId,
-        generation: opts.generation,
-        record: opts.record ?? true,
-    });
-    if (!res.deduped)
-        budget?.add(res.rollout.costMicros ?? 0);
-    return res.rollout;
-}
+import{newRolloutId as c}from"./id.js";async function u(a,n,o,e={},d){d?.assertAffordable();const t=e.rolloutId??c(),r=await a.run(n,{rolloutId:t,values:o,model:e.model,temperature:e.temperature,maxTokens:e.maxTokens,seed:e.seed??0,caseId:e.caseId,candidateId:e.candidateId,parentId:e.parentId,generation:e.generation,record:e.record??!0});return r.deduped||d?.add(r.rollout.costMicros??0),r.rollout}export{u as runOnce};

package/dist/run/sample.js

@@ -1,28 +1 @@
-import { BudgetExceededError } from "../budget/index.js";
-import { mapLimit } from "./concurrency.js";
-import { runOnce } from "./once.js";
-export async function sampleRuns(prompts, promptId, values, opts = {}, budget) {
-    const k = Math.max(1, opts.k ?? 5);
-    const seeds = Array.from({ length: k }, (_, i) => i);
-    return mapLimit(seeds, opts.concurrency ?? 4, async (seed) => {
-        try {
-            return await runOnce(prompts, promptId, values, { ...opts, seed, rolloutId: undefined }, budget);
-        }
-        catch (err) {
-            if (err instanceof BudgetExceededError)
-                throw err;
-            return {
-                id: null,
-                model: opts.model ?? "",
-                status: "failed",
-                output: "",
-                error: err.message,
-                costMicros: 0,
-                latencyMs: 0,
-                inputTokens: 0,
-                outputTokens: 0,
-                seed,
-            };
-        }
-    });
-}
+import{BudgetExceededError as m}from"../budget/index.js";import{mapLimit as s}from"./concurrency.js";import{runOnce as d}from"./once.js";async function y(n,o,u,t={},c){const a=Math.max(1,t.k??5),i=Array.from({length:a},(e,r)=>r);return s(i,t.concurrency??4,async e=>{try{return await d(n,o,u,{...t,seed:e,rolloutId:void 0},c)}catch(r){if(r instanceof m)throw r;return{id:null,model:t.model??"",status:"failed",output:"",error:r.message,costMicros:0,latencyMs:0,inputTokens:0,outputTokens:0,seed:e}}})}export{y as sampleRuns};

package/dist/types/dataset.js

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

package/dist/types/index.js

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

package/dist/types/payload.js

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

package/dist/types/prompt.d.ts

@@ -6,7 +6,7 @@ import type { Recordable, TraceHandle, TraceOptions, TraceOutcome } from "./trac
  * Where a prompt came from, and so what a rollout may reference.
  *
  * `server` has a row and a version behind it. `custom` was written in code and
- * has neither, which is why its `trace` records usage and not a rollout.
+ * has neither, which is why its `call` records usage and not a rollout.
  */
 export type PromptSource = "server" | "custom";
 /** A prompt: its fields, its version, and how to run it. */
@@ -18,6 +18,11 @@ export interface Prompt {
     fields: FieldSpec[];
     /** What a rollout recorded from this prompt should reference. Null when custom. */
     versionId: string | null;
+    /**
+     * A stable id for what this prompt says, the same whether it was pulled or
+     * built, so cost history follows the wording across being registered.
+     */
+    fingerprint: string;
     models: string[];
     source: PromptSource;
     /**

package/dist/types/prompt.js

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

package/dist/types/result.js

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

package/dist/types/rollout.js

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

package/dist/types/run.js

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

package/dist/types/trace.js

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

package/dist/types/version.js

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

package/docs/caching.mdx

@@ -0,0 +1,46 @@
+export const meta = {
+  title: "Caching — spendgraph docs",
+  description:
+    "`pull` serves a stale copy immediately and refreshes behind the caller. Invalidating has to drop both handles, because the same prompt sits under its uuid and its slug at once.",
+};
+
+# Caching, and invalidating it
+
+`pull` serves a stale copy immediately and refreshes behind the caller, so an edit takes effect within a TTL without any request paying for the fetch.
+
+## Invalidating drops both handles
+
+`promote` invalidates for you. Doing it by hand needs to drop **both** handles, not just the one passed: `pull` keys on whatever string it was given, so the same prompt sits under its uuid and its slug at once — and `promote` is only reachable with a uuid while the dashboard teaches pulling by slug. Dropping one left the other warm for a full TTL, still rendering the wording the promotion replaced.
+
+```ts
+await prompts.promote(promptId, versionId);  // invalidates
+prompts.invalidate(promptId);                // both handles
+prompts.invalidate();                        // everything
+```
+
+The delete runs even when nothing is stored under the handle: a cold isolate has a fetch in flight and no entry yet, and the delete is what stops that in-flight result being stored **after** the promotion.
+
+## A handle that stopped resolving
+
+A rename re-mints the slug, so a handle that 404s is routine rather than exotic. The cache backs one off after a failure rather than firing a doomed request on every pull, and keeps serving the entry it has.
+
+`onPullError` is worth setting. Without it a background refresh that has stopped resolving is silent, and a rename on the dashboard freezes a running service with nothing anywhere saying so.
+
+```ts
+new PromptClient({
+  apiKey,
+  baseUrl,
+  onPullError: (err, key) => log.warn({ key }, String(err)),
+  cache: { ttlSeconds: 300, retryAfterSeconds: 60 },
+});
+```
+
+`cache.identify` is not yours to set — the client fixes it to the prompt's id and slug, because an invalidation arriving under one handle has to reach a fetch started under the other.
+
+<Callout tone="trap" title="The dataset is not cached with the prompt">
+  Cases change independently of the wording, so they are fetched fresh. A cached prompt and a stale case list would score today's answers against yesterday's questions and report it as an improvement.
+</Callout>
+
+## A reply that is not a prompt
+
+`pull` refuses a response carrying no prompt, naming the handle and the two things worth checking — that the base URL points at a spendgraph app, and that the key can read this project. A prompt that is thin but real is still served, with the absent parts as their empty values.

package/docs/calling.mdx

@@ -0,0 +1,58 @@
+export const meta = {
+  title: "Calling a prompt — spendgraph docs",
+  description:
+    "`call` renders, runs the model call you give it, and records what happened around it. What was sent is built once and shared by the success and failure paths.",
+};
+
+# Calling a prompt
+
+`call` renders, runs the model call **you** give it, and records what happened around it. This package never sees the provider response, which is why the call is handed to it rather than made by it.
+
+```ts
+const reply = await stored.call({ audience: "students", max_words: 50 }, async ({ messages }) => {
+  const res = await anthropic.messages.create({ model, max_tokens: 400, messages });
+  return { output: res.content[0].text, model, inputTokens: 400, outputTokens: 12 };
+});
+```
+
+It fills in the version, fields, messages, latency and status; you return the text, model and tokens.
+
+**Return the tokens** or every cost on the prompt reads as zero — the first call that forgets warns once.
+
+## One record, two paths
+
+What was sent is built **once** and shared by the success path and the failure path, so the two cannot disagree about it. That is the thing hand-written reporting gets wrong.
+
+A callback that throws is recorded as failed and then rethrown: a provider call that throws is otherwise recorded nowhere at all, which leaves the run most in need of explaining with no evidence.
+
+## Recording
+
+Recording is on for every prompt and is fire-and-forget. There is no client-level switch: pass `{ report: false }` on the call that should not be recorded, which is where you know whether it should.
+
+Fire-and-forget means nothing catches a send that fails, and what is lost is spend nothing downstream can reconstruct. **`onReportError` is where that arrives** — on the client for a rollout, and on `buildCustomPrompt` for a custom prompt's usage. A client passes its own down to what it builds.
+
+## Tools
+
+`call` and `invoke` accept anything that hands out a turn — [`toolbus()`](/docs/tools/overview), or your own.
+
+```ts
+await prompt.call(values, ({ messages, turn }) => call(messages, turn), { tools: bus });
+```
+
+The callback gets the turn **fully typed**; the rollout gets the tools offered and the steps taken. Which tools were offered is recorded as well as which were called: without it a rollout cannot tell "chose not to" from "was never offered", which are opposite bugs.
+
+<Callout tone="trap" title="The recording never blocks the call, and never breaks it">
+  Reporting happens beside your call, not in front of it: a report that fails reaches `onReportError` rather than your `catch`. That is deliberate — a metering outage must not take an app down — but it does mean a missing rollout is silent unless you wired that callback.
+</Callout>
+
+## Binding a model
+
+```ts
+const chain = prompt.bind(model);
+
+await chain.invoke(values);
+await chain.stream(values, { onText: (delta) => res.write(delta) });
+await chain.batch(cases, { concurrency: 4 });
+```
+
+`stream` falls back to `call` for a model that cannot stream, so binding one does not require it.

package/docs/datasets.mdx

@@ -0,0 +1,61 @@
+export const meta = {
+  title: "Versions and datasets — spendgraph docs",
+  description:
+    "Cases sit on one side of a wall the server decides, so a case never moves sides. setCases replaces the whole set, because a dataset has one answer at a time.",
+};
+
+# Versions and datasets
+
+```ts
+await prompts.versions(promptId, { origin: "user", limit: 20 });
+await prompts.cases(promptId);
+await prompts.setCases(promptId, cases);
+```
+
+## A case sits on one side of a wall
+
+Every case is either `feedback` or `held_out`, and **the server decides which** — it is not a field you set.
+
+```
+  feedback   ──▶  what an optimiser is allowed to read and learn from
+  held_out   ──▶  what it never sees, so a score means something
+```
+
+That is the whole point of the split, and the reason the client cannot set it. A case that could move sides is a case that can be quietly moved to the side where the prompt already does well, and every number downstream stops meaning anything. `DatasetCase.split` exists on the type so a read can report it; omit it on a write.
+
+```ts
+const summary = await prompts.cases(promptId);
+
+summary.counts;    // { total, feedback, held_out }
+summary.problem;   // why this cannot be optimised against yet, or null
+```
+
+`problem` is the useful one. A dataset too small, too lopsided, or missing expected outputs cannot support a comparison, and the server says which rather than returning a confident score built on four cases.
+
+## `setCases` replaces everything
+
+Not a merge, and deliberately.
+
+A dataset is a **set** — "which cases am I evaluating against" has one answer at a time. A merge would leave no way to remove a case, and a stale case nobody can delete quietly biases every run after it.
+
+```ts
+await prompts.setCases(promptId, [
+  { caseId: "refund-partial", fieldValues: { audience: "students" }, expected: "…" },
+]);
+```
+
+Send the set you want to have. Read it back with `cases()` if you need to confirm what landed.
+
+<Callout tone="trap" title="A case id is not a label — it decides which side of the wall the case lands on">
+  The split is derived from the id, so renaming a case re-rolls it: a case that was held out can come back as feedback, and whatever proposes changes may now read what it is scored against. Nothing in the data would say so. Change the text, keep the id.
+</Callout>
+
+## Versions
+
+```ts
+await prompts.versions(promptId, { origin: "user", limit: 20 });
+```
+
+`origin` separates a version somebody wrote from one a run produced, which matters once an optimiser is writing candidates — otherwise the history reads as though a person made forty edits in a minute.
+
+Promoting a version is on [Caching](/docs/prompt/caching), because the part worth knowing is what it invalidates.