@spendgraph/prompt 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spendgraph/prompt",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "Pull a stored prompt or build one in code, render it, and record what it cost.",
   "license": "Apache-2.0",
   "repository": {
@@ -27,7 +27,6 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
-    "./docs/*": "./docs/*",
     "./render": {
       "types": "./dist/render/index.d.ts",
       "import": "./dist/render/index.js"
@@ -40,16 +39,15 @@
   },
   "files": [
     "dist",
-    "docs",
     "README.md"
   ],
   "dependencies": {
-    "@spendgraph/sdk": "^0.8.1"
+    "@spendgraph/sdk": "^0.8.2"
   },
   "devDependencies": {
-    "@spendgraph/config": "0.8.1",
-    "@spendgraph/llms": "^0.8.1",
-    "@spendgraph/tools": "^0.8.1",
+    "@spendgraph/config": "0.8.2",
+    "@spendgraph/llms": "^0.8.2",
+    "@spendgraph/tools": "^0.8.2",
     "typescript": "^5"
   },
   "engines": {

package/docs/caching.mdx

@@ -1,46 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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()`](/spendgraph/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

@@ -1,61 +0,0 @@
-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](/spendgraph/prompt/caching), because the part worth knowing is what it invalidates.

package/docs/fields.mdx

@@ -1,63 +0,0 @@
-export const meta = {
-  title: "Fields: spendgraph docs",
-  description:
-    "A placeholder is declared as a FieldSpec. A missing required field throws before anything is sent, and a value with nowhere to land is said rather than dropped.",
-};
-
-# Fields
-
-A `{placeholder}` is declared as a `FieldSpec`, a name, a type, whether it is required, and how it renders. A missing required field throws **before anything is sent**.
-
-What it throws is `FieldValidationError`, re-exported from the SDK so a caller has one name to catch whether the failure came from a prompt, a tool argument or a graph input:
-
-```ts
-import { FieldValidationError } from "@spendgraph/prompt";
-
-try {
-  prompt.format(values);
-} catch (err) {
-  if (err instanceof FieldValidationError) err.errors;   // which fields, and why
-}
-```
-
-```ts
-prompt.format(values);     // Message[], validated and substituted
-prompt.serialize(values);  // the field map that format used
-```
-
-Types come from `@spendgraph/sdk`, because a tool's arguments and a graph node's inputs are the same problem.
-
-## Only declared fields are substituted
-
-A `{placeholder}` nobody supplied is **left as it is**. Emptying it would send a prompt with a hole the caller cannot see, and noise that reads as content is worse than a visible gap.
-
-A value you *did* pass with no field to land in is a different thing. The first time that happens, the prompt says so:
-
-```
-[prompt] {audience} 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.
-```
-
-All three conditions have to hold: the value was supplied, the placeholder is in the wording, and no field declares it, so an unrelated value and an unsupplied placeholder both stay quiet.
-
-## Substitution reads own properties only
-
-`{constructor}`, `{toString}` and `{valueOf}` are not supplied just because every object has them. A template about code is all it takes to send `explain what function Object() { [native code] } does` to a model, and that is noise dressed as content.
-
-<Callout tone="trap" title="A value that looks like a placeholder stays text">
-  Substitution runs once and does not re-read what it wrote, so a field whose value is `{other}` reaches the model as those eight characters. The alternative is a value from a user deciding which of your other fields to expand.
-</Callout>
-
-## Conversation history
-
-Prior turns render between the system turn and the question, oldest first.
-
-```ts
-prompt.format(values, { history });
-await prompt.call(values, ({ messages }) => call(messages), { history });
-```
-
-History is passed through **verbatim**: it is a record of what was already said, not a template, so `{placeholders}` inside it are left alone. A `system` turn in the history is dropped: the prompt owns that turn, and two of them is a different request from the one the prompt describes.
-
-A rollout records at most 50 messages, which is what the route accepts. A longer conversation still runs; only its rollout is refused, and that refusal reaches `onReportError` rather than your call, so the first time it happens the package warns, once, while somebody is still watching. `MAX_RECORDED_MESSAGES` is exported if you want to trim before it bites.

package/docs/overview.mdx

@@ -1,80 +0,0 @@
-export const meta = {
-  title: "Prompts: spendgraph docs",
-  description:
-    "Pull a stored prompt or write one in code, render it, and record what it cost. Both hand back the same object, so nothing downstream has to know which it was given.",
-};
-
-# Prompts
-
-The wording that produced last week's answer is not the wording in the file today, and a prompt edited since is a score nobody can reproduce.
-
-Pull a prompt from the dashboard or write one in code, render it, and record what the call cost, with the exact messages that were sent kept beside the reply.
-
-```sh
-npm install @spendgraph/prompt
-```
-
-## Two ways in, one prompt
-
-<PromptSources />
-
-`pullPrompt` fetches the wording from the server. `buildCustomPrompt` declares it in code. Both hand back the same `Prompt`, so `format`, `serialize` and `call` behave identically and nothing downstream has to know which it was given.
-
-```ts
-import { PromptClient, buildCustomPrompt } from "@spendgraph/prompt";
-
-const prompts = new PromptClient({
-  apiKey: process.env.SPENDGRAPH_API_KEY,
-  baseUrl: "https://spendgraph.locusgraph.com",
-});
-
-const stored = await prompts.pull("billing-explainer");
-
-const local = buildCustomPrompt({
-  name: "billing-explainer",
-  blocks: [{ title: "Role", body: "You explain invoices to {audience}." }],
-  question: "Explain this line item in {max_words} words.",
-  fields: [
-    { name: "audience", type: "string", required: true },
-    { name: "max_words", type: "number", required: true },
-  ],
-});
-```
-
-`pull` takes an id or a slug, the server resolves either. `pullPrompt` is the same fetch as a standalone function, for a caller that wants one prompt and no client to hold.
-
-## Running one
-
-Bind a model and the prompt runs itself:
-
-```ts
-import { Llm } from "@spendgraph/llms";
-
-const chain = stored.bind(new Llm({ client: anthropic, model: "claude-opus-5" }));
-
-const answer = await chain.invoke({ audience: "students", max_words: 50 });
-answer.output;
-answer.rolloutId;
-```
-
-`bind` asks for a **shape, not an import**: anything with `call(messages)` returning an outcome satisfies `Model`, and an `LlmReply` already is one. Neither package depends on the other.
-
-## What each kind records
-
-A **server** prompt has a row and a version behind it, so a call writes a rollout. A **custom** prompt has neither, so it records usage instead: the tokens still land on the dashboard, attributed to the model and tagged with the prompt's name; only the wording goes unversioned.
-
-Read `prompt.source` to tell them apart.
-
-<Callout tone="trap" title="A custom prompt has no version, so its spend is usage rather than a rollout">
-  `buildCustomPrompt` records the call and the cost exactly as a stored one does, but there is no row and no version, so nothing ties the number to a wording you can go back to. Fine while you are exploring; not what you want under a score you intend to compare next month.
-</Callout>
-
-## Where to go next
-
-| | |
-| --- | --- |
-| [Fields](/spendgraph/prompt/fields) | placeholders, types, and what is substituted |
-| [Calling a prompt](/spendgraph/prompt/calling) | `call`, history, tools, and what gets recorded |
-| [Caching](/spendgraph/prompt/caching) | serving stale, refreshing behind, invalidating both handles |
-| [Running server-side](/spendgraph/prompt/running) | `run`, `sample`, `runAll`, and the spend ceiling |
-| [Versions and datasets](/spendgraph/prompt/datasets) | the split the server decides, and why it does |

package/docs/running.mdx

@@ -1,55 +0,0 @@
-export const meta = {
-  title: "Running server-side: spendgraph docs",
-  description:
-    "run, sample and runAll execute the prompt where the spec, rendering and pricing already live. The batch path, and the ceiling that stops it running away.",
-};
-
-# Running server-side
-
-`run`, `sample` and `runAll` execute the prompt **on the server**, where the spec, rendering and pricing already live.
-
-This is the batch path. A production request should pull, render and report instead: the server-side call adds a hop and makes spendgraph a dependency of your uptime, which is the right trade for evaluation and the wrong one for a user waiting on a response.
-
-```ts
-await prompts.run(promptId, values);
-await prompts.sample(promptId, values, { k: 5 });
-await prompts.runAll(promptId, values);      // one rollout per saved model
-```
-
-## Every seed, and every model, comes back
-
-`sample` always returns **k results**. A failed seed is present with `status: "failed"` rather than missing, three results for k = 5 would let a metric compute over three and report better consistency than the run showed.
-
-`runAll` does the same across models. One slug with a typo used to take the whole comparison with it, and not stop the calls already queued, which still left, landed and were billed after the caller had been told the run failed. Now each model comes back in the order asked, a failed one carrying its own name and the provider's message.
-
-A **budget stop** is the exception: it throws `BudgetExceededError`, carrying what was spent and what the ceiling was. Money running out says nothing about a prompt or a model, and recording those as failures would put the wallet into `pass^k`.
-
-```ts
-import { BudgetExceededError } from "@spendgraph/prompt";
-
-catch (err) {
-  if (err instanceof BudgetExceededError) {
-    err.spentMicros;   // integer micro-USD, as everywhere else
-    err.limitMicros;
-  }
-}
-```
-
-## The spend ceiling
-
-`maxCostMicros` caps what those spend. Omit it and the client warns once that it is unbounded; pass `null` to say you meant it.
-
-```ts
-new PromptClient({ apiKey, baseUrl, maxCostMicros: 5_000_000 });  // $5
-new PromptClient({ apiKey, baseUrl, maxCostMicros: null });       // deliberately none
-```
-
-`0` is kept, because spending nothing is a thing a caller can mean. A ceiling that is `NaN` or negative is **refused**: `NaN >= NaN` is false, so a `NaN` limit never fires and the guard is silently not there, and `Number(process.env.MAX_COST_MICROS)` on an unset variable is `NaN`, which is how it arrives without anyone typing it.
-
-<Callout tone="trap" title="Omit `maxCostMicros` and the client warns once, then spends without a ceiling">
-  `runAll` fans out across every saved model and `sample` multiplies that by k, so the bill is a product of two numbers neither of which is in front of you. Pass a ceiling, or pass `null` to say you meant it, the warning appears once per process and is easy to scroll past.
-</Callout>
-
-## What you run against
-
-Cases and versions have their own page: [Versions and datasets](/spendgraph/prompt/datasets).