@kaana.ai/contracts 0.0.0-stage → 4.3.0

package/dist/public/responses.d.ts

@@ -0,0 +1,253 @@
+/**
+ * `POST /v1/responses` — Kaana's own dialect, and the preferred endpoint.
+ *
+ * Moved from the Oxy edge (`packages/api/src/schemas/inferenceEdge.schemas.ts`,
+ * `responsesRequestSchema` and `responsesResponseSchema`) by Kaana ADR 0002.
+ * Two changes, both from the ADR: `model` names a model reference or a power
+ * level and nothing else (Oxy's `routingProfile`/`routingProfileId` were Oxy
+ * catalogue identities), and the response names no serving provider.
+ */
+import { z } from 'zod';
+/**
+ * What a `model` field may name: a concrete model reference
+ * (`publisher/model[@revision]`, served or refused, never substituted) or a
+ * power level (`auto`, `instant`, … — no `/`, so the two are decidable from
+ * the string alone).
+ */
+export declare const modelTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+    medium: "medium";
+    high: "high";
+    auto: "auto";
+    instant: "instant";
+    xhigh: "xhigh";
+    pro: "pro";
+    ultra: "ultra";
+}>]>;
+/**
+ * The request. `model` may be absent: the application's routing policy in Oxy
+ * Console may name a default target, and the request is refused only when it
+ * names none either.
+ *
+ * `.strict()`: a field Kaana does not implement is refused rather than
+ * silently ignored, so nobody is billed for a request that dropped half of
+ * what it asked for.
+ */
+export declare const responsesRequestSchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodEnum<{
+        medium: "medium";
+        high: "high";
+        auto: "auto";
+        instant: "instant";
+        xhigh: "xhigh";
+        pro: "pro";
+        ultra: "ultra";
+    }>]>>;
+    input: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            user: "user";
+            system: "system";
+            developer: "developer";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+            detail: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                auto: "auto";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"audio">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+            filename: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"refusal">;
+            text: z.ZodString;
+        }, z.core.$strict>], "type">>;
+        name: z.ZodOptional<z.ZodString>;
+        toolCallId: z.ZodOptional<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>]>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    stream: z.ZodOptional<z.ZodBoolean>;
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    topK: z.ZodOptional<z.ZodNumber>;
+    frequencyPenalty: z.ZodOptional<z.ZodNumber>;
+    presencePenalty: z.ZodOptional<z.ZodNumber>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    stopSequences: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        strict: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>>;
+    toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+        auto: "auto";
+        none: "none";
+        required: "required";
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"function">;
+        name: z.ZodString;
+    }, z.core.$strict>]>>;
+    responseFormat: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"text">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"json_object">;
+    }, z.core.$strict>, z.ZodObject<{
+        type: z.ZodLiteral<"json_schema">;
+        name: z.ZodString;
+        schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        strict: z.ZodBoolean;
+    }, z.core.$strict>], "type">>;
+    reasoning: z.ZodOptional<z.ZodObject<{
+        effort: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+    }, z.core.$strict>>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    clientRequestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * The non-streaming body. A streamed request answers with
+ * `responseStreamEventSchema` frames instead.
+ */
+export declare const responseSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    generationId: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+    finishReason: z.ZodEnum<{
+        content_filter: "content_filter";
+        cancelled: "cancelled";
+        refusal: "refusal";
+        stop: "stop";
+        length: "length";
+        tool_calls: "tool_calls";
+    }>;
+    output: z.ZodArray<z.ZodObject<{
+        role: z.ZodEnum<{
+            user: "user";
+            system: "system";
+            developer: "developer";
+            assistant: "assistant";
+            tool: "tool";
+        }>;
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+            detail: z.ZodOptional<z.ZodEnum<{
+                low: "low";
+                high: "high";
+                auto: "auto";
+            }>>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"audio">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"file">;
+            source: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"inline">;
+                mediaType: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strict>], "kind">;
+            filename: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodObject<{
+            type: z.ZodLiteral<"refusal">;
+            text: z.ZodString;
+        }, z.core.$strict>], "type">>;
+        name: z.ZodOptional<z.ZodString>;
+        toolCallId: z.ZodOptional<z.ZodString>;
+        toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            name: z.ZodString;
+            arguments: z.ZodString;
+        }, z.core.$strict>>>;
+    }, 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>>;
+    routingPolicy: z.ZodObject<{
+        routingPolicyId: z.ZodString;
+        policyVersion: z.ZodNumber;
+    }, z.core.$strict>;
+    latencyMs: z.ZodNumber;
+}, z.core.$strict>;
+export type ModelTarget = z.infer<typeof modelTargetSchema>;
+export type ResponsesRequest = z.infer<typeof responsesRequestSchema>;
+export type Response = z.infer<typeof responseSchema>;

package/dist/public/responses.js

@@ -0,0 +1,95 @@
+/**
+ * `POST /v1/responses` — Kaana's own dialect, and the preferred endpoint.
+ *
+ * Moved from the Oxy edge (`packages/api/src/schemas/inferenceEdge.schemas.ts`,
+ * `responsesRequestSchema` and `responsesResponseSchema`) by Kaana ADR 0002.
+ * Two changes, both from the ADR: `model` names a model reference or a power
+ * level and nothing else (Oxy's `routingProfile`/`routingProfileId` were Oxy
+ * catalogue identities), and the response names no serving provider.
+ */
+import { z } from 'zod';
+import { powerLevelSchema } from './catalogue.js';
+import { generationIdSchema, modelReferenceSchema, requestIdSchema } from './identifiers.js';
+import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, responseFormatSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
+import { usageQuantitySchema } from './money.js';
+import { routingPolicyReferenceSchema } from './policy.js';
+import { inferenceFinishReasonSchema } from './streamEvents.js';
+/**
+ * What a `model` field may name: a concrete model reference
+ * (`publisher/model[@revision]`, served or refused, never substituted) or a
+ * power level (`auto`, `instant`, … — no `/`, so the two are decidable from
+ * the string alone).
+ */
+export const modelTargetSchema = z.union([modelReferenceSchema, powerLevelSchema]);
+/** The message-or-text input `/v1/responses` accepts. */
+const responsesInputSchema = z.union([z.string().min(1), z.array(inferenceMessageSchema).min(1)]);
+/**
+ * The request. `model` may be absent: the application's routing policy in Oxy
+ * Console may name a default target, and the request is refused only when it
+ * names none either.
+ *
+ * `.strict()`: a field Kaana does not implement is refused rather than
+ * silently ignored, so nobody is billed for a request that dropped half of
+ * what it asked for.
+ */
+export const responsesRequestSchema = z
+    .object({
+    model: modelTargetSchema.optional(),
+    input: responsesInputSchema,
+    maxOutputTokens: z.number().int().positive().safe().optional(),
+    stream: z.boolean().optional(),
+    temperature: z.number().min(0).max(2).optional(),
+    topP: z.number().min(0).max(1).optional(),
+    topK: z.number().int().positive().safe().optional(),
+    frequencyPenalty: z.number().min(-2).max(2).optional(),
+    presencePenalty: z.number().min(-2).max(2).optional(),
+    seed: z.number().int().safe().optional(),
+    stopSequences: z.array(z.string().min(1).max(256)).max(8).optional(),
+    tools: z.array(toolDefinitionSchema).max(128).optional(),
+    toolChoice: toolChoiceSchema.optional(),
+    responseFormat: responseFormatSchema.optional(),
+    /** Refused when the resolved model does not advertise the effort. */
+    reasoning: inferenceReasoningSchema.optional(),
+    labels: requestLabelsSchema.optional(),
+    /** The caller's own correlation id, echoed on the response. */
+    clientRequestId: z.string().min(1).max(128).optional(),
+})
+    .strict()
+    .superRefine((request, ctx) => {
+    if (request.toolChoice !== undefined && (request.tools ?? []).length === 0) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['toolChoice'],
+            message: 'a tool choice requires at least one tool definition',
+        });
+    }
+    const names = (request.tools ?? []).map((tool) => tool.name);
+    if (new Set(names).size !== names.length) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['tools'],
+            message: 'tool names must be unique within one request',
+        });
+    }
+});
+/**
+ * The non-streaming body. A streamed request answers with
+ * `responseStreamEventSchema` frames instead.
+ */
+export const responseSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    requestId: requestIdSchema,
+    /** Absent when no generation id was reported for the request. */
+    generationId: generationIdSchema.optional(),
+    /** The revision that actually served the request, which may differ from the ask. */
+    model: modelReferenceSchema,
+    finishReason: inferenceFinishReasonSchema,
+    output: z.array(inferenceMessageSchema),
+    usage: z.array(usageQuantitySchema),
+    /** The customer's own routing-policy revision that served it. */
+    routingPolicy: routingPolicyReferenceSchema,
+    /** Kaana's own measurement of the request, in whole milliseconds. */
+    latencyMs: z.number().int().nonnegative(),
+})
+    .strict();