pareta 2.0.0 → 3.0.0

package/README.md

@@ -41,7 +41,7 @@ contender honestly:
 
 ```ts
 const set = await pa.evals.sets.create({
-  items: [...], intent: "extract vendor, total and date from each invoice",
+  items: [...], prompt: "extract vendor, total and date from each invoice",
 });
 const run = await pa.evals.runs.create({
   evalSet: set.id, models: ["auto"], frontier: ["claude-opus-4-7"], wait: true,

package/dist/index.cjs

@@ -174,7 +174,7 @@ function parseSSE(reader, opts) {
 }
 
 // src/version.ts
-var VERSION = "2.0.0";
+var VERSION = "3.0.0";
 
 // src/money.ts
 var MICRO_PER_CENT = 10000n;
@@ -255,6 +255,36 @@ var ChatCompletion = class extends BaseModel {
   get usage() {
     return new Usage(this.raw.usage ?? {});
   }
+  /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+  _cost;
+  /** #164: attach the per-call receipt from the response headers (billed +
+   * the frontier counterfactual, micro-USD ints). Chainable. */
+  withCost(headers) {
+    const int = (name) => {
+      const v = headers?.get(name);
+      if (v == null) return null;
+      const n = parseInt(v, 10);
+      return Number.isNaN(n) ? null : n;
+    };
+    this._cost = {
+      billed: int("X-Pareta-Billed"),
+      frontier: int("X-Pareta-Frontier-Would-Have-Cost")
+    };
+    return this;
+  }
+  /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+  get billedMicroUsd() {
+    return this._cost?.billed ?? null;
+  }
+  /** What one list-priced frontier call would have cost, micro-USD. */
+  get frontierWouldHaveCostMicroUsd() {
+    return this._cost?.frontier ?? null;
+  }
+  /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+  get savingsFactor() {
+    const b = this.billedMicroUsd, f = this.frontierWouldHaveCostMicroUsd;
+    return b && f && b > 0 ? Math.round(f / b * 10) / 10 : null;
+  }
 };
 var ChatCompletionChunk = class extends ChatCompletion {
 };
@@ -342,9 +372,9 @@ var EvalSet = class extends BaseModel {
     return this.raw.scoring_strategy ?? null;
   }
   /** The one-sentence success criterion this set was created with (CB1:
-   * DATA + INTENT). Required at create. */
-  get intent() {
-    return this.raw.intent ?? null;
+   * DATA + PROMPT). Required at create. */
+  get prompt() {
+    return this.raw.prompt ?? null;
   }
 };
 function evalSetFromCreate(raw) {
@@ -383,23 +413,24 @@ var ProposalResult = class extends BaseModel {
   get closestTask() {
     return this.raw.closest_task ?? null;
   }
-  get intent() {
-    return this.raw.intent ?? null;
+  get prompt() {
+    return this.raw.prompt ?? null;
   }
   get message() {
     return this.raw.message ?? null;
   }
-  /** True when the binder matched exactly ONE homogeneous SPECIFIC contract at
-   * high/medium confidence and no conflict/split — the case `create` auto-binds
-   * without a human confirming. The `custom-eval` universal FLOOR is EXCLUDED:
-   * the binder offers it only when no specific contract fits, and per the
-   * precision ladder the floor is a CHOICE — the user opts in with
-   * `task: "custom-eval"`, never a silent auto-bind. */
+  /** True when exactly ONE homogeneous SPECIFIC task matched at high/medium
+   * confidence with no conflict/split — the case a task-less `create`
+   * proceeds with, no human confirming. `custom-eval` (a judge panel grading
+   * each answer against your prompt) is EXCLUDED: it is offered only when
+   * nothing specific fits, and using it is the user's CHOICE — opt in with
+   * `task: "custom-eval"`, never silently. */
   get isClean() {
     const props = this.proposals;
     return this.homogeneous && this.conflict == null && this.split == null && props.length === 1 && (props[0].confidence === "high" || props[0].confidence === "medium") && Boolean(props[0].taskId) && props[0].taskId !== "custom-eval";
   }
-  /** The task `create` would auto-bind, or null if the result isn't clean. */
+  /** How a task-less `create` would score this set, or null if the result
+   * isn't clean (pass `task` yourself). */
   get boundTask() {
     return this.isClean ? this.proposals[0].taskId : null;
   }
@@ -644,10 +675,14 @@ var Completions = class {
         cast: (raw) => new ChatCompletionChunk(raw)
       });
     }
+    let headers;
     return this.client.request("POST", PATH, {
       body,
-      cast: (raw) => new ChatCompletion(raw)
-    });
+      cast: (raw) => new ChatCompletion(raw),
+      onHeaders: (h) => {
+        headers = h;
+      }
+    }).then((completion) => completion.withCost(headers));
   }
 };
 var Chat = class {
@@ -744,37 +779,37 @@ async function toBlob(file, mimeOverride) {
   const mime = mimeOverride || "application/octet-stream";
   return { blob: new Blob([bytes], { type: mime }), filename: "upload", size: bytes.byteLength, mime };
 }
-function requireIntent(intent) {
-  const s = (intent ?? "").trim();
+function requirePrompt(prompt) {
+  const s = (prompt ?? "").trim();
   if (!s) {
     throw new ParetaError(
-      'intent is required: one sentence describing what the model should do with each item (e.g. "extract vendor, total and date from each invoice"). Pass intent to evals.create / proposeContract.'
+      'prompt is required: one sentence describing what the model should do with each item (e.g. "extract vendor, total and date from each invoice"). Pass prompt to evals.create / proposeContract.'
     );
   }
   return s.slice(0, 500);
 }
-function itemsJsonl(task, items, intent, name) {
+function itemsJsonl(task, items, prompt, name) {
   if (!items || items.length === 0) throw new ParetaError("items is required and must be non-empty");
   const jsonl = items.map((it) => JSON.stringify(it)).join("\n");
   return {
     files: { items: { filename: `items.${task}.jsonl`, content: jsonl, contentType: "application/jsonl" } },
-    data: { task_id: task, intent, name: name || `sdk eval set (${items.length} items)` }
+    data: { task_id: task, prompt, name: name || `sdk eval set (${items.length} items)` }
   };
 }
-function proposeMultipart(items, intent) {
+function proposeMultipart(items, prompt) {
   if (!items || items.length === 0) throw new ParetaError("items is required and must be non-empty");
   const jsonl = items.map((it) => JSON.stringify(it)).join("\n");
   return {
     files: { items: { filename: "items.jsonl", content: jsonl, contentType: "application/jsonl" } },
-    data: { intent }
+    data: { prompt }
   };
 }
 function bindError(result) {
-  const intent = result.intent ?? "";
+  const prompt = result.prompt ?? "";
   if (result.conflict) {
     const c = result.conflict;
     return new ParetaError(
-      `intent '${intent}' describes a different job than the data's shape supports (reads as '${c.intended_task}': ${c.reasoning}). Pass a task to pin a contract, or revise the intent.`
+      `prompt '${prompt}' describes a different job than the data's shape supports (reads as '${c.intended_task}': ${c.reasoning}). Pass a task to pin the task, or revise the prompt.`
     );
   }
   if (result.split) {
@@ -787,14 +822,14 @@ function bindError(result) {
   if (props.length === 1 && props[0].taskId === "custom-eval") {
     const warn = props[0].warning ? ` (${props[0].warning})` : "";
     return new ParetaError(
-      `no specific grading contract fits this data for intent '${intent}'. The custom-eval universal floor is available \u2014 it grades by judged win-rate vs the frontier anchor.${warn} Pass task: "custom-eval" to use it, or revise the data/intent for a specific contract.`
+      `no ready-made scorer fits this data for prompt '${prompt}'. A judge panel can grade each answer against what you asked for (win rate vs gpt-5.5) \u2014 pass task: "custom-eval" to use it.${warn} Or revise the data/prompt so a specific task fits.`
     );
   }
   const options = props.map((p) => p.taskId).filter(Boolean);
   if (options.length === 0 && result.closestTask) options.push(result.closestTask);
   const hint = options.length ? ` Candidates: ${options.join(", ")}.` : "";
   return new ParetaError(
-    `could not confidently bind a grading contract for intent '${intent}'.${hint} Pass a task to pin one, or inspect evals.proposeContract({ items, intent }).`
+    `couldn't work out how to score this for prompt '${prompt}'.${hint} Pass a task to choose yourself, or inspect evals.proposeContract({ items, prompt }).`
   );
 }
 function mergeCandidates(models, frontierIds) {
@@ -818,27 +853,27 @@ var EvalSets = class {
   }
   client;
   /**
-   * Persist an eval set from your rows. `intent` is REQUIRED (v2): one sentence
-   * on what the model should do with each item. `task` is OPTIONAL — omit it and
-   * the binder resolves your intent + the data's shape to a grading contract
-   * (auto-binds a clean single match; throws with the proposals otherwise). Pass
-   * `task` to pin one explicitly.
+   * Persist an eval set from your rows. `prompt` is REQUIRED (v3): one sentence
+   * on what the model should do with each item. `task` is OPTIONAL — omit it
+   * and Pareta works out how to score the results from your prompt + the
+   * data's shape (a clean single match is used; anything ambiguous throws with
+   * the proposals). Pass `task` to pin one explicitly.
    */
   async create(params) {
-    const intent = requireIntent(params.intent);
+    const prompt = requirePrompt(params.prompt);
     let task = params.task;
     if (task == null) {
-      const proposal = await this.proposeContract(params.items, intent);
+      const proposal = await this.proposeContract(params.items, prompt);
       task = proposal.boundTask ?? void 0;
       if (task == null) throw bindError(proposal);
     }
-    const { files, data } = itemsJsonl(task, params.items, intent, params.name);
+    const { files, data } = itemsJsonl(task, params.items, prompt, params.name);
     return this.client.request("POST", BASE2, { files, data, cast: evalSetFromCreate });
   }
-  /** Internal: the binder call `create` uses when no task is pinned. Public on
+  /** Internal: the propose call `create` uses when no task is pinned. Public on
    * `Evals` as `proposeContract`; kept here so `sets.create` can reach it. */
-  proposeContract(items, intent) {
-    const { files, data } = proposeMultipart(items, requireIntent(intent));
+  proposeContract(items, prompt) {
+    const { files, data } = proposeMultipart(items, requirePrompt(prompt));
     return this.client.request("POST", PROPOSE, { files, data, cast: proposalResult });
   }
   list() {
@@ -909,11 +944,11 @@ var EvalRuns = class {
     let evalSet = params.evalSet;
     if (evalSet == null) {
       if (!params.items) {
-        throw new ParetaError("pass evalSet: <id>, or items (+ intent) to create one");
+        throw new ParetaError("pass evalSet: <id>, or items (+ prompt) to create one");
       }
       evalSet = (await this.sets.create({
         items: params.items,
-        intent: params.intent,
+        prompt: params.prompt,
         task: params.task,
         name: params.name
       })).id ?? void 0;
@@ -957,13 +992,14 @@ var Evals = class {
   }
   client;
   /**
-   * Which grading contract fits your data under your stated `intent`? Stateless
+   * How would your data be scored under your stated `prompt`? Stateless
    * discovery — nothing is persisted. Returns a ProposalResult (ranked
-   * proposals, the auto-bind decision, conflict/split reporting). `sets.create`
-   * calls this under the hood; use it directly to preview the binding first.
+   * proposals, the task a task-less create would use, conflict/split
+   * reporting). `sets.create` calls this under the hood; use it directly to
+   * preview the scoring first.
    */
   proposeContract(params) {
-    return this.sets.proposeContract(params.items, params.intent);
+    return this.sets.proposeContract(params.items, params.prompt);
   }
   /**
    * The frontier (vendor) roster you can evaluate against. With `task`, each is
@@ -1310,6 +1346,7 @@ var Pareta = class _Pareta {
         break;
       }
       if (res.ok) {
+        if (opts.onHeaders) opts.onHeaders(res.headers);
         const text = await res.text();
         const raw = text ? JSON.parse(text) : {};
         return cast ? cast(raw) : raw;