@tarkahq/sdk 0.0.0-stage → 0.3.0

package/dist/esm/resources/inference.js

@@ -0,0 +1,437 @@
+import { required, requireText, TarkaError } from "../errors.js";
+function chatRequest(input, stream) {
+    requireText(input?.model, "model");
+    const { prompt, system, messages, ...settings } = input;
+    if (prompt !== undefined) {
+        if (typeof prompt !== "string" ||
+            messages !== undefined ||
+            (system !== undefined && typeof system !== "string")) {
+            throw new TypeError("Provide a text prompt with an optional system instruction, or messages");
+        }
+        return {
+            ...settings,
+            stream,
+            messages: [
+                ...(system === undefined ? [] : [{ role: "system", content: system }]),
+                { role: "user", content: prompt },
+            ],
+        };
+    }
+    if (!Array.isArray(messages) || !messages.length || system !== undefined) {
+        throw new TypeError("Provide a prompt or a non-empty messages array");
+    }
+    for (const message of messages)
+        requireText(message.role, "message.role");
+    return { ...settings, stream, messages };
+}
+/** Inference model discovery. Access through `client.models`. */
+export class Models {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * List the models visible to your inference credential.
+     *
+     * @returns Model records directly as an array.
+     * @example
+     * const models = await client.models.list();
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async list(options) {
+        return (await this.#rpc.listModels(options)).data;
+    }
+    /**
+     * Retrieve one inference model.
+     *
+     * @param id - Model identifier or alias returned by `models.list()`.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        requireText(id, "model id");
+        return this.#rpc.retrieveModel({ model: id }, options);
+    }
+}
+/** Control plane model catalog, including provisioning information. Access through `client.catalog`. */
+export class Catalog {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * List catalog models, optionally filtered by modality.
+     *
+     * @param filter - Optional modality filter. Pass `undefined` when supplying only request settings.
+     * @returns Catalog records directly as an array; inference discovery is available through `client.models`.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async list(filter = {}, options) {
+        return (await this.#rpc.listModels(filter, options)).models;
+    }
+}
+/** OpenAI-compatible JSON chat. Access through `client.chat.json` when you need fields outside the typed chat API. */
+export class JsonChat {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Create a chat completion from an OpenAI-compatible JSON body.
+     *
+     * @param body - Ordinary JSON with OpenAI field names, such as `max_tokens`. The SDK sets `stream: false`.
+     * @returns The response body directly, without a `body` envelope.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(body, options) {
+        return required((await this.#rpc.createOpenAIChatCompletion({ body: { ...body, stream: false } }, options)).body, "body");
+    }
+    /**
+     * Stream OpenAI-compatible JSON chat events.
+     *
+     * @param body - Ordinary JSON with OpenAI field names. The SDK sets `stream: true`.
+     * @returns A lazy iterable of `{ type, data }` events. Breaking iteration cancels the RPC.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *stream(body, options) {
+        for await (const event of this.#rpc.streamOpenAIChatCompletion({ body: { ...body, stream: true } }, options)) {
+            yield { type: event.type, data: required(event.data, "data") };
+        }
+    }
+}
+/** Typed chat completions and text helpers. Access through `client.chat`. */
+export class Chat {
+    #rpc;
+    /** OpenAI-compatible JSON requests and events for fields outside the typed chat API. */
+    json;
+    constructor(rpc) {
+        this.#rpc = rpc;
+        this.json = new JsonChat(rpc);
+    }
+    /**
+     * Generate a full chat completion, including usage and tool calls.
+     *
+     * @param input - Model and either a text `prompt` with optional `system`, or a non-empty `messages` array.
+     * @returns The complete response. Use `text()` when you only need the first choice's text.
+     * @example
+     * const completion = await client.chat.create({ model, prompt: "Hello" });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        return this.#rpc.createChatCompletion(chatRequest(input, false), options);
+    }
+    /**
+     * Stream full chat chunks, including tool-call deltas and usage when provided.
+     *
+     * @param input - Model and a prompt or messages. Streaming is selected by this method.
+     * @returns A lazy iterable. Breaking iteration cancels the RPC; timeouts cover the whole stream.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *stream(input, options) {
+        yield* this.#rpc.streamChatCompletion(chatRequest(input, true), options);
+    }
+    /**
+     * Generate the text from choice 0 of a chat completion.
+     *
+     * @param input - Model and either a text `prompt` with optional `system`, or a non-empty `messages` array.
+     * @throws TarkaError with `failed_precondition` if choice 0 has no text. Use `create()` for tool calls or full results.
+     * @example
+     * const text = await client.chat.text({ model, prompt: "Say hello" });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async text(input, options) {
+        const result = await this.create(input, options);
+        const content = result.choices.find((choice) => choice.index === 0)?.message
+            ?.content;
+        if (typeof content !== "string")
+            throw new TarkaError("The first choice did not contain text; use chat.create() to inspect the full completion", "failed_precondition");
+        return content;
+    }
+    /**
+     * Stream only non-empty text deltas from choice 0.
+     *
+     * Tool-call deltas and usage-only chunks are omitted. Use `stream()` to receive complete chunks.
+     * @param input - Model and a prompt or messages.
+     * @returns A lazy iterable of strings; breaking iteration cancels the RPC.
+     * @example
+     * for await (const text of client.chat.streamText({ model, prompt: "Hello" })) {
+     *   process.stdout.write(text);
+     * }
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *streamText(input, options) {
+        for await (const chunk of this.stream(input, options)) {
+            const text = chunk.choices.find((choice) => choice.index === 0)?.delta
+                ?.content;
+            if (typeof text === "string" && text.length)
+                yield text;
+        }
+    }
+}
+/** OpenAI-compatible Responses API with unwrapped JSON results. Access through `client.responses`. */
+export class Responses {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Create a response and return its JSON body directly.
+     *
+     * @param body - OpenAI-compatible JSON with original field names. The SDK sets `stream: false`.
+     * @example
+     * const response = await client.responses.create({ model, input: "Hello" });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(body, options) {
+        return required((await this.#rpc.createResponse({ body: { ...body, stream: false } }, options)).body, "body");
+    }
+    /**
+     * Stream response events as `{ type, data }`.
+     *
+     * @param body - OpenAI-compatible JSON. The SDK sets `stream: true`.
+     * @returns A lazy iterable. Breaking iteration cancels the RPC; a partial stream is never automatically replayed.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *stream(body, options) {
+        for await (const event of this.#rpc.streamResponse({ body: { ...body, stream: true } }, options)) {
+            yield { type: event.type, data: required(event.data, "data") };
+        }
+    }
+    /**
+     * Retrieve the JSON body of a stored response.
+     *
+     * @param id - Response identifier returned by creation.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        requireText(id, "response id");
+        return required((await this.#rpc.retrieveResponse({ responseId: id }, options)).body, "body");
+    }
+    /**
+     * Request cancellation of a response.
+     *
+     * @param id - Response identifier.
+     * @returns The updated response body.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async cancel(id, options) {
+        requireText(id, "response id");
+        return required((await this.#rpc.cancelResponse({ responseId: id }, options)).body, "body");
+    }
+    /**
+     * Delete a stored response.
+     *
+     * @param id - Response identifier.
+     * @returns Resolves without a value after the server acknowledges deletion.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(id, options) {
+        requireText(id, "response id");
+        await this.#rpc.deleteResponse({ responseId: id }, options);
+    }
+}
+/** Image text recognition and streaming. Access through `client.ocr`. */
+export class Ocr {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    request(input, stream) {
+        requireText(input?.model, "model");
+        if (input.image !== undefined) {
+            requireText(input.image, "image");
+            if (input.images !== undefined)
+                throw new TypeError("Provide image or images, not both");
+        }
+        else {
+            if (!Array.isArray(input.images) || !input.images.length)
+                throw new TypeError("images must not be empty");
+            for (const image of input.images)
+                requireText(image, "image");
+        }
+        return { ...input, stream };
+    }
+    /**
+     * Recognize text and return the full OCR result.
+     *
+     * @param input - OCR model and either one `image` or a non-empty `images` array, in a format supported by the model.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        return this.#rpc.createOCR(this.request(input, false), options);
+    }
+    /**
+     * Recognize text and return only the result's `text` field.
+     *
+     * @param input - OCR model and either `image` or `images`.
+     * @example
+     * const text = await client.ocr.text({ model, image: imageUrl });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async text(input, options) {
+        return (await this.create(input, options)).text;
+    }
+    /**
+     * Stream full OCR chunks.
+     *
+     * @param input - OCR model and either `image` or `images`.
+     * @returns A lazy iterable. Breaking iteration cancels the RPC.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *stream(input, options) {
+        yield* this.#rpc.streamOCR(this.request(input, true), options);
+    }
+    /**
+     * Stream non-empty text fields from OCR chunks.
+     *
+     * @param input - OCR model and either `image` or `images`.
+     * @returns Text chunks in server order. Use `stream()` for the other result fields.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *streamText(input, options) {
+        for await (const chunk of this.stream(input, options))
+            if (chunk.text)
+                yield chunk.text;
+    }
+}
+/** Speech-to-text transcription. Access through `client.audio.transcriptions`. */
+export class Transcriptions {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Transcribe audio and return the full text response, including metadata when provided.
+     *
+     * @param input - Transcription model, audio bytes as a Buffer, and optional filename, content type, and model settings.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        return this.#rpc.createTranscription(input, options);
+    }
+    /**
+     * Transcribe audio and return only the recognized text.
+     *
+     * @param input - Transcription model and audio bytes as a Buffer.
+     * @example
+     * const text = await client.audio.transcriptions.text({ model, file: audioBuffer });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async text(input, options) {
+        return (await this.create(input, options)).text;
+    }
+}
+/** Audio translation. Access through `client.audio.translations`. */
+export class Translations {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Translate audio and return the full text response.
+     *
+     * @param input - Translation model, audio bytes as a Buffer, and optional file metadata and model settings.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        return this.#rpc.createTranslation(input, options);
+    }
+    /**
+     * Translate audio and return only the translated text.
+     *
+     * @param input - Translation model and audio bytes as a Buffer.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async text(input, options) {
+        return (await this.create(input, options)).text;
+    }
+}
+/** Speech generation as a collected Buffer or a stream. Access through `client.audio.speech`. */
+export class Speech {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Generate speech as a stream of audio chunks.
+     *
+     * @param input - Speech model, text in `input`, and optional voice and output settings.
+     * @returns A lazy iterable of `{ data: Buffer, contentType }`. Breaking iteration cancels the RPC.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async *stream(input, options) {
+        yield* this.#rpc.createSpeech(input, options);
+    }
+    /**
+     * Generate speech and collect all audio into one Buffer.
+     *
+     * @param input - Speech model, text in `input`, and optional voice and output settings.
+     * @returns `{ data: Buffer, contentType }`. Use `stream()` to avoid buffering a large response.
+     * @example
+     * const audio = await client.audio.speech.create({ model, input: "Hello" });
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        const chunks = [];
+        let contentType = "";
+        for await (const chunk of this.stream(input, options)) {
+            chunks.push(chunk.data);
+            contentType = chunk.contentType || contentType;
+        }
+        return { data: Buffer.concat(chunks), contentType };
+    }
+}
+/** Voice cloning with explicit consent metadata. Access through `client.audio.voices`. */
+export class Voices {
+    #rpc;
+    constructor(rpc) {
+        this.#rpc = rpc;
+    }
+    /**
+     * Create a voice clone from an audio sample and consent information.
+     *
+     * @param input - Model, voice name, sample Buffer, consent signer and date, plus optional file metadata.
+     * @returns The created voice record; inspect its `status` for the server-reported state.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async create(input, options) {
+        return this.#rpc.createVoiceClone(input, options);
+    }
+    /**
+     * Retrieve a voice clone and its current state.
+     *
+     * @param id - Voice identifier.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async get(id, options) {
+        requireText(id, "voice id");
+        return this.#rpc.getVoiceClone({ voiceId: id }, options);
+    }
+    /**
+     * Delete a voice clone.
+     *
+     * @param id - Voice identifier.
+     * @returns Resolves without a value after acknowledgement.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    async delete(id, options) {
+        requireText(id, "voice id");
+        await this.#rpc.deleteVoiceClone({ voiceId: id }, options);
+    }
+}
+/** Audio transcription, translation, generation, and voice cloning. Access through `client.audio`. */
+export class Audio {
+    /** Transcribe audio into text, with full-result and text-only methods. */
+    transcriptions;
+    /** Translate audio into text, with full-result and text-only methods. */
+    translations;
+    /** Generate audio as a collected Buffer or a stream of chunks. */
+    speech;
+    /** Create, retrieve, and delete voice clones. */
+    voices;
+    constructor(rpc) {
+        this.transcriptions = new Transcriptions(rpc);
+        this.translations = new Translations(rpc);
+        this.speech = new Speech(rpc);
+        this.voices = new Voices(rpc);
+    }
+}