@kaana.ai/contracts 8.0.1 → 8.1.0

package/dist/internal/realtime.d.ts

@@ -108,6 +108,7 @@ export declare const realtimeSessionRequestSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -248,6 +249,7 @@ export declare const realtimeSessionCreatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -505,6 +507,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -581,6 +584,7 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -827,6 +831,16 @@ export declare const realtimeServerEventSchema: z.ZodDiscriminatedUnion<[z.ZodOb
     requestId: z.ZodString;
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
     responseId: z.ZodString;

package/dist/internal/realtime.js

@@ -11,7 +11,7 @@ import { inferenceTimestampSchema, modelReferenceSchema, requestIdSchema, } from
 import { usageQuantitySchema, usageSourceSchema } from '../public/money.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceFinishReasonSchema } from '../public/streamEvents.js';
-import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, } from '../public/realtime.js';
+import { MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandAcceptedEventSchema, realtimeCommandIdSchema, realtimeConfigIssues, realtimeInputAudioClearedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeItemAddedEventSchema, realtimeItemDeletedEventSchema, realtimeItemDoneEventSchema, realtimeItemTruncatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeResponseCreatedEventSchema, realtimeResponseIdSchema, realtimeResponseStatusSchema, realtimeSessionCloseReasonSchema, realtimeSessionConfigSchema, realtimeSessionLimitsSchema, realtimeSessionResumedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, realtimeTranscriptInterimEventSchema, } from '../public/realtime.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { inferenceErrorSchema } from './errors.js';
 import { deploymentIdSchema, inferenceProviderSlugSchema } from './identifiers.js';
@@ -165,6 +165,7 @@ export const realtimeServerEventSchema = z
     realtimeOutputAudioDoneEventSchema,
     realtimeTranscriptDeltaEventSchema,
     realtimeTranscriptDoneEventSchema,
+    realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
     realtimeResponseDoneEventSchema,

package/dist/public/realtime.d.ts

@@ -89,6 +89,7 @@ export declare const realtimeTurnDetectionSchema: z.ZodDiscriminatedUnion<[z.Zod
 export declare const realtimeInputTranscriptionSchema: z.ZodObject<{
     language: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
+    interimResults: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /** The target of a `translation` session. */
 export declare const realtimeTranslationSchema: z.ZodObject<{
@@ -153,6 +154,7 @@ export declare const realtimeSessionConfigSchema: z.ZodObject<{
     inputAudioTranscription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;
+        interimResults: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     translation: z.ZodOptional<z.ZodObject<{
         targetLanguage: z.ZodString;
@@ -210,6 +212,7 @@ export declare const realtimeSessionConfigUpdateSchema: z.ZodObject<{
     inputAudioTranscription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;
+        interimResults: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
         type: z.ZodLiteral<"function">;
@@ -369,6 +372,7 @@ export declare const realtimeSessionUpdateCommandSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -559,6 +563,7 @@ export declare const realtimeClientCommandSchema: z.ZodDiscriminatedUnion<[z.Zod
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
             type: z.ZodLiteral<"function">;
@@ -740,6 +745,7 @@ export declare const realtimeSessionUpdatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1017,6 +1023,24 @@ export declare const realtimeTranscriptDoneEventSchema: z.ZodObject<{
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The provisional text of an input item not yet final (contract set 8.1.0,
+ * Kaana ADR 0006): sent only to a `transcription` session that asked for
+ * `interimResults`. Each one REPLACES the item's previous interim text; it is
+ * display state, never settled and never part of the item's transcript, and
+ * the item's next `transcript.delta` or its `transcript.done` supersedes it.
+ */
+export declare const realtimeTranscriptInterimEventSchema: z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
 /** Written output of a response (`outputModalities` including `text`). */
 export declare const realtimeTextDeltaEventSchema: z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
@@ -1158,6 +1182,7 @@ export declare const realtimeSessionOpenSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1268,6 +1293,7 @@ export declare const realtimePublicSessionCreatedEventSchema: z.ZodObject<{
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1505,6 +1531,7 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1581,6 +1608,7 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
         inputAudioTranscription: z.ZodOptional<z.ZodObject<{
             language: z.ZodOptional<z.ZodString>;
             prompt: z.ZodOptional<z.ZodString>;
+            interimResults: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strict>>;
         translation: z.ZodOptional<z.ZodObject<{
             targetLanguage: z.ZodString;
@@ -1827,6 +1855,16 @@ export declare const realtimePublicServerEventSchema: z.ZodDiscriminatedUnion<[z
     requestId: z.ZodString;
     sequence: z.ZodNumber;
     commandId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"transcript.interim">;
+    source: z.ZodLiteral<"input_audio">;
+    itemId: z.ZodString;
+    contentIndex: z.ZodNumber;
+    text: z.ZodString;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    sequence: z.ZodNumber;
+    commandId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"text.delta">;
     responseId: z.ZodString;

package/dist/public/realtime.js

@@ -116,6 +116,12 @@ export const realtimeInputTranscriptionSchema = z
     language: z.string().check(minUtf16Length(2)).check(maxUtf16Length(35)).optional(),
     /** A hint — vocabulary or context — used where the model takes one. */
     prompt: z.string().check(maxUtf16Length(4_096)).optional(),
+    /**
+     * Send `transcript.interim`: the model's provisional text of the current
+     * item, about every half second, before any of it is final (contract set
+     * 8.1.0, Kaana ADR 0006). Only a `transcription` session sends it.
+     */
+    interimResults: z.boolean().optional(),
 })
     .strict();
 /** The target of a `translation` session. */
@@ -506,6 +512,21 @@ export const realtimeTranscriptDoneEventSchema = z.object({
     responseId: realtimeResponseIdSchema.optional(),
     transcript: z.string(),
 });
+/**
+ * The provisional text of an input item not yet final (contract set 8.1.0,
+ * Kaana ADR 0006): sent only to a `transcription` session that asked for
+ * `interimResults`. Each one REPLACES the item's previous interim text; it is
+ * display state, never settled and never part of the item's transcript, and
+ * the item's next `transcript.delta` or its `transcript.done` supersedes it.
+ */
+export const realtimeTranscriptInterimEventSchema = z.object({
+    ...eventBase,
+    type: z.literal('transcript.interim'),
+    source: z.literal('input_audio'),
+    itemId: realtimeItemIdSchema,
+    contentIndex: z.number().int().nonnegative().safe(),
+    text: z.string(),
+});
 /** Written output of a response (`outputModalities` including `text`). */
 export const realtimeTextDeltaEventSchema = z.object({
     ...eventBase,
@@ -599,6 +620,9 @@ export function realtimeConfigIssues(kind, config) {
             }
             break;
     }
+    if (kind !== 'transcription' && config.inputAudioTranscription?.interimResults === true) {
+        found(['inputAudioTranscription', 'interimResults'], 'only a transcription session sends interim text');
+    }
     if (config.toolChoice !== undefined && !hasTools) {
         found(['toolChoice'], 'a tool choice requires at least one tool definition');
     }
@@ -805,6 +829,7 @@ export const realtimePublicServerEventSchema = z
     realtimeOutputAudioDoneEventSchema,
     realtimeTranscriptDeltaEventSchema,
     realtimeTranscriptDoneEventSchema,
+    realtimeTranscriptInterimEventSchema,
     realtimeTextDeltaEventSchema,
     realtimeToolCallEventSchema,
     realtimePublicResponseDoneEventSchema,

package/dist/public/version.d.ts

@@ -100,7 +100,7 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export declare const INFERENCE_CONTRACT_VERSION = "8.0.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.1.0";
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:
@@ -181,6 +181,12 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.0.0";
  * envelopes v3 and v4 (`scopedExecutionSchema`, `privateAutoExecutionSchema`
  * and every shape under them) and a deployment's `scopedExecution`. A grant
  * or a request that parsed under 6.0.0 without them still parses the same.
+ *
+ * Contract set 8.1.0 (Kaana ADR 0006) is additive: a `transcription`
+ * session's `inputAudioTranscription.interimResults`, and the
+ * `transcript.interim` event it asks for, the provisional text of an input
+ * item that the item's deltas and its `transcript.done` supersede. Any other
+ * kind asking for interim text is refused. Nothing in 8.0.0 changes.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";

package/dist/public/version.js

@@ -100,7 +100,7 @@
  * change to, say, the catalogue reject every in-flight inference request; the
  * per-shape `schemaVersion` is what a message is validated against.
  */
-export const INFERENCE_CONTRACT_VERSION = '8.0.0';
+export const INFERENCE_CONTRACT_VERSION = '8.1.0';
 /**
  * Contract set 4.0.0 (Kaana ADR 0002) is the first published as
  * `@kaana.ai/contracts`. MAJOR because the set changed hands and split in two:
@@ -181,6 +181,12 @@ export const INFERENCE_CONTRACT_VERSION = '8.0.0';
  * envelopes v3 and v4 (`scopedExecutionSchema`, `privateAutoExecutionSchema`
  * and every shape under them) and a deployment's `scopedExecution`. A grant
  * or a request that parsed under 6.0.0 without them still parses the same.
+ *
+ * Contract set 8.1.0 (Kaana ADR 0006) is additive: a `transcription`
+ * session's `inputAudioTranscription.interimResults`, and the
+ * `transcript.interim` event it asks for, the provisional text of an input
+ * item that the item's deltas and its `transcript.done` supersede. Any other
+ * kind asking for interim text is refused. Nothing in 8.0.0 changes.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.0.0",
+    "version": "8.1.0",
     "description": "Kaana inference API. Generated from @kaana.ai/contracts; the Zod source is the authority. Accounts, applications, oxy_sk_ keys, limits and billing are managed in Oxy Console: https://console.oxy.so"
   },
   "servers": [
@@ -4470,6 +4470,9 @@
           "prompt": {
             "type": "string",
             "maxLength": 4096
+          },
+          "interimResults": {
+            "type": "boolean"
           }
         },
         "additionalProperties": false
@@ -5020,6 +5023,9 @@
           {
             "$ref": "#/components/schemas/RealtimeTranscriptDoneEvent"
           },
+          {
+            "$ref": "#/components/schemas/RealtimeTranscriptInterimEvent"
+          },
           {
             "$ref": "#/components/schemas/RealtimeTextDeltaEvent"
           },
@@ -5945,6 +5951,55 @@
           "transcript"
         ]
       },
+      "RealtimeTranscriptInterimEvent": {
+        "type": "object",
+        "properties": {
+          "schemaVersion": {
+            "type": "number",
+            "const": 1
+          },
+          "requestId": {
+            "$ref": "#/components/schemas/RequestId"
+          },
+          "sequence": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "commandId": {
+            "$ref": "#/components/schemas/RealtimeCommandId"
+          },
+          "type": {
+            "type": "string",
+            "const": "transcript.interim"
+          },
+          "source": {
+            "type": "string",
+            "const": "input_audio"
+          },
+          "itemId": {
+            "$ref": "#/components/schemas/RealtimeItemId"
+          },
+          "contentIndex": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "text": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "schemaVersion",
+          "requestId",
+          "sequence",
+          "type",
+          "source",
+          "itemId",
+          "contentIndex",
+          "text"
+        ]
+      },
       "RealtimeTranscriptSource": {
         "type": "string",
         "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "8.0.1",
+  "version": "8.1.0",
   "description": "Kaana inference contract: the Zod schemas of the public API at https://kaana.ai/v1 and, under /internal, of the Oxy-Kaana grant, settlement and signed lane.",
   "type": "module",
   "sideEffects": false,