@spendgraph/prompt 0.2.0

package/dist/types/payload.d.ts

@@ -0,0 +1,16 @@
+import type { FieldSpec } from "@spendgraph/sdk";
+import type { Block } from "../render/index.js";
+/** What `GET /api/v1/prompts/:id` returns, narrowed to what this package uses. */
+export interface PromptPayload {
+    id: string;
+    name: string;
+    /** The other handle `pull` accepts. Null on a row the backfill could not slug. */
+    slug?: string | null;
+    blocks: Block[];
+    question: string;
+    models: string[];
+    temperature: number;
+    maxTokens: number;
+    fieldSpec: FieldSpec[];
+    currentVersionId: string | null;
+}

package/dist/types/payload.js

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

package/dist/types/prompt.d.ts

@@ -0,0 +1,73 @@
+import type { FieldSpec } from "@spendgraph/sdk";
+import type { Chain, Model } from "../prompt/bind.js";
+import type { History, Message } from "../render/index.js";
+import type { Recordable, TraceHandle, TraceOptions, TraceOutcome } from "./trace.js";
+/**
+ * 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.
+ */
+export type PromptSource = "server" | "custom";
+/** A prompt: its fields, its version, and how to run it. */
+export interface Prompt {
+    id: string;
+    name: string;
+    /** What `pullPrompt` accepts besides the id. Null when there is none. */
+    slug: string | null;
+    fields: FieldSpec[];
+    /** What a rollout recorded from this prompt should reference. Null when custom. */
+    versionId: string | null;
+    models: string[];
+    source: PromptSource;
+    /**
+     * Validates and substitutes, throwing on a missing required field.
+     *
+     * `history` is placed between the system turn and the question, verbatim.
+     */
+    format(values?: Record<string, unknown>, opts?: RenderOptions): Message[];
+    /** The serialised field map that `render` used — recorded on the rollout. */
+    serialize(values?: Record<string, unknown>): Record<string, string>;
+    /**
+     * Renders, runs your model call, and records what it cost around it.
+     *
+     * This package never sees the provider call, so handing it the call is what
+     * gives it a completion signal. It fills in the version, fields, messages,
+     * latency and status; you return the text, model and tokens.
+     *
+     * A `server` prompt records a rollout. A `custom` one has no row to hang a
+     * rollout on, so it records usage instead — the spend still lands, the
+     * wording is simply not versioned. A callback that throws is recorded as
+     * failed, then rethrown.
+     */
+    call<T extends Recordable = Recordable>(values: Record<string, unknown>, run: (handle: TraceHandle<T>) => Promise<TraceOutcome> | TraceOutcome, opts?: TraceOptions<T>): Promise<TraceOutcome & {
+        rolloutId: string;
+        pricing?: Promise<number | undefined>;
+    }>;
+    /**
+     * Attaches a model, so the prompt can run itself.
+     *
+     * `chain.invoke(values)` is then the whole call — rendered, run and recorded.
+     */
+    bind(model: Model): Chain;
+}
+export interface RenderOptions {
+    /** Prior turns, oldest first. A `system` turn here is dropped — the prompt owns that. */
+    history?: History;
+}
+/** What `buildCustomPrompt` takes. Everything but `name` has a sane default. */
+export interface PromptSpec {
+    name: string;
+    /** Titled sections, rendered into the system turn in order. */
+    blocks?: {
+        title: string;
+        body: string;
+    }[];
+    /** The user turn. */
+    question?: string;
+    /** Declared placeholders. Undeclared `{names}` are left alone. */
+    fields?: FieldSpec[];
+    models?: string[];
+    /** Substituted into blocks and question before field validation. */
+    variables?: Record<string, string>;
+}

package/dist/types/prompt.js

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

package/dist/types/result.d.ts

@@ -0,0 +1,13 @@
+/** A rollout as the run route returns it. `id` is null for a dry run. */
+export interface RunResult {
+    id: string | null;
+    model: string;
+    status: "completed" | "failed";
+    output: string;
+    error?: string | null;
+    costMicros: number;
+    latencyMs: number;
+    inputTokens: number;
+    outputTokens: number;
+    seed?: number;
+}

package/dist/types/result.js

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

package/dist/types/rollout.d.ts

@@ -0,0 +1,8 @@
+import type { RolloutInput, RolloutRecord } from "@spendgraph/sdk";
+/**
+ * Prompt-shaped names for the shared rollout types.
+ *
+ * The shapes live in core because a graph run is a rollout too.
+ */
+export type ReportInput = RolloutInput;
+export type Rollout = RolloutRecord;

package/dist/types/rollout.js

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

package/dist/types/run.d.ts

@@ -0,0 +1,18 @@
+/** Run configuration. Field values are the second argument, not part of this. */
+export interface RunOptions {
+    /** Overrides the prompt's first saved model. Never silently defaulted. */
+    model?: string;
+    temperature?: number;
+    maxTokens?: number;
+    /** Which repetition this is. Metadata for pass^k, not a provider parameter. */
+    seed?: number;
+    /** Links the run to a dataset case; the server resolves the split from it. */
+    caseId?: string;
+    candidateId?: string;
+    parentId?: string;
+    generation?: number;
+    /** Supply to make your own retry idempotent. Generated when omitted. */
+    rolloutId?: string;
+    /** false runs the model but writes nothing — for debugging, not datasets. */
+    record?: boolean;
+}

package/dist/types/run.js

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

package/dist/types/trace.d.ts

@@ -0,0 +1,71 @@
+import type { RolloutStep } from "@spendgraph/sdk";
+import type { History, Message } from "../render/index.js";
+/** What a turn contributes to the rollout once the call is done. */
+export interface TurnRecord {
+    offeredTools: string[];
+    steps: RolloutStep[];
+}
+/**
+ * Structurally what `@spendgraph/tools`'s `ToolTrace` is, narrowed to the one
+ * method a rollout needs.
+ *
+ * Declared here rather than imported so this package depends on nothing but the
+ * SDK. A real `ToolTrace` satisfies it, and the generic below hands the callback
+ * back the full thing rather than this narrowing.
+ */
+export interface Recordable {
+    record(): TurnRecord;
+}
+/** Anything that can hand out a turn — a `toolbus()`, or a test double. */
+export interface TurnSource<T extends Recordable = Recordable> {
+    trace(query?: string, limit?: number): T;
+}
+/** What the callback is handed. */
+export interface TraceHandle<T extends Recordable = Recordable> {
+    messages: Message[];
+    /** Present only when `tools` was given. Already selected for this call. */
+    turn?: T;
+}
+/** What the callback returns — only what this package cannot see for itself. */
+export interface TraceOutcome {
+    output: string;
+    model: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    /** Billed on their own by search-grounded providers. */
+    citationTokens?: number;
+    reasoningTokens?: number;
+    /**
+     * What the call cost, in micro-USD, once the server has priced it.
+     *
+     * Set by a caller that already knows it. `call` does not fill this in — the
+     * price is computed server-side and does not exist until the rollout has been
+     * written, so `call` hands back `pricing`, a promise, and never stalls the
+     * call waiting for it. Never guessed here: a number this package made up
+     * would be indistinguishable from one the pricing table produced.
+     */
+    costMicros?: number;
+    /** Defaults to "completed". A run that answered badly is not a failure. */
+    status?: "completed" | "failed";
+    error?: string;
+    /** Overrides the turn's steps. A `GraphResult` already carries them. */
+    steps?: RolloutStep[];
+    offeredTools?: string[];
+    /** Set only for evaluation rollouts. Production traffic leaves it unset. */
+    caseId?: string;
+    seed?: number;
+}
+export interface TraceOptions<T extends Recordable = Recordable> {
+    /** Prior turns, oldest first. Rendered between the system turn and the question. */
+    history?: History;
+    /** A bus to select from. The callback gets the turn; the rollout gets both. */
+    tools?: TurnSource<T>;
+    /** What to select tools on. Defaults to the rendered user message. */
+    query?: string;
+    /** False records nothing. The callback still runs and still returns. */
+    report?: boolean;
+    /** Supply your own to make a retry safe. Generated otherwise. */
+    rolloutId?: string;
+}

package/dist/types/trace.js

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

package/dist/types/version.d.ts

@@ -0,0 +1,21 @@
+import type { FieldSpec } from "@spendgraph/sdk";
+import type { Block } from "../render/index.js";
+/** One wording a prompt has had. */
+export interface PromptVersion {
+    id: string;
+    promptId: string;
+    hash: string;
+    blocks: Block[];
+    question: string;
+    fieldSpec: FieldSpec[] | null;
+    /** "user" is a wording a person wrote; "assay" is one the optimizer proposed. */
+    origin: "user" | "assay";
+    candidateId: string | null;
+    parentVersionId: string | null;
+    /** Last time this wording was put live; null means it never has been. */
+    servedAt?: string | null;
+    /** How many stints it has had live. */
+    servedCount?: number;
+    createdAt: string;
+    isCurrent: boolean;
+}

package/dist/types/version.js

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

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@spendgraph/prompt",
+  "version": "0.2.0",
+  "description": "Pull a stored prompt or build one in code, render it, and record what it cost.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnLog0/spendgraph.git",
+    "directory": "packages/prompt"
+  },
+  "homepage": "https://github.com/fnLog0/spendgraph#readme",
+  "bugs": {
+    "url": "https://github.com/fnLog0/spendgraph/issues"
+  },
+  "keywords": [
+    "llm",
+    "prompt",
+    "versioning",
+    "evaluation",
+    "observability"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./render": {
+      "types": "./dist/render/index.d.ts",
+      "import": "./dist/render/index.js"
+    },
+    "./package.json": "./package.json",
+    "./internals": {
+      "types": "./dist/internals.d.ts",
+      "import": "./dist/internals.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && vitest run",
+    "pretest": "npm run build --workspace @spendgraph/tools"
+  },
+  "dependencies": {
+    "@spendgraph/sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "@spendgraph/llms": "^0.2.0",
+    "@spendgraph/tools": "^0.2.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}