pareta 1.4.0 → 2.1.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 {
@@ -87,6 +98,44 @@ declare class EvalSet extends BaseModel {
     get name(): string | null;
     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;
+}
+/**
+ * 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).
+ */
+declare class ContractProposal extends BaseModel {
+    get taskId(): string | null;
+    get confidence(): string | null;
+    get evidence(): Raw;
+    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).
+ */
+declare class ProposalResult extends BaseModel {
+    get proposals(): ContractProposal[];
+    get homogeneous(): boolean;
+    get split(): Raw | null;
+    get conflict(): Raw | null;
+    get closestTask(): string | null;
+    get intent(): 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. */
+    get isClean(): boolean;
+    /** The task `create` would auto-bind, or null if the result isn't clean. */
+    get boundTask(): string | null;
 }
 /**
  * One scored item inside `EvalResult.perItem`. `prediction` is the model's raw
@@ -281,10 +330,18 @@ declare class Tasks {
 /**
  * `client.evals` — eval sets + runs (bring-your-own-data evaluation).
  *
- *   const set = await pa.evals.sets.create({ task, items: [...] });
+ *   // 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
  *   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({ task, items, models, wait: true })
+ *   // or, in one call: runs.create({ items, intent: "…", 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
+ * high/medium match — a conflict, split, or ambiguity throws with the
+ * proposals so you pin `task`.
  *
  * Runs are metered (the org balance is debited for compute); `run.cost` is the
  * billed total in dollars (floored to cents). `frontier` accepts an explicit
@@ -299,11 +356,22 @@ type FileInput = string | Blob | ArrayBuffer | Uint8Array;
 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.
+     */
     create(params: {
-        task: string;
         items: Array<Record<string, unknown>>;
+        intent: string;
+        task?: string;
         name?: string;
     }): Promise<EvalSet>;
+    /** Internal: the binder 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>;
     list(): Promise<EvalSet[]>;
     retrieve(evalSetId: string): Promise<EvalSet>;
     delete(evalSetId: string): Promise<void>;
@@ -322,6 +390,7 @@ interface EvalRunCreateParams {
     evalSet?: string;
     task?: string;
     items?: Array<Record<string, unknown>>;
+    intent?: string;
     models: string[];
     frontier?: FrontierSpec;
     name?: string;
@@ -346,6 +415,16 @@ declare class Evals {
     readonly runs: EvalRuns;
     constructor(client: Transport);
     private readonly client;
+    /**
+     * Which grading contract fits your data under your stated `intent`? 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.
+     */
+    proposeContract(params: {
+        items: Array<Record<string, unknown>>;
+        intent: string;
+    }): Promise<ProposalResult>;
     /**
      * The frontier (vendor) roster you can evaluate against. With `task`, each is
      * annotated `benchmarked` + the roster is vision-filtered for document tasks.
@@ -564,6 +643,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;
@@ -630,7 +712,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "1.4.0";
+declare const VERSION = "2.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python
@@ -722,4 +804,4 @@ declare class EndpointNotReadyError extends APIStatusError {
     constructor(message: string, init: APIStatusErrorInit);
 }
 
-export { APIConnectionError, APIStatusError, APITimeoutError, Audio, type AudioInput, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, Embeddings, type EmbeddingsFn, type EmbeddingsOptions, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, type ImageEditOptions, type ImageGenerateOptions, ImageGeneration, type ImageInput, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Speech, type SpeechOptions, Task, TaskMatch, TaskMatchCandidate, Transcription, type TranscriptionOptions, type Transport, Usage, VERSION, type ValidationErrorItem };
+export { APIConnectionError, APIStatusError, APITimeoutError, Audio, type AudioInput, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, ContractProposal, Embeddings, type EmbeddingsFn, type EmbeddingsOptions, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, type ImageEditOptions, type ImageGenerateOptions, ImageGeneration, type ImageInput, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, ProposalResult, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Speech, type SpeechOptions, Task, TaskMatch, TaskMatchCandidate, Transcription, type TranscriptionOptions, type Transport, Usage, VERSION, type ValidationErrorItem };

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 {
@@ -87,6 +98,44 @@ declare class EvalSet extends BaseModel {
     get name(): string | null;
     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;
+}
+/**
+ * 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).
+ */
+declare class ContractProposal extends BaseModel {
+    get taskId(): string | null;
+    get confidence(): string | null;
+    get evidence(): Raw;
+    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).
+ */
+declare class ProposalResult extends BaseModel {
+    get proposals(): ContractProposal[];
+    get homogeneous(): boolean;
+    get split(): Raw | null;
+    get conflict(): Raw | null;
+    get closestTask(): string | null;
+    get intent(): 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. */
+    get isClean(): boolean;
+    /** The task `create` would auto-bind, or null if the result isn't clean. */
+    get boundTask(): string | null;
 }
 /**
  * One scored item inside `EvalResult.perItem`. `prediction` is the model's raw
@@ -281,10 +330,18 @@ declare class Tasks {
 /**
  * `client.evals` — eval sets + runs (bring-your-own-data evaluation).
  *
- *   const set = await pa.evals.sets.create({ task, items: [...] });
+ *   // 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
  *   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({ task, items, models, wait: true })
+ *   // or, in one call: runs.create({ items, intent: "…", 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
+ * high/medium match — a conflict, split, or ambiguity throws with the
+ * proposals so you pin `task`.
  *
  * Runs are metered (the org balance is debited for compute); `run.cost` is the
  * billed total in dollars (floored to cents). `frontier` accepts an explicit
@@ -299,11 +356,22 @@ type FileInput = string | Blob | ArrayBuffer | Uint8Array;
 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.
+     */
     create(params: {
-        task: string;
         items: Array<Record<string, unknown>>;
+        intent: string;
+        task?: string;
         name?: string;
     }): Promise<EvalSet>;
+    /** Internal: the binder 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>;
     list(): Promise<EvalSet[]>;
     retrieve(evalSetId: string): Promise<EvalSet>;
     delete(evalSetId: string): Promise<void>;
@@ -322,6 +390,7 @@ interface EvalRunCreateParams {
     evalSet?: string;
     task?: string;
     items?: Array<Record<string, unknown>>;
+    intent?: string;
     models: string[];
     frontier?: FrontierSpec;
     name?: string;
@@ -346,6 +415,16 @@ declare class Evals {
     readonly runs: EvalRuns;
     constructor(client: Transport);
     private readonly client;
+    /**
+     * Which grading contract fits your data under your stated `intent`? 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.
+     */
+    proposeContract(params: {
+        items: Array<Record<string, unknown>>;
+        intent: string;
+    }): Promise<ProposalResult>;
     /**
      * The frontier (vendor) roster you can evaluate against. With `task`, each is
      * annotated `benchmarked` + the roster is vision-filtered for document tasks.
@@ -564,6 +643,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;
@@ -630,7 +712,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "1.4.0";
+declare const VERSION = "2.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python
@@ -722,4 +804,4 @@ declare class EndpointNotReadyError extends APIStatusError {
     constructor(message: string, init: APIStatusErrorInit);
 }
 
-export { APIConnectionError, APIStatusError, APITimeoutError, Audio, type AudioInput, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, Embeddings, type EmbeddingsFn, type EmbeddingsOptions, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, type ImageEditOptions, type ImageGenerateOptions, ImageGeneration, type ImageInput, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Speech, type SpeechOptions, Task, TaskMatch, TaskMatchCandidate, Transcription, type TranscriptionOptions, type Transport, Usage, VERSION, type ValidationErrorItem };
+export { APIConnectionError, APIStatusError, APITimeoutError, Audio, type AudioInput, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, ContractProposal, Embeddings, type EmbeddingsFn, type EmbeddingsOptions, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, type ImageEditOptions, type ImageGenerateOptions, ImageGeneration, type ImageInput, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, ProposalResult, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Speech, type SpeechOptions, Task, TaskMatch, TaskMatchCandidate, Transcription, type TranscriptionOptions, type Transport, Usage, VERSION, type ValidationErrorItem };

package/dist/index.mjs

@@ -172,7 +172,7 @@ function parseSSE(reader, opts) {
 }
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "2.1.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 {
 };
@@ -339,6 +369,11 @@ var EvalSet = class extends BaseModel {
   get scoringStrategy() {
     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;
+  }
 };
 function evalSetFromCreate(raw) {
   return new EvalSet(raw?.eval_set ?? {});
@@ -346,6 +381,60 @@ function evalSetFromCreate(raw) {
 function evalSetList(raw) {
   return (raw?.eval_sets ?? []).map((e) => new EvalSet(e));
 }
+var ContractProposal = class extends BaseModel {
+  get taskId() {
+    return this.raw.task_id ?? null;
+  }
+  get confidence() {
+    return this.raw.confidence ?? null;
+  }
+  get evidence() {
+    return this.raw.evidence ?? {};
+  }
+  get warning() {
+    return this.raw.warning ?? null;
+  }
+};
+var ProposalResult = class extends BaseModel {
+  get proposals() {
+    return (this.raw.proposals ?? []).map((p) => new ContractProposal(p));
+  }
+  get homogeneous() {
+    return Boolean(this.raw.homogeneous);
+  }
+  get split() {
+    return this.raw.split ?? null;
+  }
+  get conflict() {
+    return this.raw.conflict ?? null;
+  }
+  get closestTask() {
+    return this.raw.closest_task ?? null;
+  }
+  get intent() {
+    return this.raw.intent ?? 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. */
+  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. */
+  get boundTask() {
+    return this.isClean ? this.proposals[0].taskId : null;
+  }
+};
+function proposalResult(raw) {
+  return new ProposalResult(raw ?? {});
+}
 var EvalItemResult = class extends BaseModel {
   get idx() {
     return this.raw.idx ?? null;
@@ -583,10 +672,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 {
@@ -639,6 +732,7 @@ var Tasks = class {
 
 // src/resources/evals.ts
 var BASE2 = "/v1/eval-sets";
+var PROPOSE = "/v1/eval-sets/propose-contract";
 var RUNS = "/v1/eval-runs";
 var FRONTIER = "/v1/eval/frontier-models";
 var INLINE_MAX = 5 * 1024 * 1024;
@@ -682,14 +776,59 @@ 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 itemsJsonl(task, items, name) {
+function requireIntent(intent) {
+  const s = (intent ?? "").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.'
+    );
+  }
+  return s.slice(0, 500);
+}
+function itemsJsonl(task, items, intent, 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, name: name || `sdk eval set (${items.length} items)` }
+    data: { task_id: task, intent, name: name || `sdk eval set (${items.length} items)` }
+  };
+}
+function proposeMultipart(items, intent) {
+  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 }
   };
 }
+function bindError(result) {
+  const intent = result.intent ?? "";
+  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.`
+    );
+  }
+  if (result.split) {
+    const s = result.split;
+    return new ParetaError(
+      `the dataset looks MIXED \u2014 ${s.validated_n}/${s.total_n} items fit '${s.closest_task}', the rest a different shape. Split the set or pass a task.`
+    );
+  }
+  const props = result.proposals;
+  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.`
+    );
+  }
+  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 }).`
+  );
+}
 function mergeCandidates(models, frontierIds) {
   const cands = [...models ?? [], ...frontierIds ?? []];
   if (cands.length === 0) throw new ParetaError("models is required (the open candidates to evaluate)");
@@ -710,10 +849,30 @@ var EvalSets = class {
     this.client = client;
   }
   client;
-  create(params) {
-    const { files, data } = itemsJsonl(params.task, params.items, params.name);
+  /**
+   * 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.
+   */
+  async create(params) {
+    const intent = requireIntent(params.intent);
+    let task = params.task;
+    if (task == null) {
+      const proposal = await this.proposeContract(params.items, intent);
+      task = proposal.boundTask ?? void 0;
+      if (task == null) throw bindError(proposal);
+    }
+    const { files, data } = itemsJsonl(task, params.items, intent, 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
+   * `Evals` as `proposeContract`; kept here so `sets.create` can reach it. */
+  proposeContract(items, intent) {
+    const { files, data } = proposeMultipart(items, requireIntent(intent));
+    return this.client.request("POST", PROPOSE, { files, data, cast: proposalResult });
+  }
   list() {
     return this.client.request("GET", BASE2, { cast: evalSetList });
   }
@@ -781,10 +940,15 @@ var EvalRuns = class {
   async create(params) {
     let evalSet = params.evalSet;
     if (evalSet == null) {
-      if (!(params.task && params.items)) {
-        throw new ParetaError("pass evalSet: <id>, or task + items to create one");
+      if (!params.items) {
+        throw new ParetaError("pass evalSet: <id>, or items (+ intent) to create one");
       }
-      evalSet = (await this.sets.create({ task: params.task, items: params.items, name: params.name })).id ?? void 0;
+      evalSet = (await this.sets.create({
+        items: params.items,
+        intent: params.intent,
+        task: params.task,
+        name: params.name
+      })).id ?? void 0;
     }
     const frontierIds = await this.frontierIds(params.frontier, evalSet, params.task);
     const candidateModelIds = mergeCandidates(params.models, frontierIds);
@@ -824,6 +988,15 @@ var Evals = class {
     this.client = client;
   }
   client;
+  /**
+   * Which grading contract fits your data under your stated `intent`? 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.
+   */
+  proposeContract(params) {
+    return this.sets.proposeContract(params.items, params.intent);
+  }
   /**
    * The frontier (vendor) roster you can evaluate against. With `task`, each is
    * annotated `benchmarked` + the roster is vision-filtered for document tasks.
@@ -1169,6 +1342,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;
@@ -1235,6 +1409,6 @@ var Pareta = class _Pareta {
   }
 };
 
-export { APIConnectionError, APIStatusError, APITimeoutError, Audio, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, Choice, ConflictError, Embeddings, EndpointNotReadyError, EvalItemResult, EvalResult, EvalRun, EvalRuns, EvalSet, EvalSets, FrontierModel, ImageGeneration, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, PermissionDeniedError, RateLimitError, Rerank, RerankResult, Speech, Task, TaskMatch, TaskMatchCandidate, Transcription, Usage, VERSION };
+export { APIConnectionError, APIStatusError, APITimeoutError, Audio, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, Choice, ConflictError, ContractProposal, Embeddings, EndpointNotReadyError, EvalItemResult, EvalResult, EvalRun, EvalRuns, EvalSet, EvalSets, FrontierModel, ImageGeneration, Images, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, PermissionDeniedError, ProposalResult, RateLimitError, Rerank, RerankResult, Speech, Task, TaskMatch, TaskMatchCandidate, Transcription, Usage, VERSION };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map