@tarkahq/sdk 0.0.0-stage → 0.3.0

package/dist/esm/grpc.d.ts

@@ -0,0 +1,12 @@
+/** Low-level transport, service definitions and codecs for advanced integrations. */
+export { createChannel, DEFAULT_GRPC_ENDPOINT, type ChannelConfig, } from "./client.js";
+export { createServiceClient, type CallOptions, type ServiceClient, type ServiceDefinition, } from "./transport.js";
+export type { GrpcClient, InferenceRpc, ProvisioningRpc, SandboxRpc, } from "./rpc-types.js";
+export { Channel, ChannelCredentials, Metadata, credentials, status, type ChannelOptions, type ServiceError, } from "@grpc/grpc-js";
+export * as inference from "./generated/tarka/inference/v1/inference.js";
+export * as provisioning from "./generated/tarka/provisioning/v1/provisioning.js";
+export * as sandboxes from "./generated/tarka/provisioning/v1/sandbox.js";
+export * as iam from "./generated/tarka/iam/v1/iam.js";
+export * as gateway from "./generated/tarka/gateway/v1/gateway.js";
+export * as access from "./generated/tarka/access/v1/access.js";
+export * as channels from "./generated/tarka/channels/v1/channels.js";

package/dist/esm/grpc.js

@@ -0,0 +1,11 @@
+/** Low-level transport, service definitions and codecs for advanced integrations. */
+export { createChannel, DEFAULT_GRPC_ENDPOINT, } from "./client.js";
+export { createServiceClient, } from "./transport.js";
+export { Channel, ChannelCredentials, Metadata, credentials, status, } from "@grpc/grpc-js";
+export * as inference from "./generated/tarka/inference/v1/inference.js";
+export * as provisioning from "./generated/tarka/provisioning/v1/provisioning.js";
+export * as sandboxes from "./generated/tarka/provisioning/v1/sandbox.js";
+export * as iam from "./generated/tarka/iam/v1/iam.js";
+export * as gateway from "./generated/tarka/gateway/v1/gateway.js";
+export * as access from "./generated/tarka/access/v1/access.js";
+export * as channels from "./generated/tarka/channels/v1/channels.js";

package/dist/esm/index.d.ts

@@ -0,0 +1,6 @@
+export { TarkaClient, type TarkaClientOptions } from "./client.js";
+export { TarkaError, type ErrorCode } from "./errors.js";
+export type * from "./types.js";
+export { Sandbox, SandboxTemplate, Execution, OperationError, SandboxOperationError, TemplateOperationError, ExecutionOperationError, ResourceStateError, type RecoveryDetails, } from "./resources/sandboxes.js";
+export type { OrganizationScope } from "./resources/provisioning.js";
+export { RuntimeClient, RuntimeMessage, RuntimeRun, RuntimeError, type RuntimeClientOptions, type RuntimeStart, type RuntimePermission, type RuntimeMetadata, } from "./runtime.js";

package/dist/esm/index.js

@@ -0,0 +1,4 @@
+export { TarkaClient } from "./client.js";
+export { TarkaError } from "./errors.js";
+export { Sandbox, SandboxTemplate, Execution, OperationError, SandboxOperationError, TemplateOperationError, ExecutionOperationError, ResourceStateError, } from "./resources/sandboxes.js";
+export { RuntimeClient, RuntimeMessage, RuntimeRun, RuntimeError, } from "./runtime.js";

package/dist/esm/resources/inference.d.ts

@@ -0,0 +1,293 @@
+import type { InferenceRpc, ProvisioningRpc } from "../rpc-types.js";
+import type { RequestOptions, ChatInput, Model, CatalogModel, ChatCompletion, ChatChunk, JsonObject, ResponseEvent, OcrInput, OcrResult, OcrChunk, TranscriptionInput, TranslationInput, AudioText, SpeechInput, AudioData, VoiceInput, Voice } from "../types.js";
+/** Inference model discovery. Access through `client.models`. */
+export declare class Models {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    list(options?: RequestOptions): Promise<Model[]>;
+    /**
+     * 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.
+     */
+    get(id: string, options?: RequestOptions): Promise<Model>;
+}
+/** Control plane model catalog, including provisioning information. Access through `client.catalog`. */
+export declare class Catalog {
+    #private;
+    constructor(rpc: ProvisioningRpc);
+    /**
+     * 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.
+     */
+    list(filter?: {
+        modality?: string;
+    }, options?: RequestOptions): Promise<CatalogModel[]>;
+}
+/** OpenAI-compatible JSON chat. Access through `client.chat.json` when you need fields outside the typed chat API. */
+export declare class JsonChat {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(body: JsonObject, options?: RequestOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    stream(body: JsonObject, options?: RequestOptions): AsyncIterable<ResponseEvent>;
+}
+/** Typed chat completions and text helpers. Access through `client.chat`. */
+export declare class Chat {
+    #private;
+    /** OpenAI-compatible JSON requests and events for fields outside the typed chat API. */
+    readonly json: JsonChat;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(input: ChatInput, options?: RequestOptions): Promise<ChatCompletion>;
+    /**
+     * 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.
+     */
+    stream(input: ChatInput, options?: RequestOptions): AsyncIterable<ChatChunk>;
+    /**
+     * 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.
+     */
+    text(input: ChatInput, options?: RequestOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    streamText(input: ChatInput, options?: RequestOptions): AsyncIterable<string>;
+}
+/** OpenAI-compatible Responses API with unwrapped JSON results. Access through `client.responses`. */
+export declare class Responses {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(body: JsonObject, options?: RequestOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    stream(body: JsonObject, options?: RequestOptions): AsyncIterable<ResponseEvent>;
+    /**
+     * 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.
+     */
+    get(id: string, options?: RequestOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    cancel(id: string, options?: RequestOptions): Promise<JsonObject>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}
+/** Image text recognition and streaming. Access through `client.ocr`. */
+export declare class Ocr {
+    #private;
+    constructor(rpc: InferenceRpc);
+    private request;
+    /**
+     * 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.
+     */
+    create(input: OcrInput, options?: RequestOptions): Promise<OcrResult>;
+    /**
+     * 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.
+     */
+    text(input: OcrInput, options?: RequestOptions): Promise<string>;
+    /**
+     * 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.
+     */
+    stream(input: OcrInput, options?: RequestOptions): AsyncIterable<OcrChunk>;
+    /**
+     * 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.
+     */
+    streamText(input: OcrInput, options?: RequestOptions): AsyncIterable<string>;
+}
+/** Speech-to-text transcription. Access through `client.audio.transcriptions`. */
+export declare class Transcriptions {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(input: TranscriptionInput, options?: RequestOptions): Promise<AudioText>;
+    /**
+     * 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.
+     */
+    text(input: TranscriptionInput, options?: RequestOptions): Promise<string>;
+}
+/** Audio translation. Access through `client.audio.translations`. */
+export declare class Translations {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(input: TranslationInput, options?: RequestOptions): Promise<AudioText>;
+    /**
+     * 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.
+     */
+    text(input: TranslationInput, options?: RequestOptions): Promise<string>;
+}
+/** Speech generation as a collected Buffer or a stream. Access through `client.audio.speech`. */
+export declare class Speech {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    stream(input: SpeechInput, options?: RequestOptions): AsyncIterable<AudioData>;
+    /**
+     * 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.
+     */
+    create(input: SpeechInput, options?: RequestOptions): Promise<AudioData>;
+}
+/** Voice cloning with explicit consent metadata. Access through `client.audio.voices`. */
+export declare class Voices {
+    #private;
+    constructor(rpc: InferenceRpc);
+    /**
+     * 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.
+     */
+    create(input: VoiceInput, options?: RequestOptions): Promise<Voice>;
+    /**
+     * Retrieve a voice clone and its current state.
+     *
+     * @param id - Voice identifier.
+     * @param options - Per-call timeout in milliseconds, cancellation signal, and metadata.
+     */
+    get(id: string, options?: RequestOptions): Promise<Voice>;
+    /**
+     * 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.
+     */
+    delete(id: string, options?: RequestOptions): Promise<void>;
+}
+/** Audio transcription, translation, generation, and voice cloning. Access through `client.audio`. */
+export declare class Audio {
+    /** Transcribe audio into text, with full-result and text-only methods. */
+    readonly transcriptions: Transcriptions;
+    /** Translate audio into text, with full-result and text-only methods. */
+    readonly translations: Translations;
+    /** Generate audio as a collected Buffer or a stream of chunks. */
+    readonly speech: Speech;
+    /** Create, retrieve, and delete voice clones. */
+    readonly voices: Voices;
+    constructor(rpc: InferenceRpc);
+}