pareta 2.0.0 → 3.0.0

package/dist/index.d.cts

@@ -47,6 +47,17 @@ declare class ChatCompletion extends BaseModel {
     get created(): number | null;
     get choices(): Choice[];
     get usage(): Usage;
+    /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+    private _cost?;
+    /** #164: attach the per-call receipt from the response headers (billed +
+     * the frontier counterfactual, micro-USD ints). Chainable. */
+    withCost(headers?: Headers): ChatCompletion;
+    /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+    get billedMicroUsd(): number | null;
+    /** What one list-priced frontier call would have cost, micro-USD. */
+    get frontierWouldHaveCostMicroUsd(): number | null;
+    /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+    get savingsFactor(): number | null;
 }
 /** One SSE delta. `chunk.choices[0].delta.content` is the incremental text. */
 declare class ChatCompletionChunk extends ChatCompletion {
@@ -88,13 +99,13 @@ declare class EvalSet extends BaseModel {
     get itemCount(): number | null;
     get scoringStrategy(): string | null;
     /** The one-sentence success criterion this set was created with (CB1:
-     * DATA + INTENT). Required at create. */
-    get intent(): string | null;
+     * DATA + PROMPT). Required at create. */
+    get prompt(): string | null;
 }
 /**
- * One proposed grading contract for an uploaded dataset (a row of
- * `ProposalResult.proposals`). `warning` is set on the custom-eval floor when
- * the data looks extraction-shaped (judge grading is weaker there).
+ * One proposed way to score an uploaded dataset (a row of
+ * `ProposalResult.proposals`). `warning` is set on a "custom-eval" proposal
+ * when the data looks extraction-shaped (judge grading is weaker there).
  */
 declare class ContractProposal extends BaseModel {
     get taskId(): string | null;
@@ -103,10 +114,10 @@ declare class ContractProposal extends BaseModel {
     get warning(): string | null;
 }
 /**
- * The binder's answer for `evals.proposeContract` (POST
- * /v1/eval-sets/propose-contract): which grading contract(s) fit your data
- * under your stated intent. Nothing is persisted — confirm by passing the
- * chosen `taskId` (or letting `create` auto-bind a clean single proposal).
+ * Pareta's answer for `evals.proposeContract` (POST
+ * /v1/eval-sets/propose-contract): how your data could be scored under your
+ * stated prompt. Nothing is persisted — confirm by passing the chosen
+ * `taskId` (or letting a task-less `create` use a clean single proposal).
  */
 declare class ProposalResult extends BaseModel {
     get proposals(): ContractProposal[];
@@ -114,16 +125,17 @@ declare class ProposalResult extends BaseModel {
     get split(): Raw | null;
     get conflict(): Raw | null;
     get closestTask(): string | null;
-    get intent(): string | null;
+    get prompt(): string | null;
     get message(): string | 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(): boolean;
-    /** 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(): string | null;
 }
 /**
@@ -319,16 +331,17 @@ declare class Tasks {
 /**
  * `client.evals` — eval sets + runs (bring-your-own-data evaluation).
  *
- *   // An eval set is DATA + INTENT (v2, breaking): intent REQUIRED, task
- *   // OPTIONAL — the binder resolves your intent + the data's shape.
- *   await pa.evals.proposeContract({ items: [...], intent: "…" });   // preview
- *   const set = await pa.evals.sets.create({ items: [...], intent: "…" });  // auto-binds
+ *   // An eval set is DATA + PROMPT (v3, breaking): prompt REQUIRED, task
+ *   // OPTIONAL — Pareta works out how to score the results from your
+ *   // prompt + the data's shape.
+ *   await pa.evals.proposeContract({ items: [...], prompt: "…" });   // preview
+ *   const set = await pa.evals.sets.create({ items: [...], prompt: "…" });  // clean match used automatically
  *   await pa.evals.sets.uploadDocument(set.id, file, { idx, fieldName });   // blob tasks
  *   const run = await pa.evals.runs.create({ evalSet: set.id, models: [...], wait: true });
- *   // or, in one call: runs.create({ items, intent: "…", models, wait: true })
+ *   // or, in one call: runs.create({ items, prompt: "…", models, wait: true })
  *
- * `create` (and the inline `runs.create` sugar) require `intent`; with no
- * `task` they call `proposeContract` and auto-bind ONLY a clean single
+ * `create` (and the inline `runs.create` sugar) require `prompt`; with no
+ * `task` they call `proposeContract` and accept ONLY a clean single
  * high/medium match — a conflict, split, or ambiguity throws with the
  * proposals so you pin `task`.
  *
@@ -346,21 +359,21 @@ declare class EvalSets {
     private readonly client;
     constructor(client: Transport);
     /**
-     * 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.
      */
     create(params: {
         items: Array<Record<string, unknown>>;
-        intent: string;
+        prompt: string;
         task?: string;
         name?: string;
     }): Promise<EvalSet>;
-    /** 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: Array<Record<string, unknown>>, intent: string): Promise<ProposalResult>;
+    proposeContract(items: Array<Record<string, unknown>>, prompt: string): Promise<ProposalResult>;
     list(): Promise<EvalSet[]>;
     retrieve(evalSetId: string): Promise<EvalSet>;
     delete(evalSetId: string): Promise<void>;
@@ -379,7 +392,7 @@ interface EvalRunCreateParams {
     evalSet?: string;
     task?: string;
     items?: Array<Record<string, unknown>>;
-    intent?: string;
+    prompt?: string;
     models: string[];
     frontier?: FrontierSpec;
     name?: string;
@@ -405,14 +418,15 @@ declare class Evals {
     constructor(client: Transport);
     private readonly 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: {
         items: Array<Record<string, unknown>>;
-        intent: string;
+        prompt: string;
     }): Promise<ProposalResult>;
     /**
      * The frontier (vendor) roster you can evaluate against. With `task`, each is
@@ -632,6 +646,9 @@ interface RequestOptions {
     files?: Record<string, FilePart>;
     data?: Record<string, string>;
     cast?: (raw: unknown) => unknown;
+    /** Invoked with the response headers on success (before the body is cast) —
+     * lets a caller read receipt headers (#164: X-Pareta-Billed + counterfactual). */
+    onHeaders?: (headers: Headers) => void;
 }
 interface StreamOptions {
     body?: unknown;
@@ -698,7 +715,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.0.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python

package/dist/index.d.ts

@@ -47,6 +47,17 @@ declare class ChatCompletion extends BaseModel {
     get created(): number | null;
     get choices(): Choice[];
     get usage(): Usage;
+    /** #164 receipt, held OFF `.raw` so `toDict()` stays the raw server JSON. */
+    private _cost?;
+    /** #164: attach the per-call receipt from the response headers (billed +
+     * the frontier counterfactual, micro-USD ints). Chainable. */
+    withCost(headers?: Headers): ChatCompletion;
+    /** What Pareta charged, micro-USD (0 on an idempotent replay); null if absent. */
+    get billedMicroUsd(): number | null;
+    /** What one list-priced frontier call would have cost, micro-USD. */
+    get frontierWouldHaveCostMicroUsd(): number | null;
+    /** frontier / billed — e.g. 17 = 17× cheaper; null if either is missing or billed is 0. */
+    get savingsFactor(): number | null;
 }
 /** One SSE delta. `chunk.choices[0].delta.content` is the incremental text. */
 declare class ChatCompletionChunk extends ChatCompletion {
@@ -88,13 +99,13 @@ declare class EvalSet extends BaseModel {
     get itemCount(): number | null;
     get scoringStrategy(): string | null;
     /** The one-sentence success criterion this set was created with (CB1:
-     * DATA + INTENT). Required at create. */
-    get intent(): string | null;
+     * DATA + PROMPT). Required at create. */
+    get prompt(): string | null;
 }
 /**
- * One proposed grading contract for an uploaded dataset (a row of
- * `ProposalResult.proposals`). `warning` is set on the custom-eval floor when
- * the data looks extraction-shaped (judge grading is weaker there).
+ * One proposed way to score an uploaded dataset (a row of
+ * `ProposalResult.proposals`). `warning` is set on a "custom-eval" proposal
+ * when the data looks extraction-shaped (judge grading is weaker there).
  */
 declare class ContractProposal extends BaseModel {
     get taskId(): string | null;
@@ -103,10 +114,10 @@ declare class ContractProposal extends BaseModel {
     get warning(): string | null;
 }
 /**
- * The binder's answer for `evals.proposeContract` (POST
- * /v1/eval-sets/propose-contract): which grading contract(s) fit your data
- * under your stated intent. Nothing is persisted — confirm by passing the
- * chosen `taskId` (or letting `create` auto-bind a clean single proposal).
+ * Pareta's answer for `evals.proposeContract` (POST
+ * /v1/eval-sets/propose-contract): how your data could be scored under your
+ * stated prompt. Nothing is persisted — confirm by passing the chosen
+ * `taskId` (or letting a task-less `create` use a clean single proposal).
  */
 declare class ProposalResult extends BaseModel {
     get proposals(): ContractProposal[];
@@ -114,16 +125,17 @@ declare class ProposalResult extends BaseModel {
     get split(): Raw | null;
     get conflict(): Raw | null;
     get closestTask(): string | null;
-    get intent(): string | null;
+    get prompt(): string | null;
     get message(): string | 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(): boolean;
-    /** 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(): string | null;
 }
 /**
@@ -319,16 +331,17 @@ declare class Tasks {
 /**
  * `client.evals` — eval sets + runs (bring-your-own-data evaluation).
  *
- *   // An eval set is DATA + INTENT (v2, breaking): intent REQUIRED, task
- *   // OPTIONAL — the binder resolves your intent + the data's shape.
- *   await pa.evals.proposeContract({ items: [...], intent: "…" });   // preview
- *   const set = await pa.evals.sets.create({ items: [...], intent: "…" });  // auto-binds
+ *   // An eval set is DATA + PROMPT (v3, breaking): prompt REQUIRED, task
+ *   // OPTIONAL — Pareta works out how to score the results from your
+ *   // prompt + the data's shape.
+ *   await pa.evals.proposeContract({ items: [...], prompt: "…" });   // preview
+ *   const set = await pa.evals.sets.create({ items: [...], prompt: "…" });  // clean match used automatically
  *   await pa.evals.sets.uploadDocument(set.id, file, { idx, fieldName });   // blob tasks
  *   const run = await pa.evals.runs.create({ evalSet: set.id, models: [...], wait: true });
- *   // or, in one call: runs.create({ items, intent: "…", models, wait: true })
+ *   // or, in one call: runs.create({ items, prompt: "…", models, wait: true })
  *
- * `create` (and the inline `runs.create` sugar) require `intent`; with no
- * `task` they call `proposeContract` and auto-bind ONLY a clean single
+ * `create` (and the inline `runs.create` sugar) require `prompt`; with no
+ * `task` they call `proposeContract` and accept ONLY a clean single
  * high/medium match — a conflict, split, or ambiguity throws with the
  * proposals so you pin `task`.
  *
@@ -346,21 +359,21 @@ declare class EvalSets {
     private readonly client;
     constructor(client: Transport);
     /**
-     * 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.
      */
     create(params: {
         items: Array<Record<string, unknown>>;
-        intent: string;
+        prompt: string;
         task?: string;
         name?: string;
     }): Promise<EvalSet>;
-    /** 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: Array<Record<string, unknown>>, intent: string): Promise<ProposalResult>;
+    proposeContract(items: Array<Record<string, unknown>>, prompt: string): Promise<ProposalResult>;
     list(): Promise<EvalSet[]>;
     retrieve(evalSetId: string): Promise<EvalSet>;
     delete(evalSetId: string): Promise<void>;
@@ -379,7 +392,7 @@ interface EvalRunCreateParams {
     evalSet?: string;
     task?: string;
     items?: Array<Record<string, unknown>>;
-    intent?: string;
+    prompt?: string;
     models: string[];
     frontier?: FrontierSpec;
     name?: string;
@@ -405,14 +418,15 @@ declare class Evals {
     constructor(client: Transport);
     private readonly 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: {
         items: Array<Record<string, unknown>>;
-        intent: string;
+        prompt: string;
     }): Promise<ProposalResult>;
     /**
      * The frontier (vendor) roster you can evaluate against. With `task`, each is
@@ -632,6 +646,9 @@ interface RequestOptions {
     files?: Record<string, FilePart>;
     data?: Record<string, string>;
     cast?: (raw: unknown) => unknown;
+    /** Invoked with the response headers on success (before the body is cast) —
+     * lets a caller read receipt headers (#164: X-Pareta-Billed + counterfactual). */
+    onHeaders?: (headers: Headers) => void;
 }
 interface StreamOptions {
     body?: unknown;
@@ -698,7 +715,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "2.0.0";
+declare const VERSION = "3.0.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python

package/dist/index.mjs

@@ -172,7 +172,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;
@@ -253,6 +253,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 {
 };
@@ -340,9 +370,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) {
@@ -381,23 +411,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;
   }
@@ -642,10 +673,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 {
@@ -742,37 +777,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) {
@@ -785,14 +820,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) {
@@ -816,27 +851,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() {
@@ -907,11 +942,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;
@@ -955,13 +990,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
@@ -1308,6 +1344,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;