palbase 0.0.0-stage → 0.2.0

package/types/internal/src/modules/ai.d.ts

@@ -0,0 +1,678 @@
+import { type Reply, type Transport } from '../transport.js';
+/**
+ * An embedding model.
+ */
+export type EmbeddingModel = {
+    /**
+     * Its vectors' length, and the most that can be asked for.
+     */
+    dimensions: number;
+    /**
+     * List price of a million input tokens, in US dollars.
+     */
+    input_usd_per_mtok: number;
+    /**
+     * The model, as provider:model.
+     */
+    model: string;
+    /**
+     * The role that names it: default, or empty.
+     */
+    role: string;
+};
+/**
+ * The vectors.
+ */
+export type Embeddings = {
+    /**
+     * What it cost at the list price, in billionths of a dollar.
+     */
+    cost_nano_usd: number;
+    /**
+     * The vectors' length.
+     */
+    dimensions: number;
+    /**
+     * Tokens read.
+     */
+    input_tokens: number;
+    /**
+     * The model.
+     */
+    model: string;
+    /**
+     * One vector per text, in order: little-endian float32, base64-encoded.
+     */
+    vectors: string[];
+};
+/**
+ * Texts to embed.
+ */
+export type EmbeddingsRequest = {
+    /**
+     * A shorter vector than the model's own (0 or absent: the model's).
+     */
+    dimensions?: number;
+    /**
+     * The texts (1,024 at most, none empty).
+     */
+    input: string[];
+    /**
+     * default, or a catalogue embedding model as provider:model.
+     */
+    model?: string;
+};
+export type ErrorResponse = {
+    /**
+     * Machine-readable error code (snake_case)
+     */
+    error: string;
+    /**
+     * Human-readable explanation
+     */
+    error_description: string;
+    /**
+     * Correlation ID
+     */
+    request_id: string;
+    /**
+     * Seconds to wait before retrying, when the refusal ends with time.
+     */
+    retry_after?: number;
+    /**
+     * HTTP status code
+     */
+    status: number;
+};
+/**
+ * A picture job.
+ */
+export type Image = {
+    /**
+     * When it started.
+     */
+    created_at: string;
+    error: ImageError;
+    /**
+     * When it and its pictures are forgotten.
+     */
+    expires_at: string;
+    /**
+     * Its pictures, once completed.
+     */
+    files: ImageFile[];
+    /**
+     * The job's id.
+     */
+    id: string;
+    /**
+     * The model.
+     */
+    model: string;
+    /**
+     * running, completed or failed.
+     */
+    status: "running" | "completed" | "failed";
+    usage: ImageUsage;
+};
+/**
+ * Why a job failed; null when it did not.
+ */
+export type ImageError = ({
+    /**
+     * Why, as a stable code.
+     */
+    code: string;
+    /**
+     * Why, in a sentence.
+     */
+    message: string;
+}) | null;
+/**
+ * A picture of a finished job.
+ */
+export type ImageFile = {
+    /**
+     * Its size.
+     */
+    bytes: number;
+    /**
+     * Its media type.
+     */
+    media_type: string;
+    /**
+     * Where to read it (GET).
+     */
+    path: string;
+    /**
+     * Its place in the job, from 0.
+     */
+    position: number;
+};
+/**
+ * A picture the caller sends.
+ */
+export type ImageInput = {
+    /**
+     * The picture's bytes, base64-encoded (20 MB at most).
+     */
+    data: string;
+    /**
+     * image/png, image/jpeg or image/webp (a mask is image/png with an alpha channel).
+     */
+    media_type: "image/png" | "image/jpeg" | "image/webp";
+};
+/**
+ * An image model.
+ */
+export type ImageModel = {
+    /**
+     * List price of a million reference picture tokens, in US dollars.
+     */
+    image_input_usd_per_mtok: number;
+    /**
+     * List price of a million picture tokens, in US dollars.
+     */
+    image_output_usd_per_mtok: number;
+    /**
+     * The model, as provider:model.
+     */
+    model: string;
+    /**
+     * The role that names it: default, strong, or empty.
+     */
+    role: string;
+    /**
+     * List price of a million prompt tokens, in US dollars.
+     */
+    text_input_usd_per_mtok: number;
+};
+/**
+ * A request for pictures.
+ */
+export type ImageRequest = {
+    /**
+     * auto, transparent or opaque; transparent needs png or webp.
+     */
+    background?: string;
+    /**
+     * How many pictures (1–4, default 1).
+     */
+    count?: number;
+    /**
+     * png (default), jpeg or webp.
+     */
+    format?: string;
+    mask?: ImageInput;
+    /**
+     * default (fast), strong (precise edits), or a catalogue image model as provider:model.
+     */
+    model?: string;
+    /**
+     * What to make.
+     */
+    prompt: string;
+    /**
+     * auto, low, medium, high, xhigh or max.
+     */
+    quality?: string;
+    /**
+     * Pictures to work from (4 at most, each 8 MiB at most and — with the mask — 24 MiB together, as PNG, JPEG or WebP): with them the job is an edit.
+     */
+    references?: ImageInput[];
+    /**
+     * auto, 1024x1024, 1536x1024, 1024x1536, or WIDTHxHEIGHT: sides multiples of 16, an aspect between 1:3 and 3:1, 655,360 to 8,294,400 pixels.
+     */
+    size?: string;
+};
+/**
+ * What a finished job cost; null until then.
+ */
+export type ImageUsage = ({
+    /**
+     * What it cost at the list price, in billionths of a dollar.
+     */
+    cost_nano_usd: number;
+    /**
+     * Reference picture tokens.
+     */
+    image_input_tokens: number;
+    /**
+     * Prompt tokens.
+     */
+    input_tokens: number;
+    /**
+     * Picture tokens.
+     */
+    output_tokens: number;
+}) | null;
+/**
+ * One turn of the conversation so far.
+ */
+export type Message = {
+    /**
+     * What was said.
+     */
+    content: string;
+    /**
+     * Who said it.
+     */
+    role: "user" | "assistant";
+};
+/**
+ * What a project may name.
+ */
+export type Models = {
+    /**
+     * Embedding models, with their list prices.
+     */
+    embeddings: EmbeddingModel[];
+    /**
+     * Image models, with their list prices.
+     */
+    images: ImageModel[];
+    /**
+     * The roles a text model is chosen by.
+     */
+    text: TextModel[];
+};
+/**
+ * A provider the project connected with its own key.
+ */
+export type Provider = {
+    /**
+     * The provider.
+     */
+    name: string;
+    /**
+     * The provider accepted the key when it was connected.
+     */
+    verified: boolean;
+};
+/**
+ * A provider key.
+ */
+export type ProviderKey = {
+    /**
+     * The provider's API key. It is never read back.
+     */
+    key: string;
+};
+/**
+ * The project's own provider keys.
+ */
+export type ProviderList = {
+    /**
+     * The project's providers.
+     */
+    providers: Provider[];
+};
+/**
+ * A response.
+ */
+export type Response = {
+    /**
+     * When it was admitted.
+     */
+    created_at: string;
+    error: ResponseError;
+    /**
+     * The response's id.
+     */
+    id: string;
+    /**
+     * The caller's own labels (16 at most, snake_case keys): returned with the response and its event.
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * The model that answered.
+     */
+    model: string;
+    /**
+     * The parsed document of an answer to a schema; null otherwise.
+     */
+    output: unknown;
+    /**
+     * Where it is: queued, in_progress, then completed, failed, canceled, timed_out or budget_exceeded.
+     */
+    status: string;
+    /**
+     * The answer as the model wrote it; for a schema's answer, the JSON document.
+     */
+    text: string | null;
+    usage: ResponseUsage;
+};
+/**
+ * Why a response did not complete; null when it did.
+ */
+export type ResponseError = ({
+    /**
+     * Why, as a stable code.
+     */
+    code: string;
+    /**
+     * Why, in a sentence.
+     */
+    message: string;
+}) | null;
+/**
+ * A background response ended.
+ */
+export type ResponseEvent = {
+    /**
+     * What it cost, in billionths of a dollar.
+     */
+    cost_nano_usd: number;
+    /**
+     * The caller's own labels (16 at most, snake_case keys): returned with the response and its event.
+     */
+    metadata: {
+        [key: string]: string;
+    };
+    /**
+     * The model that answered.
+     */
+    model: string;
+    /**
+     * The response.
+     */
+    response_id: string;
+    /**
+     * How it ended.
+     */
+    status: string;
+};
+/**
+ * A question for a model: input, or messages.
+ */
+export type ResponseRequest = {
+    /**
+     * Answer at once; the response's end is the event ai.response.completed or ai.response.failed.
+     */
+    background?: boolean;
+    /**
+     * The question (2 MB at most). Give this, or messages.
+     */
+    input?: string;
+    /**
+     * How the model should answer (256 KB at most).
+     */
+    instructions?: string;
+    /**
+     * The conversation so far instead of one question (500 turns at most); its last turn is the user's.
+     */
+    messages?: Message[];
+    /**
+     * The caller's own labels (16 at most, snake_case keys): returned with the response and its event.
+     */
+    metadata?: {
+        [key: string]: string;
+    };
+    /**
+     * A role — fast, default (the default), strong — or a catalogue model as provider:model. Name a role: when a provider retires a model, the role is bound to another and your code does not change.
+     */
+    model?: string;
+    /**
+     * A JSON Schema the answer must be a document of. Its keywords are the provider's strict subset: type, properties, required, additionalProperties, items, enum, description, title, minimum, maximum, minLength, maxLength, minItems, maxItems — no $ref, at most 12 levels and 512 properties; every property required (a nullable one may be null). One outside the subset is refused, naming where it is.
+     */
+    schema?: {
+        [key: string]: unknown;
+    };
+    /**
+     * The schema's name, as the model is told it (letters, digits, _ and -; default answer).
+     */
+    schema_name?: string;
+    /**
+     * Answer with the response's live view (text/event-stream).
+     */
+    stream?: boolean;
+};
+/**
+ * What a response used.
+ */
+export type ResponseUsage = {
+    /**
+     * Tokens read.
+     */
+    input_tokens: number;
+    /**
+     * Tokens written.
+     */
+    output_tokens: number;
+};
+/**
+ * A role a text model is chosen by.
+ */
+export type TextModel = {
+    /**
+     * What it is for.
+     */
+    description: string;
+    /**
+     * The role.
+     */
+    role: string;
+};
+/**
+ * A page of uses.
+ */
+export type UsagePage = {
+    /**
+     * The cursor of the next page; absent on the last.
+     */
+    next_cursor?: string;
+    /**
+     * Uses, newest first.
+     */
+    usage: Use[];
+};
+/**
+ * One use of a model.
+ */
+export type Use = {
+    /**
+     * Whose connection paid: platform, or project (the project's own key).
+     */
+    connection_owner: "platform" | "project" | "";
+    /**
+     * What it cost at the provider's list price, in billionths of a dollar.
+     */
+    cost_nano_usd: number;
+    /**
+     * When.
+     */
+    created_at: string;
+    /**
+     * The use's id.
+     */
+    id: string;
+    /**
+     * Reference picture tokens.
+     */
+    image_input_tokens: number;
+    /**
+     * Tokens read.
+     */
+    input_tokens: number;
+    /**
+     * Texts embedded, or pictures made.
+     */
+    items: number;
+    /**
+     * text, embedding or image.
+     */
+    kind: "text" | "embedding" | "image";
+    /**
+     * The model.
+     */
+    model: string;
+    /**
+     * Tokens written.
+     */
+    output_tokens: number;
+    /**
+     * The response, for a text use.
+     */
+    response_id: string | null;
+};
+/** The events this module sends the project's webhooks (x-palbase-events), by type: each one's payload, the event's data. */
+export interface Events {
+    /**
+     * ai.response.completed: a response started with background: true completed; read its answer by its id.
+     */
+    "ai.response.completed": ResponseEvent;
+    /**
+     * ai.response.failed: a response started with background: true ended without completing (failed, canceled, timed out, over its budget).
+     */
+    "ai.response.failed": ResponseEvent;
+}
+/** Palbase ai */
+export declare function client(t: Transport): {
+    /**
+     * Turn texts into vectors
+     *
+     * One vector per text, in the order of the input. Up to 1,024 texts per request — a longer list is several requests, and the SDK cuts it; the platform splits a request over the provider's own limits.
+     */
+    createEmbeddings(input: {
+        body: EmbeddingsRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Embeddings>>;
+    /**
+     * Make pictures
+     *
+     * Starts a picture job and answers at once: making a picture takes the provider minutes. With reference images it edits them; a mask marks the part of the first to change. Read the job by its id; its pictures are kept for a day — save what you keep in your storage.
+     */
+    createImage(input: {
+        headers: {
+            "Idempotency-Key": string;
+        };
+        body: ImageRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<202, Image>>;
+    /**
+     * Read a picture job
+     *
+     * The job: running, its pictures, or why it failed.
+     */
+    getImage(input: {
+        path: {
+            image_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Image>>;
+    /**
+     * Read a picture
+     *
+     * The bytes of one picture of a finished job, with its media type.
+     */
+    getImageFile(input: {
+        path: {
+            image_id: string; /** The picture's place in the job, from 0. */
+            position: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * What a project may name
+     *
+     * The roles a text model is chosen by, and the embedding and image models with their list prices.
+     */
+    listModels(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Models>>;
+    /**
+     * The project's own provider keys
+     *
+     * The providers the project connected with its own key. A key is never read back.
+     */
+    listProviders(input?: {
+        signal?: AbortSignal;
+    }): Promise<Reply<200, ProviderList>>;
+    /**
+     * Use the project's own provider key
+     *
+     * From now on every call that goes to this provider goes out with the project's own key and is billed by the provider to the project. The key is shown to the provider before it is kept: one the provider refuses is not kept.
+     */
+    connectProvider(input: {
+        path: {
+            provider: string;
+        };
+        body: ProviderKey; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Provider>>;
+    /**
+     * Stop using the project's own provider key
+     *
+     * The key is removed; calls to this provider go out with the platform's connection again.
+     */
+    disconnectProvider(input: {
+        path: {
+            provider: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<204, undefined>>;
+    /**
+     * Ask a model
+     *
+     * Admits a response: an answer to the input, as text or — with a schema — as a JSON document of that shape, validated before it is returned. With stream: true the answer is the response's live view (text/event-stream). With background: true it answers at once and the response's end is the event ai.response.completed (or ai.response.failed). Otherwise it answers at once with the response queued; read it by its id.
+     */
+    createResponse(input: {
+        headers: {
+            "Idempotency-Key": string;
+        };
+        body: ResponseRequest; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response> | Reply<202, Response>>;
+    /**
+     * Read a response
+     *
+     * A response as it stands: its status, and at its end its answer, its use and — when it did not complete — why.
+     */
+    getResponse(input: {
+        path: {
+            response_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * Stop a response
+     *
+     * Asks the model service to stop the response; it ends canceled, and what it used until then is recorded.
+     */
+    cancelResponse(input: {
+        path: {
+            response_id: string;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * Follow a response as it is produced
+     *
+     * The response's live view from a byte offset of its answer: every fragment as the model produces it, then the response at its end. A finished response answers its terminal at once.
+     */
+    followResponse(input: {
+        path: {
+            response_id: string;
+        };
+        query?: {
+            offset?: number;
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, Response>>;
+    /**
+     * What the project's use of models cost
+     *
+     * Every use, newest first: a response's tokens, an embeddings call, a picture job — with its cost at the provider's list price and whose connection paid. A use under the project's own key is billed by the provider, not by Palbase.
+     */
+    listUsage(input?: {
+        query?: {
+            limit?: number; /** The next_cursor of the previous page. */
+            cursor?: string; /** Only uses of this kind: text, embedding or image. */
+            kind?: "text" | "embedding" | "image";
+        }; /** Stops the call: the request in flight, a wait before a retry, a proof-of-work being solved. */
+        signal?: AbortSignal;
+    }): Promise<Reply<200, UsagePage>>;
+};
+export type Client = ReturnType<typeof client>;