@spendgraph/prompt 0.5.0 → 0.7.0

package/docs/fields.mdx

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

@@ -0,0 +1,78 @@
+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
+
+`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](/docs/prompt/fields) | placeholders, types, and what is substituted |
+| [Calling a prompt](/docs/prompt/calling) | `call`, history, tools, and what gets recorded |
+| [Caching](/docs/prompt/caching) | serving stale, refreshing behind, invalidating both handles |
+| [Running server-side](/docs/prompt/running) | `run`, `sample`, `runAll`, and the spend ceiling |
+| [Versions and datasets](/docs/prompt/datasets) | the split the server decides, and why it does |

package/docs/running.mdx

@@ -0,0 +1,55 @@
+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](/docs/prompt/datasets).

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@spendgraph/prompt",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Pull a stored prompt or build one in code, render it, and record what it cost.",
-  "license": "MIT",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/fnLog0/spendgraph.git",
@@ -27,6 +27,7 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./docs/*": "./docs/*",
     "./render": {
       "types": "./dist/render/index.d.ts",
       "import": "./dist/render/index.js"
@@ -39,19 +40,15 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments",
-    "test": "npm run build && vitest run",
-    "pretest": "npm run build --workspace @spendgraph/tools"
-  },
   "dependencies": {
-    "@spendgraph/sdk": "^0.5.0"
+    "@spendgraph/sdk": "^0.7.0"
   },
   "devDependencies": {
-    "@spendgraph/llms": "^0.5.0",
-    "@spendgraph/tools": "^0.5.0",
+    "@spendgraph/llms": "^0.7.0",
+    "@spendgraph/tools": "^0.7.0",
     "typescript": "^5"
   },
   "engines": {
@@ -59,5 +56,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json --emitDeclarationOnly && tsc -p tsconfig.json --declaration false --removeComments && node ../../scripts/minify.mjs dist",
+    "test": "vitest run"
   }
-}
+}