@kaana.ai/contracts 0.0.0-stage → 4.4.0

package/dist/internal/usage.d.ts

@@ -0,0 +1,127 @@
+/**
+ * The normalized usage report: what Kaana measured, and the only shape a
+ * settlement is written from.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/usage.ts`) by Kaana ADR 0002.
+ * Reservations, receipts and refunds are the ledger and stay in
+ * `@oxy.so/contracts`.
+ */
+import { z } from 'zod';
+/**
+ * The data plane's technical account of one request, and the ONLY shape a
+ * settlement is written from.
+ *
+ * `inferenceStreamUsageEventSchema` is not a narrower version of this one that
+ * could be widened into it — see that event's own comment. Its units are exact
+ * and settleable; the record around them is not inferable, so an edge settling
+ * from a stream event supplies the outcome itself and never promotes the event.
+ *
+ * No money and no price: the data plane measures units and names the route it
+ * used, and the control plane decides what that costs. Keeping the two apart is
+ * what allows a price to be corrected after the fact without re-running or
+ * re-measuring anything.
+ *
+ * `usageSource` is load-bearing when a provider returns no usage at all: the
+ * report still arrives, marked `estimated`, so settlement can apply the
+ * estimation policy knowingly instead of treating a reconstruction as fact.
+ *
+ * `units` is a PARTITION of what the request consumed, not a set of totals with
+ * details hanging off them — see `USAGE_UNITS` in `money.ts`. Reporting a provider's
+ * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
+ * reasoning tokens twice, so subtracting the children out is part of what
+ * "normalized" means in this shape's name.
+ *
+ * **A `completed` report carries at least one unit, and the other outcomes need
+ * not.** `completed` is the one outcome that asserts the customer received the
+ * whole answer, so "delivered in full, consumed nothing measurable" is a
+ * contradiction — and it is one that BILLS NOTHING: settlement prices every
+ * reported unit and sums, so an empty list is a free request produced by a
+ * provider that simply omitted its usage block. The refinement makes that shape
+ * unparseable, and the policy behind it is refuse-and-release: the report is
+ * rejected and the hold is released, never estimated and charged.
+ *
+ * The three other outcomes legitimately carry none, which is why the rule is
+ * conditional rather than a `.min(1)` on the field. In the reference data plane
+ * `failed` is DERIVED from having no units — `outcomeFor` in
+ * Kaana's `internal/kaana/executor.go` returns `partial` when units exist and `failed`
+ * when they do not — and `cancelled` is reported for a client that stopped
+ * before anything was measured. An unconditional minimum would refuse those
+ * reports, and a refused report is a request that ran, cost money upstream and
+ * can never be settled or refunded.
+ */
+export declare const normalizedUsageReportSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<2>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+    attribution: z.ZodObject<{
+        principal: z.ZodObject<{
+            billing: z.ZodObject<{
+                accountId: z.core.$ZodBranded<z.ZodString, "OxyAccountId", "out">;
+            }, z.core.$strict>;
+            applicationId: z.ZodString;
+            credentialId: z.ZodString;
+            environment: z.ZodEnum<{
+                development: "development";
+                staging: "staging";
+                production: "production";
+            }>;
+            inferenceScopes: z.ZodArray<z.ZodEnum<{
+                "inference:invoke": "inference:invoke";
+                "inference:models:read": "inference:models:read";
+                "inference:usage:read": "inference:usage:read";
+                "inference:routing:read": "inference:routing:read";
+                "inference:routing:write": "inference:routing:write";
+                "inference:providers:read": "inference:providers:read";
+                "inference:providers:write": "inference:providers:write";
+            }>>;
+        }, z.core.$strip>;
+        userId: z.ZodOptional<z.core.$ZodBranded<z.ZodString, "DelegatedUserId", "out">>;
+        requestId: z.ZodString;
+        generationId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    outcome: z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        partial: "partial";
+        failed: "failed";
+    }>;
+    units: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            output_tokens: "output_tokens";
+            reasoning_tokens: "reasoning_tokens";
+            requests: "requests";
+            images: "images";
+            audio_input_milliseconds: "audio_input_milliseconds";
+            audio_output_milliseconds: "audio_output_milliseconds";
+            video_milliseconds: "video_milliseconds";
+            characters: "characters";
+            embeddings: "embeddings";
+            audio_input_tokens: "audio_input_tokens";
+            cached_audio_input_tokens: "cached_audio_input_tokens";
+            audio_output_tokens: "audio_output_tokens";
+            session_milliseconds: "session_milliseconds";
+            input_transcription_milliseconds: "input_transcription_milliseconds";
+        }>;
+        quantity: z.ZodNumber;
+    }, z.core.$strict>>;
+    usageSource: z.ZodEnum<{
+        provider_reported: "provider_reported";
+        oxy_measured: "oxy_measured";
+        estimated: "estimated";
+    }>;
+    resolvedModelReference: z.ZodString;
+    servingProvider: z.ZodString;
+    deploymentId: z.ZodString;
+    routeSwitches: z.ZodNumber;
+    fundingTier: z.ZodOptional<z.ZodEnum<{
+        free: "free";
+        credit: "credit";
+        paid: "paid";
+    }>>;
+    startedAt: z.ZodString;
+    completedAt: z.ZodString;
+    timeToFirstTokenMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type NormalizedUsageReport = z.infer<typeof normalizedUsageReportSchema>;

package/dist/internal/usage.js

@@ -0,0 +1,109 @@
+/**
+ * The normalized usage report: what Kaana measured, and the only shape a
+ * settlement is written from.
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/usage.ts`) by Kaana ADR 0002.
+ * Reservations, receipts and refunds are the ledger and stay in
+ * `@oxy.so/contracts`.
+ */
+import { z } from 'zod';
+import { inferenceRequestOutcomeSchema } from '../public/generations.js';
+import { generationIdSchema, inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from '../public/identifiers.js';
+import { usageQuantitySchema, usageSourceSchema } from '../public/money.js';
+import { inferenceAttributionSchema } from './attribution.js';
+import { deploymentIdSchema, inferenceFundingTierSchema, inferenceProviderSlugSchema, } from './identifiers.js';
+/**
+ * The data plane's technical account of one request, and the ONLY shape a
+ * settlement is written from.
+ *
+ * `inferenceStreamUsageEventSchema` is not a narrower version of this one that
+ * could be widened into it — see that event's own comment. Its units are exact
+ * and settleable; the record around them is not inferable, so an edge settling
+ * from a stream event supplies the outcome itself and never promotes the event.
+ *
+ * No money and no price: the data plane measures units and names the route it
+ * used, and the control plane decides what that costs. Keeping the two apart is
+ * what allows a price to be corrected after the fact without re-running or
+ * re-measuring anything.
+ *
+ * `usageSource` is load-bearing when a provider returns no usage at all: the
+ * report still arrives, marked `estimated`, so settlement can apply the
+ * estimation policy knowingly instead of treating a reconstruction as fact.
+ *
+ * `units` is a PARTITION of what the request consumed, not a set of totals with
+ * details hanging off them — see `USAGE_UNITS` in `money.ts`. Reporting a provider's
+ * nested `prompt_tokens`/`completion_tokens` verbatim charges the cached and
+ * reasoning tokens twice, so subtracting the children out is part of what
+ * "normalized" means in this shape's name.
+ *
+ * **A `completed` report carries at least one unit, and the other outcomes need
+ * not.** `completed` is the one outcome that asserts the customer received the
+ * whole answer, so "delivered in full, consumed nothing measurable" is a
+ * contradiction — and it is one that BILLS NOTHING: settlement prices every
+ * reported unit and sums, so an empty list is a free request produced by a
+ * provider that simply omitted its usage block. The refinement makes that shape
+ * unparseable, and the policy behind it is refuse-and-release: the report is
+ * rejected and the hold is released, never estimated and charged.
+ *
+ * The three other outcomes legitimately carry none, which is why the rule is
+ * conditional rather than a `.min(1)` on the field. In the reference data plane
+ * `failed` is DERIVED from having no units — `outcomeFor` in
+ * Kaana's `internal/kaana/executor.go` returns `partial` when units exist and `failed`
+ * when they do not — and `cancelled` is reported for a client that stopped
+ * before anything was measured. An unconditional minimum would refuse those
+ * reports, and a refused report is a request that ran, cost money upstream and
+ * can never be settled or refunded.
+ */
+export const normalizedUsageReportSchema = z
+    .object({
+    /** See `version.ts`: emitted by the data plane as a whole message. */
+    schemaVersion: z.literal(2),
+    requestId: requestIdSchema,
+    generationId: generationIdSchema.optional(),
+    attribution: inferenceAttributionSchema,
+    outcome: inferenceRequestOutcomeSchema,
+    units: z.array(usageQuantitySchema),
+    usageSource: usageSourceSchema,
+    resolvedModelReference: modelReferenceSchema,
+    servingProvider: inferenceProviderSlugSchema,
+    /** Exact Kaana deployment that attempted the request; never inferred from names. */
+    deploymentId: deploymentIdSchema,
+    /** How many allowed route switches occurred while serving this request. */
+    routeSwitches: z.number().int().nonnegative().max(100),
+    /**
+     * The funding tier of the platform key that served the final attempt, as
+     * the data plane states it (ADR 0038). Absent when the key's economics
+     * were never stated, when a customer credential served, or when nothing
+     * was served. Oxy reads it to account for what the request cost the
+     * platform; it is never a key identity and never reaches a customer.
+     */
+    fundingTier: inferenceFundingTierSchema.optional(),
+    startedAt: inferenceTimestampSchema,
+    completedAt: inferenceTimestampSchema,
+    timeToFirstTokenMs: z.number().int().nonnegative().safe().optional(),
+})
+    .superRefine((report, ctx) => {
+    // Compared as instants: two spellings of one moment sort differently as text.
+    if (Date.parse(report.completedAt) < Date.parse(report.startedAt)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['completedAt'],
+            message: 'a request cannot complete before it started',
+        });
+    }
+    const units = report.units.map((quantity) => quantity.unit);
+    if (new Set(units).size !== units.length) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['units'],
+            message: 'each unit is reported once, as a total',
+        });
+    }
+    if (report.outcome === 'completed' && report.units.length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['units'],
+            message: 'a completed request consumed something; report at least one unit',
+        });
+    }
+});

package/dist/internal.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@kaana.ai/contracts/internal` — what Oxy and Kaana exchange privately.
+ *
+ * The grant and its authorization request, the settlement, the canonical
+ * input hash, the operational catalogue, customer-credential control and the
+ * signed v1–v4 envelope with its stream and usage report (retired at the end
+ * of the cut, Kaana ADR 0002 phase 5). Nothing here is a public API: it names
+ * providers, deployments, keys and billing accounts.
+ *
+ * Shared vocabulary (identifiers, messages, money) is imported from the
+ * package root; this entry point exports only what is internal.
+ */
+export * from './internal/attribution.js';
+export * from './internal/canonical.js';
+export * from './internal/catalogue.js';
+export * from './internal/credentialControl.js';
+export * from './internal/decisions.js';
+export * from './internal/economics.js';
+export * from './internal/embeddings.js';
+export * from './internal/errors.js';
+export * from './internal/grant.js';
+export * from './internal/identifiers.js';
+export * from './internal/privateAutoExecution.js';
+export * from './internal/realtime.js';
+export * from './internal/request.js';
+export * from './internal/routing.js';
+export * from './internal/scopedExecution.js';
+export * from './internal/settlement.js';
+export * from './internal/streamEvents.js';
+export * from './internal/usage.js';

package/dist/internal.js

@@ -0,0 +1,30 @@
+/**
+ * `@kaana.ai/contracts/internal` — what Oxy and Kaana exchange privately.
+ *
+ * The grant and its authorization request, the settlement, the canonical
+ * input hash, the operational catalogue, customer-credential control and the
+ * signed v1–v4 envelope with its stream and usage report (retired at the end
+ * of the cut, Kaana ADR 0002 phase 5). Nothing here is a public API: it names
+ * providers, deployments, keys and billing accounts.
+ *
+ * Shared vocabulary (identifiers, messages, money) is imported from the
+ * package root; this entry point exports only what is internal.
+ */
+export * from './internal/attribution.js';
+export * from './internal/canonical.js';
+export * from './internal/catalogue.js';
+export * from './internal/credentialControl.js';
+export * from './internal/decisions.js';
+export * from './internal/economics.js';
+export * from './internal/embeddings.js';
+export * from './internal/errors.js';
+export * from './internal/grant.js';
+export * from './internal/identifiers.js';
+export * from './internal/privateAutoExecution.js';
+export * from './internal/realtime.js';
+export * from './internal/request.js';
+export * from './internal/routing.js';
+export * from './internal/scopedExecution.js';
+export * from './internal/settlement.js';
+export * from './internal/streamEvents.js';
+export * from './internal/usage.js';

package/dist/public/audio.d.ts

@@ -0,0 +1,347 @@
+/**
+ * `POST /v1/audio/speech` (with and without streaming) and
+ * `POST /v1/audio/transcriptions`.
+ *
+ * The speech request is moved from the Oxy edge
+ * (`packages/api/src/schemas/inferenceEdge.schemas.ts`) by Kaana ADR 0002;
+ * streaming speech (decision 8), the voice limits checked before a grant
+ * (decision 9) and transcription are new in contract set 4.0.0.
+ */
+import { z } from 'zod';
+import type { ModelAudioCapabilities } from './catalogue.js';
+/** The longest text one speech request may carry, before any model's own limit. */
+export declare const MAX_SPEECH_INPUT_CHARACTERS = 100000;
+/**
+ * How a streamed speech response is carried:
+ *
+ * - `audio` (OpenAI-compatible): `200` with `Transfer-Encoding: chunked` and the
+ *   raw bytes. A failure before the first byte is an HTTP status with an error
+ *   body; one after it cuts the connection and the generation record keeps the
+ *   code.
+ * - `sse` (what `@kaana.ai/sdk` uses): {@link speechStreamEventSchema} frames,
+ *   so a failure mid-stream arrives typed.
+ */
+export declare const speechStreamFormatSchema: z.ZodEnum<{
+    audio: "audio";
+    sse: "sse";
+}>;
+/**
+ * The formats speech can be streamed in: `audio/mpeg` and
+ * `audio/pcm;rate=24000`, the two containers that can be played as they arrive.
+ */
+export declare const STREAMABLE_SPEECH_FORMATS: readonly ["mp3", "pcm"];
+/**
+ * The request, in the shape a stock OpenAI client sends.
+ *
+ * `model` is a concrete model: a voice belongs to a model, so a power level,
+ * which may choose any of several, could not be validated against one.
+ */
+export declare const speechRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    input: z.ZodString;
+    voice: z.ZodString;
+    response_format: z.ZodOptional<z.ZodEnum<{
+        mp3: "mp3";
+        opus: "opus";
+        aac: "aac";
+        flac: "flac";
+        wav: "wav";
+        pcm: "pcm";
+    }>>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    stream_format: z.ZodOptional<z.ZodEnum<{
+        audio: "audio";
+        sse: "sse";
+    }>>;
+    user: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/** One chunk of audio, in order, as soon as the provider produced it. */
+export declare const speechAudioDeltaEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"speech.audio.delta">;
+    audio: z.ZodString;
+}, z.core.$strict>;
+/** The last event of a successful stream: what served it and what it consumed. */
+export declare const speechAudioDoneEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"speech.audio.done">;
+    requestId: z.ZodString;
+    model: z.ZodString;
+    usage: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            output_tokens: "output_tokens";
+            reasoning_tokens: "reasoning_tokens";
+            requests: "requests";
+            images: "images";
+            audio_input_milliseconds: "audio_input_milliseconds";
+            audio_output_milliseconds: "audio_output_milliseconds";
+            video_milliseconds: "video_milliseconds";
+            characters: "characters";
+            embeddings: "embeddings";
+            audio_input_tokens: "audio_input_tokens";
+            cached_audio_input_tokens: "cached_audio_input_tokens";
+            audio_output_tokens: "audio_output_tokens";
+            session_milliseconds: "session_milliseconds";
+            input_transcription_milliseconds: "input_transcription_milliseconds";
+        }>;
+        quantity: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** The terminal failure of a stream, after which nothing follows. */
+export declare const speechStreamErrorEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        code: z.ZodEnum<{
+            invalid_request: "invalid_request";
+            authentication_failed: "authentication_failed";
+            permission_denied: "permission_denied";
+            insufficient_scope: "insufficient_scope";
+            model_not_found: "model_not_found";
+            unsupported_modality: "unsupported_modality";
+            context_length_exceeded: "context_length_exceeded";
+            request_too_large: "request_too_large";
+            output_limit_exceeded: "output_limit_exceeded";
+            idempotency_conflict: "idempotency_conflict";
+            insufficient_balance: "insufficient_balance";
+            spending_limit_exceeded: "spending_limit_exceeded";
+            quota_exceeded: "quota_exceeded";
+            byok_credential_invalid: "byok_credential_invalid";
+            policy_violation: "policy_violation";
+            commercial_permission_denied: "commercial_permission_denied";
+            no_route_available: "no_route_available";
+            upstream_content_filtered: "upstream_content_filtered";
+            cancelled: "cancelled";
+            rate_limited: "rate_limited";
+            provider_error: "provider_error";
+            provider_timeout: "provider_timeout";
+            provider_overloaded: "provider_overloaded";
+            service_unavailable: "service_unavailable";
+            internal_error: "internal_error";
+        }>;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+        requestId: z.ZodString;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        param: z.ZodOptional<z.ZodString>;
+        upstreamCategory: z.ZodOptional<z.ZodEnum<{
+            rate_limit: "rate_limit";
+            quota: "quota";
+            timeout: "timeout";
+            overloaded: "overloaded";
+            server_error: "server_error";
+            content_filter: "content_filter";
+            invalid_request: "invalid_request";
+            authentication: "authentication";
+            unknown: "unknown";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/**
+ * The frames of `stream_format: 'sse'`. The media type is not repeated: it is
+ * a function of the request's `response_format` ({@link speechMediaType}).
+ */
+export declare const speechStreamEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"speech.audio.delta">;
+    audio: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"speech.audio.done">;
+    requestId: z.ZodString;
+    model: z.ZodString;
+    usage: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            output_tokens: "output_tokens";
+            reasoning_tokens: "reasoning_tokens";
+            requests: "requests";
+            images: "images";
+            audio_input_milliseconds: "audio_input_milliseconds";
+            audio_output_milliseconds: "audio_output_milliseconds";
+            video_milliseconds: "video_milliseconds";
+            characters: "characters";
+            embeddings: "embeddings";
+            audio_input_tokens: "audio_input_tokens";
+            cached_audio_input_tokens: "cached_audio_input_tokens";
+            audio_output_tokens: "audio_output_tokens";
+            session_milliseconds: "session_milliseconds";
+            input_transcription_milliseconds: "input_transcription_milliseconds";
+        }>;
+        quantity: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"error">;
+    error: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<1>;
+        code: z.ZodEnum<{
+            invalid_request: "invalid_request";
+            authentication_failed: "authentication_failed";
+            permission_denied: "permission_denied";
+            insufficient_scope: "insufficient_scope";
+            model_not_found: "model_not_found";
+            unsupported_modality: "unsupported_modality";
+            context_length_exceeded: "context_length_exceeded";
+            request_too_large: "request_too_large";
+            output_limit_exceeded: "output_limit_exceeded";
+            idempotency_conflict: "idempotency_conflict";
+            insufficient_balance: "insufficient_balance";
+            spending_limit_exceeded: "spending_limit_exceeded";
+            quota_exceeded: "quota_exceeded";
+            byok_credential_invalid: "byok_credential_invalid";
+            policy_violation: "policy_violation";
+            commercial_permission_denied: "commercial_permission_denied";
+            no_route_available: "no_route_available";
+            upstream_content_filtered: "upstream_content_filtered";
+            cancelled: "cancelled";
+            rate_limited: "rate_limited";
+            provider_error: "provider_error";
+            provider_timeout: "provider_timeout";
+            provider_overloaded: "provider_overloaded";
+            service_unavailable: "service_unavailable";
+            internal_error: "internal_error";
+        }>;
+        message: z.ZodString;
+        retryable: z.ZodBoolean;
+        requestId: z.ZodString;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
+        param: z.ZodOptional<z.ZodString>;
+        upstreamCategory: z.ZodOptional<z.ZodEnum<{
+            rate_limit: "rate_limit";
+            quota: "quota";
+            timeout: "timeout";
+            overloaded: "overloaded";
+            server_error: "server_error";
+            content_filter: "content_filter";
+            invalid_request: "invalid_request";
+            authentication: "authentication";
+            unknown: "unknown";
+        }>>;
+    }, z.core.$strict>;
+}, z.core.$strict>], "type">;
+/** Why a speech request cannot be served by a model, before anything is held. */
+export interface SpeechRequestIssue {
+    /** The request field at fault, as `invalid_request.param` names it. */
+    readonly param: 'input' | 'voice' | 'response_format' | 'speed';
+    readonly message: string;
+}
+/**
+ * Check a speech request against the model's published audio capabilities
+ * (Kaana ADR 0002, decision 9). Kaana's handler refuses the request with
+ * `invalid_request` and the first issue's `param` BEFORE asking Oxy for a
+ * grant, so a `speed` of 1.5 for a model that publishes 0.7–1.2 holds no money;
+ * a client may run the same check first.
+ *
+ * Returns every issue, in field order; an empty list means the model accepts
+ * the request. Characters are counted in UTF-16 code units, as `length` does.
+ */
+export declare function checkSpeechRequest(request: z.infer<typeof speechRequestSchema>, audio: ModelAudioCapabilities): SpeechRequestIssue[];
+/** The largest audio file one transcription request may upload: 20 MiB. */
+export declare const MAX_TRANSCRIPTION_FILE_BYTES: number;
+/**
+ * The text fields of the `multipart/form-data` request. The audio itself is the
+ * `file` part, at most {@link MAX_TRANSCRIPTION_FILE_BYTES}, whose content type
+ * is one of `audioInputMediaTypeSchema`; it is binary and so is not a Zod shape.
+ * Synchronous: the transcription is the response.
+ */
+export declare const transcriptionRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    timestamps: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        segment: "segment";
+        word: "word";
+    }>>;
+}, z.core.$strict>;
+/**
+ * The longest audio one transcription request may carry, when its container
+ * states a duration (WAV, raw PCM at a known rate). A file whose container does
+ * not state one is bounded by {@link MAX_TRANSCRIPTION_FILE_BYTES} alone: Kaana
+ * never guesses a duration from a byte count. New in contract set 4.2.0.
+ */
+export declare const MAX_TRANSCRIPTION_AUDIO_MILLISECONDS: number;
+/**
+ * The longest padded base64 the JSON form may carry: exactly the encoding of
+ * {@link MAX_TRANSCRIPTION_FILE_BYTES}.
+ */
+export declare const MAX_TRANSCRIPTION_AUDIO_BASE64_LENGTH: number;
+/**
+ * The JSON form of `POST /v1/audio/transcriptions` (`Content-Type:
+ * application/json`): the same fields as the multipart form, with the audio
+ * inline as padded base64. For runtimes where building a multipart body from
+ * bytes is unreliable (React Native); the two forms mean the same request and
+ * hash the same way. New in contract set 4.2.0.
+ */
+export declare const transcriptionJsonRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodOptional<z.ZodString>;
+    timestamps: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        segment: "segment";
+        word: "word";
+    }>>;
+    audio: z.ZodObject<{
+        mediaType: z.ZodEnum<{
+            "audio/mpeg": "audio/mpeg";
+            "audio/wav": "audio/wav";
+            "audio/ogg": "audio/ogg";
+            "audio/aac": "audio/aac";
+            "audio/flac": "audio/flac";
+            "audio/pcm": "audio/pcm";
+            "audio/mp4": "audio/mp4";
+            "audio/webm": "audio/webm";
+        }>;
+        data: z.ZodString;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+/** The response. Segments or words are present only when the request asked for them. */
+export declare const transcriptionSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    model: z.ZodString;
+    text: z.ZodString;
+    language: z.ZodOptional<z.ZodString>;
+    durationMs: z.ZodOptional<z.ZodNumber>;
+    segments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        text: z.ZodString;
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+    }, z.core.$strict>>>;
+    words: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        word: z.ZodString;
+        startMs: z.ZodNumber;
+        endMs: z.ZodNumber;
+    }, z.core.$strict>>>;
+    usage: z.ZodArray<z.ZodObject<{
+        unit: z.ZodEnum<{
+            input_tokens: "input_tokens";
+            cached_input_tokens: "cached_input_tokens";
+            output_tokens: "output_tokens";
+            reasoning_tokens: "reasoning_tokens";
+            requests: "requests";
+            images: "images";
+            audio_input_milliseconds: "audio_input_milliseconds";
+            audio_output_milliseconds: "audio_output_milliseconds";
+            video_milliseconds: "video_milliseconds";
+            characters: "characters";
+            embeddings: "embeddings";
+            audio_input_tokens: "audio_input_tokens";
+            cached_audio_input_tokens: "cached_audio_input_tokens";
+            audio_output_tokens: "audio_output_tokens";
+            session_milliseconds: "session_milliseconds";
+            input_transcription_milliseconds: "input_transcription_milliseconds";
+        }>;
+        quantity: z.ZodNumber;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type SpeechStreamFormat = z.infer<typeof speechStreamFormatSchema>;
+export type SpeechRequest = z.infer<typeof speechRequestSchema>;
+export type SpeechAudioDeltaEvent = z.infer<typeof speechAudioDeltaEventSchema>;
+export type SpeechAudioDoneEvent = z.infer<typeof speechAudioDoneEventSchema>;
+export type SpeechStreamErrorEvent = z.infer<typeof speechStreamErrorEventSchema>;
+export type SpeechStreamEvent = z.infer<typeof speechStreamEventSchema>;
+export type TranscriptionRequestFields = z.infer<typeof transcriptionRequestSchema>;
+export type TranscriptionJsonRequest = z.infer<typeof transcriptionJsonRequestSchema>;
+export type Transcription = z.infer<typeof transcriptionSchema>;