pareta 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -142,6 +142,30 @@ declare class EvalRun extends BaseModel {
     get cost(): string;
     get results(): EvalResult[];
 }
+/** One row of `Rerank.results` — a document's position + calibrated score. */
+declare class RerankResult extends BaseModel {
+    /** Position of this document in YOUR request's documents array. */
+    get index(): number;
+    /** Calibrated P(relevant) in (0, 1) — thresholdable, not just ordinal. */
+    get relevanceScore(): number;
+}
+/** Result of `pa.rerank(...)`: `.results` ordered most-relevant-first;
+ * `.pairs` is the number of documents scored (the metered unit). */
+declare class Rerank extends BaseModel {
+    get results(): RerankResult[];
+    get model(): string | null;
+    get pairs(): number | null;
+    /** Map the ranked indices back onto the documents you sent — best first. */
+    topDocuments(documents: string[]): string[];
+}
+/** Result of `pa.embeddings(...)`: unit-normalized vectors in input order
+ * (cosine similarity is a plain dot product); `.promptTokens` is metered. */
+declare class Embeddings extends BaseModel {
+    get vectors(): number[][];
+    get model(): string | null;
+    get promptTokens(): number | null;
+    get length(): number;
+}
 
 /**
  * `client.chat.completions` — OpenAI-compatible chat completions.
@@ -366,6 +390,34 @@ declare class Auto {
     }): Promise<FrontierComparison>;
 }
 
+/**
+ * `pa.rerank(...)` + `pa.embeddings(...)` — the Retrieval capability lanes
+ * (the RAG stack: embeddings for recall, reranking for precision).
+ *
+ * Both are dedicated routes, not `chat.completions`:
+ *   POST /v1/rerank      {query, documents[], top_n?} -> ordered
+ *                        {index, relevance_score} rows (calibrated P(relevant))
+ *   POST /v1/embeddings  {input[], input_type?}       -> unit-normalized vectors
+ *
+ * Rerank is metered per document scored; embeddings per input token. You never
+ * pick a serving model — Pareta resolves the lane (`pareta-rerank-1` / `bge-1`),
+ * exactly as `model:"auto"` does for chat.
+ *
+ * Exposed as callable client fields (`pa.rerank(...)`) rather than resource
+ * objects — call-parity with the Python SDK, and neither lane has sub-methods.
+ */
+
+interface RerankOptions {
+    /** Truncate the response to the best N (all documents are still scored and metered). */
+    topN?: number;
+}
+type RerankFn = (query: string, documents: string[], opts?: RerankOptions) => Promise<Rerank>;
+interface EmbeddingsOptions {
+    /** `"query"` embeds a retrieval QUERY (asymmetric); default embeds documents raw. */
+    inputType?: "query" | "document";
+}
+type EmbeddingsFn = (input: string | string[], opts?: EmbeddingsOptions) => Promise<Embeddings>;
+
 /**
  * The `Pareta` client — one class (no sync/async split; JS is Promise-only).
  * A faithful port of the Python `_client.py` transport: header construction,
@@ -420,6 +472,10 @@ declare class Pareta implements Transport {
     readonly tasks: Tasks;
     readonly evals: Evals;
     readonly auto: Auto;
+    /** Document reranking (the Retrieval precision lane) — `pa.rerank(query, docs, {topN})`. */
+    readonly rerank: RerankFn;
+    /** Text embeddings (the Retrieval recall lane) — `pa.embeddings(input, {inputType})`. */
+    readonly embeddings: EmbeddingsFn;
     constructor(options?: ParetaOptions);
     /** Build from PARETA_API_KEY (+ optional PARETA_BASE_URL); explicit opts win. */
     static fromEnv(options?: ParetaOptions): Pareta;
@@ -443,7 +499,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python
@@ -535,4 +591,4 @@ declare class EndpointNotReadyError extends APIStatusError {
     constructor(message: string, init: APIStatusErrorInit);
 }
 
-export { APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, type SSEEvent, Task, TaskMatch, TaskMatchCandidate, type Transport, Usage, VERSION, type ValidationErrorItem };
+export { APIConnectionError, APIStatusError, APITimeoutError, 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, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Task, TaskMatch, TaskMatchCandidate, type Transport, Usage, VERSION, type ValidationErrorItem };

package/dist/index.d.ts

@@ -142,6 +142,30 @@ declare class EvalRun extends BaseModel {
     get cost(): string;
     get results(): EvalResult[];
 }
+/** One row of `Rerank.results` — a document's position + calibrated score. */
+declare class RerankResult extends BaseModel {
+    /** Position of this document in YOUR request's documents array. */
+    get index(): number;
+    /** Calibrated P(relevant) in (0, 1) — thresholdable, not just ordinal. */
+    get relevanceScore(): number;
+}
+/** Result of `pa.rerank(...)`: `.results` ordered most-relevant-first;
+ * `.pairs` is the number of documents scored (the metered unit). */
+declare class Rerank extends BaseModel {
+    get results(): RerankResult[];
+    get model(): string | null;
+    get pairs(): number | null;
+    /** Map the ranked indices back onto the documents you sent — best first. */
+    topDocuments(documents: string[]): string[];
+}
+/** Result of `pa.embeddings(...)`: unit-normalized vectors in input order
+ * (cosine similarity is a plain dot product); `.promptTokens` is metered. */
+declare class Embeddings extends BaseModel {
+    get vectors(): number[][];
+    get model(): string | null;
+    get promptTokens(): number | null;
+    get length(): number;
+}
 
 /**
  * `client.chat.completions` — OpenAI-compatible chat completions.
@@ -366,6 +390,34 @@ declare class Auto {
     }): Promise<FrontierComparison>;
 }
 
+/**
+ * `pa.rerank(...)` + `pa.embeddings(...)` — the Retrieval capability lanes
+ * (the RAG stack: embeddings for recall, reranking for precision).
+ *
+ * Both are dedicated routes, not `chat.completions`:
+ *   POST /v1/rerank      {query, documents[], top_n?} -> ordered
+ *                        {index, relevance_score} rows (calibrated P(relevant))
+ *   POST /v1/embeddings  {input[], input_type?}       -> unit-normalized vectors
+ *
+ * Rerank is metered per document scored; embeddings per input token. You never
+ * pick a serving model — Pareta resolves the lane (`pareta-rerank-1` / `bge-1`),
+ * exactly as `model:"auto"` does for chat.
+ *
+ * Exposed as callable client fields (`pa.rerank(...)`) rather than resource
+ * objects — call-parity with the Python SDK, and neither lane has sub-methods.
+ */
+
+interface RerankOptions {
+    /** Truncate the response to the best N (all documents are still scored and metered). */
+    topN?: number;
+}
+type RerankFn = (query: string, documents: string[], opts?: RerankOptions) => Promise<Rerank>;
+interface EmbeddingsOptions {
+    /** `"query"` embeds a retrieval QUERY (asymmetric); default embeds documents raw. */
+    inputType?: "query" | "document";
+}
+type EmbeddingsFn = (input: string | string[], opts?: EmbeddingsOptions) => Promise<Embeddings>;
+
 /**
  * The `Pareta` client — one class (no sync/async split; JS is Promise-only).
  * A faithful port of the Python `_client.py` transport: header construction,
@@ -420,6 +472,10 @@ declare class Pareta implements Transport {
     readonly tasks: Tasks;
     readonly evals: Evals;
     readonly auto: Auto;
+    /** Document reranking (the Retrieval precision lane) — `pa.rerank(query, docs, {topN})`. */
+    readonly rerank: RerankFn;
+    /** Text embeddings (the Retrieval recall lane) — `pa.embeddings(input, {inputType})`. */
+    readonly embeddings: EmbeddingsFn;
     constructor(options?: ParetaOptions);
     /** Build from PARETA_API_KEY (+ optional PARETA_BASE_URL); explicit opts win. */
     static fromEnv(options?: ParetaOptions): Pareta;
@@ -443,7 +499,7 @@ declare class Pareta implements Transport {
     stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
 }
 
-declare const VERSION = "1.0.0";
+declare const VERSION = "1.1.0";
 
 /**
  * Typed error hierarchy for the Pareta SDK — a faithful port of the Python
@@ -535,4 +591,4 @@ declare class EndpointNotReadyError extends APIStatusError {
     constructor(message: string, init: APIStatusErrorInit);
 }
 
-export { APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, type ChatCompletionCreateParams, type ChatMessage, Choice, ConflictError, EndpointNotReadyError, type ErrorDetail, EvalItemResult, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, type SSEEvent, Task, TaskMatch, TaskMatchCandidate, type Transport, Usage, VERSION, type ValidationErrorItem };
+export { APIConnectionError, APIStatusError, APITimeoutError, 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, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, Rerank, type RerankFn, type RerankOptions, RerankResult, type SSEEvent, Task, TaskMatch, TaskMatchCandidate, type Transport, Usage, VERSION, type ValidationErrorItem };

package/dist/index.mjs

@@ -172,7 +172,7 @@ function parseSSE(reader, opts) {
 }
 
 // src/version.ts
-var VERSION = "1.0.0";
+var VERSION = "1.1.0";
 
 // src/money.ts
 var MICRO_PER_CENT = 10000n;
@@ -443,6 +443,47 @@ var EvalRun = class extends BaseModel {
     return (this.raw.results ?? []).map((r) => new EvalResult(r));
   }
 };
+var RerankResult = class extends BaseModel {
+  /** Position of this document in YOUR request's documents array. */
+  get index() {
+    return Number(this.raw.index ?? -1);
+  }
+  /** Calibrated P(relevant) in (0, 1) — thresholdable, not just ordinal. */
+  get relevanceScore() {
+    return Number(this.raw.relevance_score ?? 0);
+  }
+};
+var Rerank = class extends BaseModel {
+  get results() {
+    return (this.raw.results ?? []).map((r) => new RerankResult(r));
+  }
+  get model() {
+    return this.raw.model ?? null;
+  }
+  get pairs() {
+    return this.raw.pairs ?? null;
+  }
+  /** Map the ranked indices back onto the documents you sent — best first. */
+  topDocuments(documents) {
+    return this.results.filter((r) => r.index >= 0 && r.index < documents.length).map((r) => documents[r.index]);
+  }
+};
+var Embeddings = class extends BaseModel {
+  get vectors() {
+    const rows = [...this.raw.data ?? []];
+    rows.sort((a, b) => Number(a.index ?? 0) - Number(b.index ?? 0));
+    return rows.map((r) => r.embedding ?? []);
+  }
+  get model() {
+    return this.raw.model ?? null;
+  }
+  get promptTokens() {
+    return this.raw.usage?.prompt_tokens ?? null;
+  }
+  get length() {
+    return (this.raw.data ?? []).length;
+  }
+};
 
 // src/resources/chat.ts
 var PATH = "/v1/chat/completions";
@@ -745,6 +786,39 @@ var Auto = class {
   }
 };
 
+// src/resources/retrieval.ts
+function makeRerank(client) {
+  return (query, documents, opts = {}) => {
+    if (!query || !query.trim()) throw new ParetaError("query is required");
+    if (!Array.isArray(documents) || documents.length === 0) {
+      throw new ParetaError("documents must be a non-empty array of strings");
+    }
+    const body = { query, documents };
+    if (opts.topN !== void 0) body.top_n = opts.topN;
+    return client.request("POST", "/v1/rerank", {
+      body,
+      cast: (raw) => new Rerank(raw)
+    });
+  };
+}
+function makeEmbeddings(client) {
+  return (input, opts = {}) => {
+    const texts = typeof input === "string" ? [input] : input;
+    if (!Array.isArray(texts) || texts.length === 0 || texts.some((t) => typeof t !== "string" || !t.trim())) {
+      throw new ParetaError("input must be a non-empty string or array of non-empty strings");
+    }
+    if (opts.inputType !== void 0 && opts.inputType !== "query" && opts.inputType !== "document") {
+      throw new ParetaError('inputType must be "query" or "document"');
+    }
+    const body = { input: texts };
+    if (opts.inputType !== void 0) body.input_type = opts.inputType;
+    return client.request("POST", "/v1/embeddings", {
+      body,
+      cast: (raw) => new Embeddings(raw)
+    });
+  };
+}
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.pareta.ai";
 function randomKey() {
@@ -772,6 +846,10 @@ var Pareta = class _Pareta {
   tasks;
   evals;
   auto;
+  /** Document reranking (the Retrieval precision lane) — `pa.rerank(query, docs, {topN})`. */
+  rerank;
+  /** Text embeddings (the Retrieval recall lane) — `pa.embeddings(input, {inputType})`. */
+  embeddings;
   constructor(options = {}) {
     if (!options.apiKey) {
       throw new ParetaError(
@@ -792,6 +870,8 @@ var Pareta = class _Pareta {
     this.tasks = new Tasks(this);
     this.evals = new Evals(this);
     this.auto = new Auto(this);
+    this.rerank = makeRerank(this);
+    this.embeddings = makeEmbeddings(this);
   }
   /** Build from PARETA_API_KEY (+ optional PARETA_BASE_URL); explicit opts win. */
   static fromEnv(options = {}) {
@@ -972,6 +1052,6 @@ var Pareta = class _Pareta {
   }
 };
 
-export { APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, Choice, ConflictError, EndpointNotReadyError, EvalItemResult, EvalResult, EvalRun, EvalRuns, EvalSet, EvalSets, FrontierModel, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, PermissionDeniedError, RateLimitError, Task, TaskMatch, TaskMatchCandidate, Usage, VERSION };
+export { APIConnectionError, APIStatusError, APITimeoutError, AuthenticationError, BadRequestError, BaseModel, ChatCompletion, ChatCompletionChunk, Choice, ConflictError, Embeddings, EndpointNotReadyError, EvalItemResult, EvalResult, EvalRun, EvalRuns, EvalSet, EvalSets, FrontierModel, InsufficientCreditsError, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, PermissionDeniedError, RateLimitError, Rerank, RerankResult, Task, TaskMatch, TaskMatchCandidate, Usage, VERSION };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map