/** * The project's AI gateway at `/ai/v1`: the models the project serves, a chat reply whole or as * it is written, and embeddings. The wire is OpenAI's, so a request is what an OpenAI client * would send, with the project's own model names. * * Every call sends the signed-in person's token, which is how a browser app calls a model: the * gateway takes it only once the project has a hard budget for itself and one for every user, and * it never takes the app key alone. A server sends the server key, or a gateway key (`psy_…`) set * as `Authorization` in `global.headers`. * * A refusal comes back as `error`, with the gateway's own sentence, its `code` * (`budget_exceeded`, `model_not_found`, ...) and the HTTP status. */ import { type Transport } from './http.js'; export declare class AiError extends Error { /** The HTTP status, or 0 when nothing answered (or the stream broke after it began). */ readonly status: number; /** The gateway's code: `budget_exceeded`, `model_not_found`, `rate_limit_exceeded`, ... */ readonly code: string | undefined; /** The error's kind on the OpenAI wire: `insufficient_quota`, `permission_error`, ... */ readonly type: string | undefined; constructor(message: string, status: number, code?: string, type?: string); } export type AiResult = { data: T; error: null; } | { data: null; error: AiError; }; /** One part of a message's content: text, or an image by URL (a `data:` URL included). */ export type AiContentPart = { type: 'text'; text: string; } | { type: 'image_url'; image_url: { url: string; detail?: 'auto' | 'low' | 'high'; }; }; export interface AiMessage { role: 'system' | 'developer' | 'user' | 'assistant' | 'tool'; content: string | AiContentPart[] | null; name?: string; tool_calls?: AiToolCall[]; tool_call_id?: string; } export interface AiToolCall { id: string; type: 'function'; function: { name: string; arguments: string; }; } export interface AiChatRequest { model: string; messages: AiMessage[]; max_tokens?: number; max_completion_tokens?: number; temperature?: number; top_p?: number; stop?: string | string[]; tools?: unknown[]; tool_choice?: unknown; response_format?: unknown; user?: string; /** Anything else the OpenAI wire takes, passed through as written. */ [field: string]: unknown; } export interface AiUsage { prompt_tokens: number; completion_tokens: number; total_tokens: number; [field: string]: unknown; } export interface AiChatCompletion { id: string; object: 'chat.completion'; created: number; model: string; choices: { index: number; message: AiMessage; finish_reason: string | null; }[]; usage?: AiUsage; } export interface AiChatChunk { id: string; object: 'chat.completion.chunk'; created: number; model: string; choices: { index: number; delta: Partial; finish_reason: string | null; }[]; /** On the last chunk, when the gateway reports it. */ usage?: AiUsage | null; } export interface AiModel { id: string; object: 'model'; created?: number; owned_by?: string; [field: string]: unknown; } export interface AiEmbedRequest { model: string; input: string | string[]; dimensions?: number; encoding_format?: 'float' | 'base64'; [field: string]: unknown; } export interface AiEmbeddings { object: 'list'; data: { object: 'embedding'; index: number; embedding: number[] | string; }[]; model: string; usage?: { prompt_tokens: number; total_tokens: number; }; } export interface AiCallOptions { signal?: AbortSignal; } export declare class AiClient { /** @internal */ readonly url: string; private readonly transport; constructor( /** @internal */ url: string, transport: Transport); private send; private json; /** The models this project serves, by the names it serves them under. */ models(options?: AiCallOptions): Promise>; /** One reply, whole. */ chat(request: AiChatRequest, options?: AiCallOptions): Promise>; /** * One reply as it is written: `data` is read with `for await`, a chunk at a time, and the * last chunk carries the usage. A refusal before the reply begins (a budget, a model the * project does not serve) is `error`; a failure after it began is thrown by the loop. */ stream(request: AiChatRequest, options?: AiCallOptions): Promise>>; /** Vectors for one input or several, in the order given. */ embed(request: AiEmbedRequest, options?: AiCallOptions): Promise>; }