@kaana.ai/contracts 0.0.0-stage → 4.3.0

package/dist/public/audio.js

@@ -0,0 +1,236 @@
+/**
+ * `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 { audioInputMediaTypeSchema, languageTagSchema, speechFormatSchema, speechMediaType, } from './audioFormats.js';
+import { publicErrorSchema } from './errors.js';
+import { modelReferenceSchema, PADDED_BASE64_PATTERN, requestIdSchema } from './identifiers.js';
+import { usageSchema } from './money.js';
+/* -------------------------------------------------------------------------- */
+/*  Speech                                                                     */
+/* -------------------------------------------------------------------------- */
+/** The longest text one speech request may carry, before any model's own limit. */
+export const MAX_SPEECH_INPUT_CHARACTERS = 100_000;
+/**
+ * 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 const speechStreamFormatSchema = z.enum(['audio', '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 const STREAMABLE_SPEECH_FORMATS = ['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 const speechRequestSchema = z
+    .object({
+    model: modelReferenceSchema,
+    /** Bounded so one request cannot drive the hold arbitrarily high. */
+    input: z.string().min(1).max(MAX_SPEECH_INPUT_CHARACTERS),
+    voice: z.string().min(1).max(64),
+    /** Absent means `mp3`. */
+    response_format: speechFormatSchema.optional(),
+    /** The contract's outer bound; each model publishes its own range. */
+    speed: z.number().min(0.25).max(4).optional(),
+    stream: z.boolean().optional(),
+    /** Only with `stream: true`. Absent means `audio`. */
+    stream_format: speechStreamFormatSchema.optional(),
+    /** OpenAI's end-user attribution field: the delegated user id, attribution only. */
+    user: z.string().min(1).max(64).optional(),
+})
+    .strict()
+    .superRefine((request, ctx) => {
+    if (request.stream_format !== undefined && request.stream !== true) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['stream_format'],
+            message: 'stream_format applies only to a streamed request (stream: true)',
+        });
+    }
+    const format = request.response_format ?? 'mp3';
+    if (request.stream === true &&
+        !STREAMABLE_SPEECH_FORMATS.includes(format)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['response_format'],
+            message: `streamed speech is ${STREAMABLE_SPEECH_FORMATS.join(' or ')}; ${format} exists only whole`,
+        });
+    }
+});
+/** One chunk of audio, in order, as soon as the provider produced it. */
+export const speechAudioDeltaEventSchema = z
+    .object({
+    type: z.literal('speech.audio.delta'),
+    /** Standard padded base64 of at most 49 152 bytes of audio. */
+    audio: z.string().min(4).max(65_536).regex(PADDED_BASE64_PATTERN),
+})
+    .strict();
+/** The last event of a successful stream: what served it and what it consumed. */
+export const speechAudioDoneEventSchema = z
+    .object({
+    type: z.literal('speech.audio.done'),
+    requestId: requestIdSchema,
+    /** The revision that actually served the request. */
+    model: modelReferenceSchema,
+    usage: usageSchema,
+})
+    .strict();
+/** The terminal failure of a stream, after which nothing follows. */
+export const speechStreamErrorEventSchema = z
+    .object({
+    type: z.literal('error'),
+    error: publicErrorSchema,
+})
+    .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 const speechStreamEventSchema = z.discriminatedUnion('type', [
+    speechAudioDeltaEventSchema,
+    speechAudioDoneEventSchema,
+    speechStreamErrorEventSchema,
+]);
+/**
+ * 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 function checkSpeechRequest(request, audio) {
+    const issues = [];
+    if (audio.maxInputCharacters !== undefined && request.input.length > audio.maxInputCharacters) {
+        issues.push({
+            param: 'input',
+            message: `input is ${request.input.length} characters; this model reads at most ${audio.maxInputCharacters}`,
+        });
+    }
+    if (!audio.voices.some((voice) => voice.id === request.voice)) {
+        issues.push({ param: 'voice', message: `this model has no voice ${request.voice}` });
+    }
+    const format = request.response_format ?? 'mp3';
+    if (!audio.audioFormats.output.includes(speechMediaType(format))) {
+        issues.push({ param: 'response_format', message: `this model does not produce ${format}` });
+    }
+    if (request.speed !== undefined) {
+        if (audio.speed === undefined) {
+            issues.push({ param: 'speed', message: 'this model accepts no speed control' });
+        }
+        else if (request.speed < audio.speed.min || request.speed > audio.speed.max) {
+            issues.push({
+                param: 'speed',
+                message: `speed must be between ${audio.speed.min} and ${audio.speed.max} for this model`,
+            });
+        }
+    }
+    return issues;
+}
+/* -------------------------------------------------------------------------- */
+/*  Transcription                                                              */
+/* -------------------------------------------------------------------------- */
+/** The largest audio file one transcription request may upload: 20 MiB. */
+export const MAX_TRANSCRIPTION_FILE_BYTES = 20 * 1024 * 1024;
+/**
+ * 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 const transcriptionRequestSchema = z
+    .object({
+    model: modelReferenceSchema,
+    /** The spoken language, when known; validated against the model's `audio.languages`. */
+    language: languageTagSchema.optional(),
+    /** Vocabulary or context that helps the model; never an instruction. */
+    prompt: z.string().max(4096).optional(),
+    /** Absent means `none`. */
+    timestamps: z.enum(['none', 'segment', 'word']).optional(),
+})
+    .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 const MAX_TRANSCRIPTION_AUDIO_MILLISECONDS = 30 * 60 * 1000;
+/**
+ * The longest padded base64 the JSON form may carry: exactly the encoding of
+ * {@link MAX_TRANSCRIPTION_FILE_BYTES}.
+ */
+export const MAX_TRANSCRIPTION_AUDIO_BASE64_LENGTH = Math.ceil(MAX_TRANSCRIPTION_FILE_BYTES / 3) * 4;
+/**
+ * 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 const transcriptionJsonRequestSchema = transcriptionRequestSchema
+    .extend({
+    audio: z
+        .object({
+        mediaType: audioInputMediaTypeSchema,
+        data: z
+            .string()
+            .min(4)
+            .max(MAX_TRANSCRIPTION_AUDIO_BASE64_LENGTH)
+            .regex(PADDED_BASE64_PATTERN),
+    })
+        .strict(),
+})
+    .strict();
+const timedSpanFields = {
+    startMs: z.number().int().nonnegative().safe(),
+    endMs: z.number().int().nonnegative().safe(),
+};
+/** The response. Segments or words are present only when the request asked for them. */
+export const transcriptionSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    requestId: requestIdSchema,
+    /** The revision that actually served the request. */
+    model: modelReferenceSchema,
+    text: z.string(),
+    /** The language the model heard, when it reports one. */
+    language: languageTagSchema.optional(),
+    durationMs: z.number().int().nonnegative().safe().optional(),
+    segments: z.array(z.object({ ...timedSpanFields, text: z.string() }).strict()).optional(),
+    words: z.array(z.object({ ...timedSpanFields, word: z.string() }).strict()).optional(),
+    usage: usageSchema,
+})
+    .strict()
+    .superRefine((transcription, ctx) => {
+    for (const field of ['segments', 'words']) {
+        for (const [index, span] of (transcription[field] ?? []).entries()) {
+            if (span.endMs < span.startMs) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [field, index, 'endMs'],
+                    message: 'a span cannot end before it starts',
+                });
+            }
+        }
+    }
+});

package/dist/public/audioFormats.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The audio vocabulary shared by the catalogue and the audio endpoints:
+ * language tags, the media types a transcription accepts, and the mapping from
+ * a speech request's `response_format` to the media type it produces.
+ *
+ * New in contract set 4.0.0 (Kaana ADR 0002, decisions 8 and 9).
+ */
+import { z } from 'zod';
+import { type InferenceAudioMediaType } from './streamEvents.js';
+/**
+ * A BCP 47 language tag (`en`, `es-ES`, `zh-Hant-TW`), as voices, models and
+ * transcription requests declare languages. Validated by its grammar only: the
+ * catalogue is the authority on which tags a model accepts.
+ */
+export declare const languageTagSchema: z.ZodString;
+/** The formats a speech request names in `response_format`. */
+export declare const speechFormatSchema: z.ZodEnum<{
+    mp3: "mp3";
+    opus: "opus";
+    aac: "aac";
+    flac: "flac";
+    wav: "wav";
+    pcm: "pcm";
+}>;
+/**
+ * The media types an uploaded audio file may have
+ * (`POST /v1/audio/transcriptions`).
+ */
+export declare const audioInputMediaTypeSchema: 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";
+}>;
+/**
+ * The audio encodings a realtime session carries, in both directions. Named by
+ * what they ARE (sample format, rate) because a realtime stream has no
+ * container to say so.
+ *
+ * Declared here rather than in `realtime.ts` (where it was until contract set
+ * 4.1.0) because the catalogue publishes which of them a model takes, and the
+ * catalogue cannot import the realtime module that imports it.
+ */
+export declare const realtimeAudioFormatSchema: z.ZodEnum<{
+    pcm16_24khz: "pcm16_24khz";
+    g711_ulaw: "g711_ulaw";
+    g711_alaw: "g711_alaw";
+}>;
+/**
+ * The media type a speech request's `response_format` produces. A client
+ * knows it before the first byte, which is why the speech stream events do
+ * not repeat it.
+ */
+export declare function speechMediaType(format: z.infer<typeof speechFormatSchema>): InferenceAudioMediaType;
+export type LanguageTag = z.infer<typeof languageTagSchema>;
+export type SpeechFormat = z.infer<typeof speechFormatSchema>;
+export type AudioInputMediaType = z.infer<typeof audioInputMediaTypeSchema>;
+export type RealtimeAudioFormat = z.infer<typeof realtimeAudioFormatSchema>;
+/** The media types speech produces; the contract calls the same set `inferenceAudioMediaTypeSchema`. */
+export type AudioMediaType = InferenceAudioMediaType;

package/dist/public/audioFormats.js

@@ -0,0 +1,60 @@
+/**
+ * The audio vocabulary shared by the catalogue and the audio endpoints:
+ * language tags, the media types a transcription accepts, and the mapping from
+ * a speech request's `response_format` to the media type it produces.
+ *
+ * New in contract set 4.0.0 (Kaana ADR 0002, decisions 8 and 9).
+ */
+import { z } from 'zod';
+import { inferenceAudioMediaTypeSchema } from './streamEvents.js';
+/**
+ * A BCP 47 language tag (`en`, `es-ES`, `zh-Hant-TW`), as voices, models and
+ * transcription requests declare languages. Validated by its grammar only: the
+ * catalogue is the authority on which tags a model accepts.
+ */
+export const languageTagSchema = z
+    .string()
+    .max(35)
+    .regex(/^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/, 'must be a BCP 47 language tag');
+/** The formats a speech request names in `response_format`. */
+export const speechFormatSchema = z.enum(['mp3', 'opus', 'aac', 'flac', 'wav', 'pcm']);
+/**
+ * The media types an uploaded audio file may have
+ * (`POST /v1/audio/transcriptions`).
+ */
+export const audioInputMediaTypeSchema = z.enum([
+    'audio/mpeg',
+    'audio/mp4',
+    'audio/wav',
+    'audio/ogg',
+    'audio/webm',
+    'audio/flac',
+    'audio/aac',
+    'audio/pcm',
+]);
+/**
+ * The audio encodings a realtime session carries, in both directions. Named by
+ * what they ARE (sample format, rate) because a realtime stream has no
+ * container to say so.
+ *
+ * Declared here rather than in `realtime.ts` (where it was until contract set
+ * 4.1.0) because the catalogue publishes which of them a model takes, and the
+ * catalogue cannot import the realtime module that imports it.
+ */
+export const realtimeAudioFormatSchema = z.enum(['pcm16_24khz', 'g711_ulaw', 'g711_alaw']);
+const SPEECH_MEDIA_TYPES = {
+    mp3: 'audio/mpeg',
+    opus: 'audio/ogg',
+    aac: 'audio/aac',
+    flac: 'audio/flac',
+    wav: 'audio/wav',
+    pcm: 'audio/pcm',
+};
+/**
+ * The media type a speech request's `response_format` produces. A client
+ * knows it before the first byte, which is why the speech stream events do
+ * not repeat it.
+ */
+export function speechMediaType(format) {
+    return inferenceAudioMediaTypeSchema.parse(SPEECH_MEDIA_TYPES[format]);
+}