@spendgraph/prompt 0.5.0 → 0.7.0

package/dist/cache/cache.js

@@ -1,128 +1 @@
-export class PullCache {
-    store = new Map();
-    ttlMs;
-    maxSize;
-    now;
-    refreshing = new Set();
-    failures = new Map();
-    retryAfterMs;
-    onRefreshError;
-    identify;
-    tick = 0;
-    invalidatedAt = new Map();
-    clearedAt = -1;
-    outstanding = 0;
-    constructor(opts = {}) {
-        this.ttlMs = (opts.ttlSeconds ?? 300) * 1000;
-        this.maxSize = Math.max(1, opts.maxSize ?? 100);
-        this.now = opts.now ?? (() => Date.now());
-        this.retryAfterMs = (opts.retryAfterSeconds ?? 60) * 1000;
-        this.onRefreshError = opts.onRefreshError;
-        this.identify = opts.identify;
-    }
-    get(key) {
-        const entry = this.store.get(key);
-        if (!entry)
-            return undefined;
-        this.store.delete(key);
-        this.store.set(key, entry);
-        const ageMs = this.now() - entry.at;
-        return { value: entry.value, stale: ageMs > this.ttlMs, ageMs };
-    }
-    set(key, value) {
-        this.store.delete(key);
-        this.store.set(key, { value, at: this.now() });
-        while (this.store.size > this.maxSize) {
-            const oldest = this.store.keys().next().value;
-            if (oldest === undefined)
-                break;
-            this.store.delete(oldest);
-            if (!this.refreshing.has(oldest))
-                this.failures.delete(oldest);
-        }
-    }
-    refreshInBackground(key, refresh) {
-        if (this.refreshing.has(key))
-            return;
-        const failedAt = this.failures.get(key);
-        if (failedAt !== undefined && this.now() - failedAt < this.retryAfterMs)
-            return;
-        this.refreshing.add(key);
-        const startedAt = this.beginFetch();
-        void refresh()
-            .then((value) => this.settle(key, value, startedAt))
-            .catch((err) => {
-            this.abandon(key);
-            try {
-                this.onRefreshError?.(err, key);
-            }
-            catch {
-            }
-        })
-            .finally(() => {
-            this.refreshing.delete(key);
-            this.forgetLogIfIdle();
-        });
-    }
-    beginFetch() {
-        this.outstanding++;
-        return this.tick;
-    }
-    settle(key, value, startedAt) {
-        this.outstanding--;
-        const names = [key, ...(this.identify?.(value) ?? [])];
-        const overtaken = startedAt < this.clearedAt ||
-            names.some((n) => (this.invalidatedAt.get(n) ?? -1) > startedAt);
-        if (!overtaken) {
-            this.failures.delete(key);
-            this.set(key, value);
-        }
-        this.forgetLogIfIdle();
-    }
-    abandon(key) {
-        this.outstanding--;
-        this.failures.set(key, this.now());
-        this.boundFailures();
-        this.forgetLogIfIdle();
-    }
-    invalidate(name) {
-        this.invalidatedAt.set(name, ++this.tick);
-    }
-    forgetLogIfIdle() {
-        if (this.outstanding === 0 && this.refreshing.size === 0)
-            this.invalidatedAt.clear();
-    }
-    boundFailures() {
-        while (this.failures.size > this.maxSize) {
-            const oldest = this.failures.keys().next().value;
-            if (oldest === undefined)
-                break;
-            this.failures.delete(oldest);
-        }
-    }
-    keysWhere(match) {
-        const out = [];
-        for (const [key, entry] of this.store)
-            if (match(entry.value))
-                out.push(key);
-        return out;
-    }
-    delete(key) {
-        this.store.delete(key);
-        this.failures.delete(key);
-        this.invalidate(key);
-        this.forgetLogIfIdle();
-    }
-    clear() {
-        this.clearedAt = ++this.tick;
-        this.store.clear();
-        this.failures.clear();
-        this.forgetLogIfIdle();
-    }
-    get size() {
-        return this.store.size;
-    }
-    get trackedKeys() {
-        return new Set([...this.invalidatedAt.keys(), ...this.failures.keys()]).size;
-    }
-}
+function a(r,e=0,s=Math.random){if(r<=0||e<=0)return r;const t=Math.min(.99,e);return Math.round(r*(1+(s()*2-1)*t))}class o{store=new Map;ttlMs;maxSize;now;refreshing=new Set;failures=new Map;retryAfterMs;onRefreshError;identify;tick=0;invalidatedAt=new Map;clearedAt=-1;outstanding=0;constructor(e={}){this.ttlMs=a((e.ttlSeconds??300)*1e3,e.jitter,e.random),this.maxSize=Math.max(1,e.maxSize??100),this.now=e.now??(()=>Date.now()),this.retryAfterMs=(e.retryAfterSeconds??60)*1e3,this.onRefreshError=e.onRefreshError,this.identify=e.identify}get(e){const s=this.store.get(e);if(!s)return;this.store.delete(e),this.store.set(e,s);const t=this.now()-s.at;return{value:s.value,stale:t>this.ttlMs,ageMs:t}}set(e,s){for(this.store.delete(e),this.store.set(e,{value:s,at:this.now()});this.store.size>this.maxSize;){const t=this.store.keys().next().value;if(t===void 0)break;this.store.delete(t),this.refreshing.has(t)||this.failures.delete(t)}}refreshInBackground(e,s){if(this.refreshing.has(e))return;const t=this.failures.get(e);if(t!==void 0&&this.now()-t<this.retryAfterMs)return;this.refreshing.add(e);const i=this.beginFetch();s().then(n=>this.settle(e,n,i)).catch(n=>{this.abandon(e);try{this.onRefreshError?.(n,e)}catch{}}).finally(()=>{this.refreshing.delete(e),this.forgetLogIfIdle()})}beginFetch(){return this.outstanding++,this.tick}settle(e,s,t){this.outstanding--;const i=[e,...this.identify?.(s)??[]];t<this.clearedAt||i.some(h=>(this.invalidatedAt.get(h)??-1)>t)||(this.failures.delete(e),this.set(e,s)),this.forgetLogIfIdle()}abandon(e){this.outstanding--,this.failures.set(e,this.now()),this.boundFailures(),this.forgetLogIfIdle()}invalidate(e){this.invalidatedAt.set(e,++this.tick)}forgetLogIfIdle(){this.outstanding===0&&this.refreshing.size===0&&this.invalidatedAt.clear()}boundFailures(){for(;this.failures.size>this.maxSize;){const e=this.failures.keys().next().value;if(e===void 0)break;this.failures.delete(e)}}keysWhere(e){const s=[];for(const[t,i]of this.store)e(i.value)&&s.push(t);return s}delete(e){this.store.delete(e),this.failures.delete(e),this.invalidate(e),this.forgetLogIfIdle()}clear(){this.clearedAt=++this.tick,this.store.clear(),this.failures.clear(),this.forgetLogIfIdle()}get size(){return this.store.size}get trackedKeys(){return new Set([...this.invalidatedAt.keys(),...this.failures.keys()]).size}}export{o as PullCache};

package/dist/cache/index.js

@@ -1 +1 @@
-export { PullCache } from "./cache.js";
+import{PullCache as o}from"./cache.js";export{o as PullCache};

package/dist/client.d.ts

@@ -6,7 +6,13 @@ export interface PromptClientOptions extends Omit<ClientOptions, "apiKey" | "bas
     /** spendgraph API key (sg_…). Without it, `pull` throws and `report` no-ops. */
     apiKey: string | undefined;
     baseUrl: string;
-    cache?: CacheOptions<PromptPayload>;
+    /**
+     * `identify` is not yours to set: the client fixes it to the prompt's id and
+     * slug, because an invalidation that arrives under one handle has to reach a
+     * fetch started under the other. Naming it in the type and discarding it in
+     * the constructor was worse than not offering it.
+     */
+    cache?: Omit<CacheOptions<PromptPayload>, "identify">;
     /** Max requests in flight for sample() and runAll(). Default 4. */
     concurrency?: number;
     /**
@@ -44,6 +50,19 @@ export declare class PromptClient {
      * you passed, so pulling the same prompt both ways keeps two entries.
      */
     pull(handle: string): Promise<Prompt>;
+    /**
+     * Registers a prompt written in code, and hands back the stored one.
+     *
+     * The wording goes up as it stands, so what runs afterwards is the text that
+     * ran before. What comes back is a server prompt: it has an id, a version,
+     * and its calls write rollouts where the built one wrote usage.
+     *
+     * `fields` are not sent. The app derives them from the `{placeholders}` in
+     * the blocks and the question, so a spec whose fields say more than its
+     * placeholders do — a default, a range, an enum — loses that here and is
+     * worth setting on the prompt afterwards.
+     */
+    create(spec: PromptSpec, projectId: string): Promise<Prompt>;
     /** A prompt written in code, wired to record its usage through this client. */
     build(spec: PromptSpec, opts?: Omit<BuildOptions, "sdk">): Prompt;
     /**
@@ -101,6 +120,13 @@ export declare class PromptClient {
      * Invalidates the cache: a promotion that left a warm entry in place would
      * keep sending the old wording for up to a TTL, which is the one moment a
      * caller is actively watching for the change.
+     *
+     * **This client's cache.** Every other process holding the same prompt keeps
+     * serving what it already pulled until its own TTL lapses, which for an edit
+     * is what "within a TTL" means and for a rollback is up to five minutes of
+     * continued harm — a version is usually rolled back because it is doing some.
+     * A fleet that needs the change at once has each instance call `invalidate`
+     * when it hears about the promotion, or pull with `cache: { ttlSeconds: 0 }`.
      */
     promote(promptId: string, versionId: string): Promise<{
         promoted: string;

package/dist/client.js

@@ -1,145 +1 @@
-import { Spendgraph } from "@spendgraph/sdk";
-import { Budget } from "./budget/index.js";
-import { buildCustomPrompt } from "./build/index.js";
-import { PullCache } from "./cache/index.js";
-import { makePrompt } from "./prompt/index.js";
-import { pullWithCache } from "./pull/index.js";
-import { newRolloutId } from "./run/id.js";
-import { runAcrossModels, runOnce, sampleRuns } from "./run/index.js";
-const DEFAULT_CONCURRENCY = 4;
-export class PromptClient {
-    sdk;
-    cache;
-    hasKey;
-    onReportError;
-    concurrency;
-    budget;
-    warnedAboutTokens = false;
-    constructor(opts) {
-        const { cache, onReportError, onPullError, concurrency, maxCostMicros, ...clientOpts } = opts;
-        this.sdk = new Spendgraph(clientOpts);
-        this.cache = new PullCache({
-            ...cache,
-            onRefreshError: cache?.onRefreshError ?? onPullError,
-            identify: (p) => [p.id, p.slug].filter((v) => Boolean(v)),
-        });
-        this.hasKey = Boolean(opts.apiKey);
-        this.onReportError = onReportError;
-        this.concurrency = Math.max(1, concurrency ?? DEFAULT_CONCURRENCY);
-        this.budget = new Budget("maxCostMicros" in opts ? maxCostMicros : undefined);
-    }
-    recorder() {
-        return {
-            enabled: true,
-            write: (promptId, entry) => {
-                this.warnOnEmptyTokens(entry);
-                return this.priced(promptId, entry);
-            },
-        };
-    }
-    async pull(handle) {
-        const payload = await pullWithCache(this.cache, handle, async () => {
-            const res = await this.sdk.prompts.get(handle);
-            return res.prompt;
-        });
-        return makePrompt({
-            id: payload.id,
-            name: payload.name,
-            slug: payload.slug ?? null,
-            blocks: payload.blocks,
-            question: payload.question,
-            fields: payload.fieldSpec ?? [],
-            versionId: payload.currentVersionId ?? null,
-            models: payload.models ?? [],
-        }, "server", this.recorder());
-    }
-    build(spec, opts = {}) {
-        return buildCustomPrompt(spec, { ...opts, sdk: this.sdk });
-    }
-    warnOnEmptyTokens(outcome) {
-        if (this.warnedAboutTokens)
-            return;
-        if (outcome.status === "failed")
-            return;
-        if ((outcome.inputTokens ?? 0) > 0 || (outcome.outputTokens ?? 0) > 0)
-            return;
-        this.warnedAboutTokens = true;
-        console.warn("[prompt] trace() recorded a rollout with no tokens. This package never sees " +
-            "the provider response, so return inputTokens and outputTokens from your callback " +
-            "or every cost on this prompt reads as zero.");
-    }
-    async run(promptId, values = {}, opts = {}) {
-        return runOnce(this.sdk.prompts, promptId, values, opts, this.budget);
-    }
-    async sample(promptId, values = {}, opts = {}) {
-        return sampleRuns(this.sdk.prompts, promptId, values, { concurrency: this.concurrency, ...opts }, this.budget);
-    }
-    async runAll(promptId, values = {}, opts = {}) {
-        const models = opts.models ?? (await this.pull(promptId)).models;
-        if (models.length === 0) {
-            throw new Error("No models given and the prompt has none saved.");
-        }
-        return runAcrossModels(this.sdk.prompts, promptId, values, models, { concurrency: this.concurrency, ...opts }, this.budget);
-    }
-    async cases(promptId) {
-        return this.sdk.prompts.cases(promptId);
-    }
-    async setCases(promptId, cases) {
-        return this.sdk.prompts.putCases(promptId, cases);
-    }
-    spent() {
-        return this.budget.spent();
-    }
-    remaining() {
-        return this.budget.remaining();
-    }
-    async versions(promptId, opts = {}) {
-        return this.sdk.prompts.versions(promptId, opts);
-    }
-    async promote(promptId, versionId) {
-        const res = await this.sdk.prompts.promote(promptId, versionId);
-        this.invalidate(promptId);
-        return res;
-    }
-    invalidate(promptId) {
-        if (!promptId) {
-            this.cache.clear();
-            return;
-        }
-        for (const key of this.cache.keysWhere((p) => p.id === promptId || p.slug === promptId)) {
-            this.cache.delete(key);
-        }
-        this.cache.delete(promptId);
-        this.cache.invalidate(promptId);
-    }
-    async priced(promptId, input) {
-        const rolloutId = input.rolloutId ?? newRolloutId();
-        if (!this.hasKey)
-            return undefined;
-        try {
-            const res = (await this.sdk.prompts.report(promptId, { ...input, rolloutId }));
-            if (res.priced === false)
-                return undefined;
-            return res.rollout?.costMicros;
-        }
-        catch (err) {
-            this.onReportError?.(err);
-            return undefined;
-        }
-    }
-    async report(promptId, input) {
-        const rolloutId = input.rolloutId ?? newRolloutId();
-        if (!this.hasKey)
-            return rolloutId;
-        try {
-            await this.sdk.prompts.report(promptId, { ...input, rolloutId });
-        }
-        catch (err) {
-            this.onReportError?.(err);
-        }
-        return rolloutId;
-    }
-}
-export function pullPrompt(handle, opts) {
-    return new PromptClient(opts).pull(handle);
-}
+import{Spendgraph as h}from"@spendgraph/sdk";import{Budget as p}from"./budget/index.js";import{buildCustomPrompt as m}from"./build/index.js";import{PullCache as f}from"./cache/index.js";import{makePrompt as k}from"./prompt/index.js";import{pullWithCache as y}from"./pull/index.js";import{newRolloutId as i}from"./run/id.js";import{runAcrossModels as b,runOnce as w,sampleRuns as g}from"./run/index.js";const E=4;function a(o,r){const e=o?.prompt;if(!e||typeof e!="object"||typeof e.id!="string")throw new Error(`Asked for prompt "${r}" and the response carried no prompt. Check the base URL points at a spendgraph app and that the key can read this project.`);return e}class v{sdk;cache;hasKey;onReportError;concurrency;budget;warnedAboutTokens=!1;constructor(r){const{cache:e,onReportError:t,onPullError:s,concurrency:c,maxCostMicros:u,...d}=r;this.sdk=new h(d),this.cache=new f({...e,onRefreshError:e?.onRefreshError??s,identify:n=>[n.id,n.slug].filter(l=>!!l)}),this.hasKey=!!r.apiKey,this.onReportError=t,this.concurrency=Math.max(1,c??E),this.budget=new p("maxCostMicros"in r?u:void 0)}recorder(){return{enabled:!0,write:(r,e)=>(this.warnOnEmptyTokens(e),this.priced(r,e))}}async pull(r){const e=await y(this.cache,r,async()=>{const t=await this.sdk.prompts.get(r);return a(t,r)});return k({id:e.id,name:e.name??e.id,slug:e.slug??null,blocks:e.blocks??[],question:e.question??"",fields:e.fieldSpec??[],versionId:e.currentVersionId??null,models:e.models??[]},"server",this.recorder())}async create(r,e){const t=await this.sdk.prompts.create({projectId:e,name:r.name,...r.blocks?{blocks:r.blocks}:{},...r.question===void 0?{}:{question:r.question},...r.variables?{variables:r.variables}:{},...r.models?{models:r.models}:{}}),s=a(t,r.name);return this.pull(s.id)}build(r,e={}){return m(r,{onReportError:this.onReportError,...e,sdk:this.sdk})}warnOnEmptyTokens(r){this.warnedAboutTokens||r.status!=="failed"&&((r.inputTokens??0)>0||(r.outputTokens??0)>0||(this.warnedAboutTokens=!0,console.warn("[prompt] call() recorded a rollout with no tokens. This package never sees the provider response, so return inputTokens and outputTokens from your callback or every cost on this prompt reads as zero.")))}async run(r,e={},t={}){return w(this.sdk.prompts,r,e,t,this.budget)}async sample(r,e={},t={}){return g(this.sdk.prompts,r,e,{concurrency:this.concurrency,...t},this.budget)}async runAll(r,e={},t={}){const s=t.models??(await this.pull(r)).models;if(s.length===0)throw new Error("No models given and the prompt has none saved.");return b(this.sdk.prompts,r,e,s,{concurrency:this.concurrency,...t},this.budget)}async cases(r){return this.sdk.prompts.cases(r)}async setCases(r,e){return this.sdk.prompts.putCases(r,e)}spent(){return this.budget.spent()}remaining(){return this.budget.remaining()}async versions(r,e={}){return this.sdk.prompts.versions(r,e)}async promote(r,e){const t=await this.sdk.prompts.promote(r,e);return this.invalidate(r),t}invalidate(r){if(!r){this.cache.clear();return}for(const e of this.cache.keysWhere(t=>t.id===r||t.slug===r))this.cache.delete(e);this.cache.delete(r),this.cache.invalidate(r)}async priced(r,e){const t=e.rolloutId??i();if(this.hasKey)try{const s=await this.sdk.prompts.report(r,{...e,rolloutId:t});return s.priced===!1?void 0:s.rollout?.costMicros}catch(s){this.onReportError?.(s);return}}async report(r,e){const t=e.rolloutId??i();if(!this.hasKey)return t;try{await this.sdk.prompts.report(r,{...e,rolloutId:t})}catch(s){this.onReportError?.(s)}return t}}function M(o,r){return new v(r).pull(o)}export{v as PromptClient,M as pullPrompt};

package/dist/fingerprint/fingerprint.d.ts

@@ -0,0 +1,23 @@
+/** Everything about a prompt that decides what the model is actually sent. */
+export interface Worded {
+    name: string;
+    blocks: readonly {
+        title: string;
+        body: string;
+    }[];
+    question: string;
+}
+/**
+ * A stable id for what a prompt says, so its cost history follows the wording
+ * rather than where the wording is kept.
+ *
+ * Built here or stored on spendgraph, the same text fingerprints the same, so
+ * registering a prompt written in code carries its history across instead of
+ * starting over under a new version id.
+ *
+ * Not a cryptographic digest. It is a cache key, and it has to be computed
+ * synchronously everywhere this package runs, where `crypto.subtle` is async
+ * and `node:crypto` is not there at all. A collision costs two prompts a shared
+ * estimate, which is the whole of the damage.
+ */
+export declare function fingerprint(worded: Worded): string;

package/dist/fingerprint/fingerprint.js

@@ -0,0 +1 @@
+const a=2166136261,e=16777619,s="\0",h="
";function c(t,n){let o=n>>>0;for(let i=0;i<t.length;i++)o^=t.charCodeAt(i),o=Math.imul(o,16777619)>>>0;return o>>>0}function r(t){return[t.name,...t.blocks.map(n=>`${n.title}\0${n.body}`),t.question].join("
")}function g(t){const n=r(t),o=c(n,2166136261).toString(16).padStart(8,"0");return`sig:${c(n,2166136261^n.length+1).toString(16).padStart(8,"0")}${o}`}export{g as fingerprint};

package/dist/fingerprint/index.d.ts

@@ -0,0 +1,2 @@
+export type { Worded } from "./fingerprint.js";
+export { fingerprint } from "./fingerprint.js";

package/dist/fingerprint/index.js

@@ -0,0 +1 @@
+import{fingerprint as f}from"./fingerprint.js";export{f as fingerprint};

package/dist/index.d.ts

@@ -5,7 +5,9 @@ export type { BuildOptions } from "./build/index.js";
 export { buildCustomPrompt } from "./build/index.js";
 export type { PromptClientOptions } from "./client.js";
 export { PromptClient, pullPrompt } from "./client.js";
-export type { Answer, BatchOptions, Chain, InvokeOptions, Model } from "./prompt/index.js";
+export type { ContextLayer, LayerFit, PackedContext, PackOptions } from "./pack/index.js";
+export { approxTokens, packContext } from "./pack/index.js";
+export type { Answer, BatchOptions, Chain, InvokeOptions, Model, ModelOptions, } from "./prompt/index.js";
 export { MAX_RECORDED_MESSAGES } from "./prompt/index.js";
-export type { Block, History, Message } from "./render/index.js";
-export type { DatasetCase, DatasetSummary, Prompt, PromptSource, PromptSpec, PromptVersion, RenderOptions, ReportInput, RunOptions, RunResult, Split, TraceHandle, TraceOptions, TraceOutcome, } from "./types/index.js";
+export type { Block, History, Message, MessageCall } from "./render/index.js";
+export type { DatasetCase, DatasetSummary, Prompt, PromptSource, PromptSpec, PromptVersion, Recordable, RenderOptions, ReportInput, RunOptions, RunResult, Split, TraceHandle, TraceOptions, TraceOutcome, TurnRecord, TurnSource, } from "./types/index.js";

package/dist/index.js

@@ -1,5 +1 @@
-export { FieldValidationError } from "@spendgraph/sdk";
-export { BudgetExceededError } from "./budget/index.js";
-export { buildCustomPrompt } from "./build/index.js";
-export { PromptClient, pullPrompt } from "./client.js";
-export { MAX_RECORDED_MESSAGES } from "./prompt/index.js";
+import{FieldValidationError as t}from"@spendgraph/sdk";import{BudgetExceededError as p}from"./budget/index.js";import{buildCustomPrompt as x}from"./build/index.js";import{PromptClient as d,pullPrompt as f}from"./client.js";import{approxTokens as i,packContext as a}from"./pack/index.js";import{MAX_RECORDED_MESSAGES as u}from"./prompt/index.js";export{p as BudgetExceededError,t as FieldValidationError,u as MAX_RECORDED_MESSAGES,d as PromptClient,i as approxTokens,x as buildCustomPrompt,a as packContext,f as pullPrompt};

package/dist/internals.d.ts

@@ -9,9 +9,11 @@ export type { RolloutInput, RolloutRecord } from "@spendgraph/sdk";
 export { serializeFields, validateFields } from "@spendgraph/sdk";
 export { Budget } from "./budget/index.js";
 export type { CacheHit, CacheOptions } from "./cache/index.js";
+export type { Worded } from "./fingerprint/index.js";
+export { fingerprint } from "./fingerprint/index.js";
 export { PullCache } from "./cache/index.js";
-export type { ModelOptions, PromptShape, Recorder } from "./prompt/index.js";
+export type { PromptShape, Recorder } from "./prompt/index.js";
 export { bind, makePrompt, noRecorder } from "./prompt/index.js";
 export { pullWithCache } from "./pull/index.js";
 export { mapLimit, newRolloutId } from "./run/index.js";
-export type { PromptPayload, Recordable, Rollout, TurnRecord, TurnSource } from "./types/index.js";
+export type { PromptPayload, Rollout } from "./types/index.js";

package/dist/internals.js

@@ -1,6 +1 @@
-export { serializeFields, validateFields } from "@spendgraph/sdk";
-export { Budget } from "./budget/index.js";
-export { PullCache } from "./cache/index.js";
-export { bind, makePrompt, noRecorder } from "./prompt/index.js";
-export { pullWithCache } from "./pull/index.js";
-export { mapLimit, newRolloutId } from "./run/index.js";
+import{serializeFields as o,validateFields as t}from"@spendgraph/sdk";import{Budget as m}from"./budget/index.js";import{fingerprint as l}from"./fingerprint/index.js";import{PullCache as a}from"./cache/index.js";import{bind as x,makePrompt as n,noRecorder as u}from"./prompt/index.js";import{pullWithCache as h}from"./pull/index.js";import{mapLimit as g,newRolloutId as C}from"./run/index.js";export{m as Budget,a as PullCache,x as bind,l as fingerprint,n as makePrompt,g as mapLimit,C as newRolloutId,u as noRecorder,h as pullWithCache,o as serializeFields,t as validateFields};

package/dist/pack/index.d.ts

@@ -0,0 +1,3 @@
+export type { ContextLayer, LayerFit, PackedContext, PackOptions } from "./pack.js";
+export { packContext } from "./pack.js";
+export { approxTokens } from "./tokens.js";

package/dist/pack/index.js

@@ -0,0 +1 @@
+import{packContext as r}from"./pack.js";import{approxTokens as t}from"./tokens.js";export{t as approxTokens,r as packContext};

package/dist/pack/pack.d.ts

@@ -0,0 +1,58 @@
+export interface ContextLayer {
+    name: string;
+    /** Its parts, the ones most worth keeping first. */
+    parts: string[];
+    /** Tokens this layer may have. Omit and it shares whatever the others leave. */
+    budget?: number;
+    /**
+     * Kept whole, or the pack says it did not fit.
+     *
+     * The instructions and the question are the two nothing is worth dropping —
+     * a context that trimmed the question to make room for retrieved documents
+     * has spent the whole window on the wrong half of the request.
+     */
+    required?: boolean;
+}
+export interface LayerFit {
+    name: string;
+    kept: string[];
+    /** Parts that did not fit. */
+    dropped: number;
+    tokens: number;
+    /** What this layer was allowed: its own budget, or what was left when its turn came. */
+    allowed: number;
+}
+export interface PackedContext {
+    layers: LayerFit[];
+    /** Kept parts by layer name, ready to fill a template. */
+    kept: Record<string, string[]>;
+    tokens: number;
+    /** Room left under the budget. */
+    left: number;
+    /** The required layers alone did not fit, so the budget was never real. */
+    over: boolean;
+}
+export interface PackOptions {
+    /** Tokens the whole context may use. */
+    budget: number;
+    /** How a part is measured. Defaults to `approxTokens`. */
+    count?: (text: string) => number;
+}
+/**
+ * Fits several competing sources into one context window.
+ *
+ * A prompt's sources do not compete evenly. The instructions and the question
+ * have to be there whatever else is; retrieval is worth a fixed share and no
+ * more, because the tenth-best document is rarely worth the history it
+ * displaced; and what is left goes to the layers that can take whatever they
+ * are given. Assembling in that order is what stops the longest source — nearly
+ * always the history — from quietly crowding out the ones that were chosen.
+ *
+ * Parts within a layer are kept in the order given, so rank before packing:
+ * this drops from the end. A part that does not fit is dropped rather than cut
+ * in half, since half a retrieved document reads as a whole one to the model.
+ *
+ * Required layers are taken whole even when they overflow, and `over` says so.
+ * The alternative is a context that silently answers a trimmed question.
+ */
+export declare function packContext(layers: ContextLayer[], opts: PackOptions): PackedContext;

package/dist/pack/pack.js

@@ -0,0 +1 @@
+import{approxTokens as u}from"./tokens.js";function m(e,o){const a=e.parts.reduce((r,t)=>r+o(t),0);return{name:e.name,kept:[...e.parts],dropped:0,tokens:a,allowed:a}}function d(e,o,a){const r=[];let t=0;for(const p of e.parts){const c=a(p);if(t+c>o)break;r.push(p),t+=c}return{name:e.name,kept:r,dropped:e.parts.length-r.length,tokens:t,allowed:o}}function k(e,o){const a=o.count??u,r=new Map;let t=0;for(const n of e.filter(s=>s.required)){const s=m(n,a);r.set(n.name,s),t+=s.tokens}const p=t>o.budget;for(const n of e.filter(s=>!s.required)){const s=Math.max(0,o.budget-t),f=d(n,Math.min(n.budget??s,s),a);r.set(n.name,f),t+=f.tokens}const c=e.map(n=>r.get(n.name));return{layers:c,kept:Object.fromEntries(c.map(n=>[n.name,n.kept])),tokens:t,left:Math.max(0,o.budget-t),over:p}}export{k as packContext};

package/dist/pack/tokens.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Roughly how many tokens a string is, at four characters each.
+ *
+ * An estimate, and this package has no tokenizer to make it anything else —
+ * every provider's differs, and pulling one in would tie a rendering package to
+ * one vendor's vocabulary. Close enough to pack against, and the reason a pack
+ * leaves headroom rather than filling the window to its last token.
+ *
+ * Pass your own counter to `packContext` where the exact number matters.
+ */
+export declare function approxTokens(text: string): number;

package/dist/pack/tokens.js

@@ -0,0 +1 @@
+const o=4;function e(n){return n?Math.ceil(n.length/4):0}export{e as approxTokens};

package/dist/prompt/bind.d.ts

@@ -1,5 +1,5 @@
-import type { History, Message } from "../render/index.js";
-import type { Prompt, TraceOutcome } from "../types/index.js";
+import type { Message } from "../render/index.js";
+import type { Prompt, TraceOptions, TraceOutcome } from "../types/index.js";
 /**
  * Anything that can answer a list of messages.
  *
@@ -17,22 +17,8 @@ export interface ModelOptions {
     tools?: unknown;
     onText?: (delta: string) => void;
 }
-export interface InvokeOptions {
-    /** Prior turns, oldest first. */
-    history?: History;
-    /** A bus to select from. The turn is passed to the model and to the rollout. */
-    tools?: {
-        trace(query?: string, limit?: number): {
-            record(): unknown;
-        };
-    };
-    /** What to select tools on. Defaults to the rendered question. */
-    query?: string;
-    /** False runs the model and records nothing. */
-    report?: boolean;
-    /** Supply your own to make a retry safe. */
-    rolloutId?: string;
-}
+/** What one invocation may be given; the same options `Prompt.call` takes. */
+export type InvokeOptions = TraceOptions;
 export interface BatchOptions extends InvokeOptions {
     /** Max calls in flight. Default 4. */
     concurrency?: number;
@@ -49,6 +35,15 @@ export interface Chain {
         onText?: (delta: string) => void;
     }): Promise<Answer>;
     /** One call per set of values, concurrency-capped. */
+    /**
+     * Every row, at most `concurrency` at a time, in the order they were given.
+     *
+     * A row that throws comes back as a failed `Answer` rather than taking the
+     * batch down with it — the point of sending five hundred is that the other
+     * four hundred and ninety-nine still land, and they have already been paid
+     * for by the time one of them fails. Each carries the `rolloutId` its record
+     * was written under, so a failure is traceable to a row rather than to a job.
+     */
     batch(values: Record<string, unknown>[], opts?: BatchOptions): Promise<Answer[]>;
 }
 /**

package/dist/prompt/bind.js

@@ -1,15 +1 @@
-import { mapLimit } from "../run/concurrency.js";
-const DEFAULT_CONCURRENCY = 4;
-export function bind(prompt, model) {
-    const once = (values, opts, streaming) => prompt.call(values, ({ messages, turn }) => {
-        const modelOpts = { tools: turn, onText: opts.onText };
-        return streaming && model.stream
-            ? model.stream(messages, modelOpts)
-            : model.call(messages, modelOpts);
-    }, opts);
-    return {
-        invoke: (values = {}, opts = {}) => once(values, opts, false),
-        stream: (values = {}, opts = {}) => once(values, opts, true),
-        batch: (values, opts = {}) => mapLimit(values, opts.concurrency ?? DEFAULT_CONCURRENCY, (v) => once(v, opts, false)),
-    };
-}
+import{mapLimit as i}from"../run/concurrency.js";import{newRolloutId as m}from"../run/id.js";const d=4;function w(c,n){const e=(r,t,o)=>c.call(r,({messages:l,turn:s})=>{const a={tools:s,onText:t.onText};return o&&n.stream?n.stream(l,a):n.call(l,a)},t),u=async(r,t)=>{try{return await e(r,t,!1)}catch(o){return{rolloutId:t.rolloutId,output:"",model:"unknown",status:"failed",error:o instanceof Error?o.message:String(o)}}};return{invoke:(r={},t={})=>e(r,t,!1),stream:(r={},t={})=>e(r,t,!0),batch:(r,t={})=>i(r,t.concurrency??d,o=>u(o,{...t,rolloutId:t.rolloutId??m()}))}}export{w as bind};

package/dist/prompt/factory.d.ts

@@ -17,7 +17,7 @@ export interface PromptShape {
  *
  * A server prompt writes a rollout; a custom one has no row to hang one on and
  * writes usage instead. Injecting it is what lets both constructors share one
- * `trace`, so the two can never drift on what "recorded" means.
+ * `call`, so the two can never drift on what "recorded" means.
  */
 export interface Recorder {
     enabled: boolean;