pareta 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,550 @@
+/** One named SSE event: the event type + its parsed (or raw-string) data. */
+interface SSEEvent {
+    event: string;
+    data: unknown;
+}
+
+/**
+ * Response objects — hand-written wrappers over the raw server JSON, a faithful
+ * port of the Python `_models.py`. Each keeps the raw payload on `.raw` and
+ * exposes it via `.toDict()`, so nothing the API returns is lost behind the
+ * typed layer.
+ *
+ * Alias / D3 boundary (a BACKEND contract, the SDK adds no alias logic):
+ * `Endpoint.model`, `EvalResult.modelId`, leaderboard names and
+ * `run.candidateModels` are per-task PUBLIC aliases — real open-weights ids
+ * never cross. Frontier (vendor) ids are in the clear.
+ */
+type Raw = Record<string, any>;
+/** Base: holds the raw payload, dict-style escape hatches. */
+declare class BaseModel {
+    /** The raw server JSON, untouched. */
+    readonly raw: Raw;
+    constructor(raw?: Raw);
+    /** The raw server JSON (alias of `.raw`, mirrors Python `.to_dict()`). */
+    toDict(): Raw;
+    /** Read an arbitrary key off the raw payload. */
+    get<T = unknown>(key: string, fallback?: T): T;
+}
+declare class Usage extends BaseModel {
+    get promptTokens(): number | null;
+    get completionTokens(): number | null;
+    get totalTokens(): number | null;
+}
+declare class Message extends BaseModel {
+    get role(): string | null;
+    get content(): string | null;
+}
+declare class Choice extends BaseModel {
+    get index(): number | null;
+    get finishReason(): string | null;
+    get message(): Message;
+    /** Streaming chunks carry `delta` instead of `message`. */
+    get delta(): Message;
+}
+declare class ChatCompletion extends BaseModel {
+    get id(): string | null;
+    get model(): string | null;
+    get created(): number | null;
+    get choices(): Choice[];
+    get usage(): Usage;
+}
+/** One SSE delta. `chunk.choices[0].delta.content` is the incremental text. */
+declare class ChatCompletionChunk extends ChatCompletion {
+}
+declare class Model extends BaseModel {
+    get id(): string | null;
+    get ownedBy(): string | null;
+    get created(): number | null;
+}
+/** The OpenAI-compatible `/v1/models` list. Exposes `.data` and is iterable. */
+declare class ModelList extends BaseModel implements Iterable<Model> {
+    get data(): Model[];
+    get length(): number;
+    [Symbol.iterator](): Iterator<Model>;
+}
+/**
+ * A deployed endpoint. `id` (== name) is what you pass to
+ * `chat.completions.create({ model })`. `model` is the per-task public alias.
+ */
+declare class Endpoint extends BaseModel {
+    get id(): string | null;
+    get name(): string | null;
+    get model(): string | null;
+    get status(): string | null;
+    get task(): string | null;
+    get url(): string | null;
+    get isLive(): boolean;
+}
+declare class Task extends BaseModel {
+    get id(): string | null;
+    get defaultScorer(): string | null;
+    get hasBlobInput(): boolean;
+}
+declare class TaskMatchCandidate extends BaseModel {
+    get taskId(): string | null;
+    get score(): number | null;
+    get confidence(): string | null;
+}
+/** Result of `tasks.match()`: `.matched`, `.chosen` (best or null), `.candidates`. */
+declare class TaskMatch extends BaseModel {
+    get query(): string | null;
+    get matched(): boolean;
+    get chosen(): TaskMatchCandidate | null;
+    get candidates(): TaskMatchCandidate[];
+    get ambiguous(): boolean;
+    get matcher(): string | null;
+}
+declare class EvalSet extends BaseModel {
+    get id(): string | null;
+    get taskId(): string | null;
+    get name(): string | null;
+    get itemCount(): number | null;
+    get scoringStrategy(): string | null;
+}
+/**
+ * One model's aggregate on an eval run. `modelId` is the per-task public alias;
+ * `kind` ('open' | 'frontier') is populated by the Slice-4 result schema.
+ */
+declare class EvalResult extends BaseModel {
+    get modelId(): string | null;
+    get kind(): string | null;
+    get qualityMean(): number | null;
+    get qualityCiLow(): number | null;
+    get qualityCiHigh(): number | null;
+    get meanCostMicroUsd(): number | null;
+    get nSucceeded(): number | null;
+    get errorCount(): number | null;
+}
+declare class LeaderboardEntry extends BaseModel {
+    get name(): string | null;
+    get kind(): string | null;
+    get quality(): number | null;
+    get costPerRequestMicroUsd(): number | null;
+    get contextK(): number | null;
+    get runMode(): string | null;
+}
+/** Models ranked for a task. `recommended` is the deployable pick; `frontier` the baseline. */
+declare class Leaderboard extends BaseModel {
+    get taskId(): string | null;
+    get metric(): string | null;
+    get costUnit(): string | null;
+    get recommended(): string | null;
+    get models(): LeaderboardEntry[];
+    get frontier(): LeaderboardEntry | null;
+}
+/** A vendor frontier model you can evaluate against (from the eval pool). */
+declare class FrontierModel extends BaseModel {
+    get id(): string | null;
+    get vendor(): string | null;
+    get vision(): boolean;
+    /** Only meaningful when a task was given: it's on that task's leaderboard. */
+    get benchmarked(): boolean;
+}
+/**
+ * Wraps the GET /v1/eval-runs/{id} envelope `{"run": {...}, "results": [...]}`.
+ * `cost` is the billed total as a floored fixed-2dp dollar string (§6);
+ * `costMicroUsd` is the raw integer.
+ */
+declare class EvalRun extends BaseModel {
+    private get run();
+    get id(): string | null;
+    get evalSetId(): string | null;
+    get status(): string | null;
+    get isTerminal(): boolean;
+    get candidateModels(): string[];
+    get errorDetail(): string | null;
+    /** Raw billed micro-USD integer. */
+    get costMicroUsd(): number;
+    /** Billed total, floored to whole cents, as a fixed-2dp dollar string ("1.23"). */
+    get cost(): string;
+    get results(): EvalResult[];
+}
+
+/**
+ * `client.chat.completions` — OpenAI-compatible chat completions.
+ *
+ * `model` is an endpoint id from `endpoints.deploy(...)` (or any model id the
+ * caller's org can reach). The call is metered: a successful completion debits
+ * the org's balance; a zero balance raises `InsufficientCreditsError` (402).
+ */
+
+/** An OpenAI-style chat message. `content` is a string or content-block array. */
+interface ChatMessage {
+    role: string;
+    content: string | Array<Record<string, unknown>>;
+    [key: string]: unknown;
+}
+/** Params for `chat.completions.create`. Extra OpenAI params pass through. */
+interface ChatCompletionCreateParams {
+    /** An endpoint id from `endpoints.deploy(...)`. */
+    model: string;
+    messages: ChatMessage[];
+    stream?: boolean;
+    /** temperature, max_tokens, top_p, … — forwarded verbatim. */
+    [key: string]: unknown;
+}
+declare class Completions {
+    private readonly client;
+    constructor(client: Transport);
+    /**
+     * Create a chat completion.
+     *
+     * `stream: false` (default) → `Promise<ChatCompletion>`.
+     * `stream: true`  → `AsyncIterable<ChatCompletionChunk>`
+     *   (`chunk.choices[0].delta.content` is the incremental text).
+     */
+    create(params: ChatCompletionCreateParams & {
+        stream: true;
+    }): AsyncIterable<ChatCompletionChunk>;
+    create(params: ChatCompletionCreateParams & {
+        stream?: false;
+    }): Promise<ChatCompletion>;
+}
+declare class Chat {
+    readonly completions: Completions;
+    constructor(client: Transport);
+}
+
+/**
+ * `client.models` — list the deployed models (endpoints) your org can call.
+ *
+ * OpenAI-compatible: only deployed, url-bearing endpoints appear. Each
+ * `Model.id` is an endpoint id usable as `chat.completions.create({ model })`.
+ */
+
+declare class Models {
+    private readonly client;
+    constructor(client: Transport);
+    list(): Promise<ModelList>;
+}
+
+/**
+ * `client.endpoints` — deploy, operate, and measure deployed endpoints.
+ *
+ * `deploy({ task, model })` is ergonomic: Pareta picks the GPU/serving config
+ * (you never pass hardware) and `model` defaults to the task's recommended pick.
+ * The backend resolver behind POST /v1/endpoints evolved with the discovery
+ * work — verify the deploy body against staging when wiring real deploys.
+ */
+
+/** Params for `endpoints.deploy`. Extra keys pass through to the deploy body. */
+interface DeployParams {
+    /** The task id to deploy a model for. */
+    task: string;
+    /** Model alias to deploy; defaults to "recommended" (the task's top pick). */
+    model?: string;
+    /** Optional endpoint name. */
+    name?: string;
+    /** If true, block through the deploy and resolve the live Endpoint. */
+    wait?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * `endpoints.metrics(id).performance()` etc. Each returns the raw metric JSON
+ * (shapes vary by dimension; typed models arrive with the OpenAPI generation).
+ */
+declare class EndpointMetrics {
+    private readonly client;
+    private readonly id;
+    constructor(client: Transport, id: string);
+    performance(params?: Record<string, unknown>): Promise<unknown>;
+    uptime(params?: Record<string, unknown>): Promise<unknown>;
+    cost(params?: Record<string, unknown>): Promise<unknown>;
+    quality(params?: Record<string, unknown>): Promise<unknown>;
+    activity(params?: Record<string, unknown>): Promise<unknown>;
+}
+declare class Endpoints {
+    private readonly client;
+    constructor(client: Transport);
+    /**
+     * Deploy a model for a task. `wait: false` (default) → an `AsyncIterable` of
+     * progress events (`{event, data}`); the terminal event is `complete`
+     * (`data.endpoint`) or `error`. `wait: true` → resolves the live `Endpoint`
+     * (throws `ParetaError` on a deploy `error` event).
+     */
+    deploy(params: DeployParams & {
+        wait: true;
+    }): Promise<Endpoint>;
+    deploy(params: DeployParams & {
+        wait?: false;
+    }): AsyncIterable<SSEEvent>;
+    private waitForDeploy;
+    list(): Promise<Endpoint[]>;
+    retrieve(endpointId: string): Promise<Endpoint>;
+    start(endpointId: string): Promise<unknown>;
+    stop(endpointId: string): Promise<unknown>;
+    delete(endpointId: string): Promise<void>;
+    metrics(endpointId: string): EndpointMetrics;
+}
+
+/**
+ * `client.tasks` — browse the benchmark catalog + match free-text intent, and
+ * the per-task discovery surface (leaderboard / recommended).
+ *
+ * Unlike the Python SDK (where `leaderboard`/`recommended` exist only on the
+ * sync client), these are present uniformly here — JS has one client.
+ */
+
+declare class Tasks {
+    private readonly client;
+    constructor(client: Transport);
+    list(): Promise<Task[]>;
+    retrieve(taskId: string, opts?: {
+        examplesN?: number;
+    }): Promise<Task>;
+    /** Free-text intent → ranked candidate tasks (the Step-0 backend matcher). */
+    match(query: string, opts?: {
+        topK?: number;
+    }): Promise<TaskMatch>;
+    /** Models ranked by quality/cost for a task (+ recommended + frontier baseline). */
+    leaderboard(taskId: string): Promise<Leaderboard>;
+    /** The task's recommended deployable model — what deploy(model:"recommended") resolves to. */
+    recommended(taskId: string): Promise<string | null>;
+}
+
+/**
+ * `client.evals` — eval sets + runs (bring-your-own-data evaluation).
+ *
+ *   const set = await pa.evals.sets.create({ task, items: [...] });
+ *   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 })
+ *
+ * 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
+ * list of ids, or the "all"/"benchmarked"/"none" roster keywords (resolved via
+ * `frontierModels()`).
+ */
+
+/** "all" | "benchmarked" | "none" | an explicit list of frontier ids. */
+type FrontierSpec = "all" | "benchmarked" | "none" | string[] | null;
+/** A document for `uploadDocument`: a filesystem path (Node), Blob, or bytes. */
+type FileInput = string | Blob | ArrayBuffer | Uint8Array;
+declare class EvalSets {
+    private readonly client;
+    constructor(client: Transport);
+    create(params: {
+        task: string;
+        items: Array<Record<string, unknown>>;
+        name?: string;
+    }): Promise<EvalSet>;
+    list(): Promise<EvalSet[]>;
+    retrieve(evalSetId: string): Promise<EvalSet>;
+    delete(evalSetId: string): Promise<void>;
+    /**
+     * Attach a binary doc (PDF/image) to one row's blob field. Collapses the
+     * 3-call signed-URL flow (or the inline path for small files) into one call.
+     * `idx` is the 0-based row, `fieldName` the blob input field.
+     */
+    uploadDocument(evalSetId: string, file: FileInput, opts: {
+        idx: number;
+        fieldName: string;
+        mime?: string;
+    }): Promise<unknown>;
+}
+interface EvalRunCreateParams {
+    evalSet?: string;
+    task?: string;
+    items?: Array<Record<string, unknown>>;
+    models: string[];
+    frontier?: FrontierSpec;
+    name?: string;
+    wait?: boolean;
+    pollInterval?: number;
+    timeout?: number;
+}
+declare class EvalRuns {
+    private readonly client;
+    private readonly sets;
+    constructor(client: Transport, sets: EvalSets);
+    private frontierIds;
+    create(params: EvalRunCreateParams): Promise<EvalRun>;
+    retrieve(runId: string): Promise<EvalRun>;
+    wait(runId: string, opts?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): Promise<EvalRun>;
+}
+declare class Evals {
+    readonly sets: EvalSets;
+    readonly runs: EvalRuns;
+    constructor(client: Transport);
+    private readonly client;
+    /**
+     * The frontier (vendor) roster you can evaluate against. With `task`, each is
+     * annotated `benchmarked` + the roster is vision-filtered for document tasks.
+     */
+    frontierModels(task?: string): Promise<FrontierModel[]>;
+}
+
+/**
+ * The `Pareta` client — one class (no sync/async split; JS is Promise-only).
+ * A faithful port of the Python `_client.py` transport: header construction,
+ * the retry policy, error mapping, and the `started`-flag streaming rule.
+ */
+
+type FetchFn = typeof globalThis.fetch;
+/** A multipart file part (used by eval-set + blob uploads). */
+interface FilePart {
+    filename: string;
+    content: Blob | ArrayBuffer | ArrayBufferView | string;
+    contentType?: string;
+}
+interface RequestOptions {
+    body?: unknown;
+    params?: Record<string, unknown> | undefined;
+    files?: Record<string, FilePart>;
+    data?: Record<string, string>;
+    cast?: (raw: unknown) => unknown;
+}
+interface StreamOptions {
+    body?: unknown;
+    params?: Record<string, unknown> | undefined;
+    cast?: (raw: unknown) => unknown;
+    events?: boolean;
+}
+/** What resource namespaces depend on (lets them avoid importing the class). */
+interface Transport {
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
+}
+interface ParetaOptions {
+    /** `pareta_sk_` secret key. Falls back to PARETA_API_KEY via `fromEnv`. */
+    apiKey?: string;
+    /** API base URL. Default https://api.pareta.ai (trailing slashes stripped). */
+    baseURL?: string;
+    /** Overall per-request timeout in ms. Default 60000. */
+    timeout?: number;
+    /** Max retries for transient failures. Default 2. */
+    maxRetries?: number;
+    /** Injected fetch implementation (for tests / Node-without-global-fetch). */
+    fetch?: FetchFn;
+}
+declare class Pareta implements Transport {
+    readonly apiKey: string;
+    readonly baseURL: string;
+    readonly timeout: number;
+    readonly maxRetries: number;
+    private readonly fetchImpl;
+    readonly chat: Chat;
+    readonly models: Models;
+    readonly endpoints: Endpoints;
+    readonly tasks: Tasks;
+    readonly evals: Evals;
+    constructor(options?: ParetaOptions);
+    /** Build from PARETA_API_KEY (+ optional PARETA_BASE_URL); explicit opts win. */
+    static fromEnv(options?: ParetaOptions): Pareta;
+    private headers;
+    private shouldRetry;
+    /** Seconds to wait before retry `attempt` (0-indexed). Overridable in tests. */
+    protected _backoff(attempt: number, retryAfter: number | null): number;
+    /** Sleep `seconds`. Overridable in tests to skip real waits. */
+    protected _sleep(seconds: number): Promise<void>;
+    private retryAfterSeconds;
+    private buildURL;
+    private buildFormData;
+    private wrapFetchError;
+    private parseError;
+    request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
+    /**
+     * Yield parsed SSE objects. Retries ONLY the initial connect/handshake — once
+     * bytes are flowing a mid-stream drop raises (re-issuing would re-run a
+     * metered generation / re-trigger a deploy). `events:true` → `{event,data}`.
+     */
+    stream<T = unknown>(method: string, path: string, opts?: StreamOptions): AsyncGenerator<T>;
+}
+
+declare const VERSION = "0.1.0";
+
+/**
+ * Typed error hierarchy for the Pareta SDK — a faithful port of the Python
+ * `_exceptions.py`. The backend is FastAPI, so error bodies are
+ * `{"detail": "<message>"}` with a standard HTTP status. We map status → a
+ * specific class so callers can `catch (e) { if (e instanceof
+ * InsufficientCreditsError) … }` instead of sniffing status codes.
+ *
+ * Status → exception mapping:
+ *   400 → BadRequestError
+ *   401 → AuthenticationError      ("invalid API key")
+ *   402 → InsufficientCreditsError ("organization is out of credit…")
+ *   403 → PermissionDeniedError
+ *   404 → NotFoundError
+ *   409 → ConflictError            (seed/legacy endpoint not deployed)
+ *   422 → BadRequestError          (FastAPI validation; `detail` is an array)
+ *   429 → RateLimitError
+ *   503 → EndpointNotReadyError    (stopped / cold / provider down)
+ *   other 5xx → APIStatusError
+ */
+/** A single FastAPI validation error item (422 `detail` is an array of these). */
+interface ValidationErrorItem {
+    loc?: (string | number)[];
+    msg?: string;
+    type?: string;
+}
+/** For 422 the server's `detail` is an ARRAY; for every other status a string. */
+type ErrorDetail = string | ValidationErrorItem[] | null | undefined;
+/** Base class for every error raised by the SDK. */
+declare class ParetaError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request never reached the server (DNS, TCP, TLS, network). */
+declare class APIConnectionError extends ParetaError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The request timed out before a response was received. */
+declare class APITimeoutError extends APIConnectionError {
+    constructor(message?: string, options?: {
+        cause?: unknown;
+    });
+}
+interface APIStatusErrorInit {
+    status: number;
+    detail?: ErrorDetail;
+    requestId?: string | null;
+    response?: Response;
+}
+/** The server returned a non-2xx status. */
+declare class APIStatusError extends ParetaError {
+    /** The HTTP status code. */
+    readonly status: number;
+    /** The server's `detail` (string, or an array of validation items for 422). */
+    readonly detail: ErrorDetail;
+    /** Value of the `x-request-id` response header, if present. */
+    readonly requestId: string | null;
+    /** The underlying `Response` (for advanced use). */
+    readonly response?: Response;
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class BadRequestError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class AuthenticationError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class PermissionDeniedError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class NotFoundError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class ConflictError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+/** The org is out of credit. Top up in the dashboard (billing is browser-only). */
+declare class InsufficientCreditsError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+declare class RateLimitError extends APIStatusError {
+    constructor(message: string, init: APIStatusErrorInit);
+}
+/** The target endpoint isn't serving yet (stopped, cold-starting, or provider down). */
+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, type DeployParams, Endpoint, EndpointMetrics, EndpointNotReadyError, type ErrorDetail, EvalResult, EvalRun, type EvalRunCreateParams, EvalRuns, EvalSet, EvalSets, type FileInput, type FilePart, FrontierModel, type FrontierSpec, InsufficientCreditsError, Leaderboard, LeaderboardEntry, Message, Model, ModelList, NotFoundError, Pareta, ParetaError, type ParetaOptions, PermissionDeniedError, RateLimitError, type SSEEvent, Task, TaskMatch, TaskMatchCandidate, type Transport, Usage, VERSION, type ValidationErrorItem };