@kaana.ai/contracts 0.0.0-stage → 4.4.0

package/dist/public/decisions.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Structured decisions (`POST /v1/decisions`).
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/decisions.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+export declare const decisionEffortSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    instant: "instant";
+    xhigh: "xhigh";
+}>;
+export declare const decisionQuestionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"choice">;
+    options: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+    question: z.ZodString;
+    criteria: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"score">;
+    levels: z.ZodArray<z.ZodString>;
+    id: z.ZodString;
+    question: z.ZodString;
+    criteria: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"noul">;
+    id: z.ZodString;
+    question: z.ZodString;
+    criteria: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>], "kind">;
+/**
+ * Conservative serialized input accounting, including escaping and structure.
+ * Measures both the normalized payload and the provider's structured-question
+ * representation. Common instructions repeat per question there. A 255-byte
+ * model identity and 4096-byte gateway-policy allowance bound adapter metadata.
+ * Kaana must also check its final serialized body before sending it.
+ */
+export declare function decisionInputBudget(payload: DecisionInput): {
+    total: number;
+    context: number;
+    gateway: number;
+};
+/** OpenRouter's TOTAL limit is separate from direct state-plus-longest context. */
+export declare function decisionFitsGateway(payload: DecisionInput): boolean;
+export declare const decisionInputSchema: z.ZodObject<{
+    state: z.ZodString;
+    instructions: z.ZodOptional<z.ZodString>;
+    questions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"choice">;
+        options: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"score">;
+        levels: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"noul">;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        instant: "instant";
+        xhigh: "xhigh";
+    }>>;
+}, z.core.$strict>;
+export declare const decisionRequestSchema: z.ZodObject<{
+    state: z.ZodString;
+    instructions: z.ZodOptional<z.ZodString>;
+    questions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"choice">;
+        options: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"score">;
+        levels: z.ZodArray<z.ZodString>;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        kind: z.ZodLiteral<"noul">;
+        id: z.ZodString;
+        question: z.ZodString;
+        criteria: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>], "kind">>;
+    effort: z.ZodOptional<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        instant: "instant";
+        xhigh: "xhigh";
+    }>>;
+    model: z.ZodString;
+}, z.core.$strict>;
+export declare const decisionAnswerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"choice">;
+    reply: z.ZodString;
+    confidence: z.ZodNumber;
+    probabilities: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"score">;
+    reply: z.ZodNumber;
+    confidence: z.ZodNumber;
+    mean: z.ZodNumber;
+    distribution: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    kind: z.ZodLiteral<"noul">;
+    probability: z.ZodNumber;
+}, z.core.$strict>], "kind">;
+export declare const decisionSuccessSchema: z.ZodObject<{
+    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>;
+    schemaVersion: z.ZodLiteral<1>;
+    requestId: z.ZodString;
+    model: z.ZodString;
+    data: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"choice">;
+        reply: z.ZodString;
+        confidence: z.ZodNumber;
+        probabilities: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"score">;
+        reply: z.ZodNumber;
+        confidence: z.ZodNumber;
+        mean: z.ZodNumber;
+        distribution: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        kind: z.ZodLiteral<"noul">;
+        probability: z.ZodNumber;
+    }, z.core.$strict>], "kind">>;
+}, z.core.$strict>;
+/** Bind output to the exact request. Provider order is not semantic. */
+export declare function decisionAnswersMatch(input: DecisionInput, answers: readonly DecisionAnswer[]): boolean;
+export type DecisionQuestion = z.infer<typeof decisionQuestionSchema>;
+export type DecisionInput = {
+    state: string;
+    instructions?: string;
+    questions: DecisionQuestion[];
+    effort?: z.infer<typeof decisionEffortSchema>;
+};
+export type DecisionRequest = z.infer<typeof decisionRequestSchema>;
+export type DecisionAnswer = z.infer<typeof decisionAnswerSchema>;
+export type DecisionSuccess = z.infer<typeof decisionSuccessSchema>;

package/dist/public/decisions.js

@@ -0,0 +1,257 @@
+/**
+ * Structured decisions (`POST /v1/decisions`).
+ *
+ * Moved from `@oxy.so/contracts` 4.12.0 (`src/inference/decisions.ts`) by Kaana ADR 0002.
+ */
+import { z } from 'zod';
+import { modelReferenceSchema, requestIdSchema } from './identifiers.js';
+import { usageQuantitySchema } from './money.js';
+import { routingPolicyReferenceSchema } from './policy.js';
+const probability = z.number().finite().min(0).max(1);
+const text = z.string().min(1).max(65536);
+const id = z.string().min(1).max(128);
+const tolerance = 1e-6;
+export const decisionEffortSchema = z.enum(['instant', 'low', 'medium', 'high', 'xhigh']);
+const common = { id, question: text, criteria: text.optional() };
+export const decisionQuestionSchema = z.discriminatedUnion('kind', [
+    z
+        .object({
+        ...common,
+        kind: z.literal('choice'),
+        options: z.array(text).min(2).max(255),
+    })
+        .strict(),
+    z
+        .object({
+        ...common,
+        kind: z.literal('score'),
+        levels: z.array(text).min(2).max(10),
+    })
+        .strict(),
+    z.object({ ...common, kind: z.literal('noul') }).strict(),
+]);
+const payloadFields = {
+    state: z.string().max(65536),
+    instructions: text.optional(),
+    questions: z.array(decisionQuestionSchema).min(1).max(255),
+    effort: decisionEffortSchema.optional(),
+};
+/**
+ * Conservative serialized input accounting, including escaping and structure.
+ * Measures both the normalized payload and the provider's structured-question
+ * representation. Common instructions repeat per question there. A 255-byte
+ * model identity and 4096-byte gateway-policy allowance bound adapter metadata.
+ * Kaana must also check its final serialized body before sending it.
+ */
+export function decisionInputBudget(payload) {
+    const bytes = (value) => new TextEncoder().encode(JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, '0')}`)).length;
+    const model = 'x'.repeat(255);
+    const measure = (questions) => {
+        const wireQuestions = Object.fromEntries(questions.map((q) => [
+            q.id,
+            {
+                type: q.kind,
+                instructions: {
+                    question: q.question,
+                    ...(payload.instructions === undefined ? {} : { instructions: payload.instructions }),
+                    ...(q.criteria === undefined ? {} : { criteria: q.criteria }),
+                },
+                ...(q.kind === 'choice'
+                    ? { criteria: Object.fromEntries(q.options.map((label) => [label, null])) }
+                    : q.kind === 'score'
+                        ? { criteria: q.levels }
+                        : {}),
+            },
+        ]));
+        return Math.max(bytes({ ...payload, model, questions }), bytes({
+            model,
+            state: payload.state,
+            questions: wireQuestions,
+            ...(payload.effort === undefined ? {} : { effort: payload.effort }),
+        }));
+    };
+    const total = measure(payload.questions);
+    return {
+        total,
+        context: Math.max(...payload.questions.map((q) => measure([q]))),
+        gateway: total + 4096,
+    };
+}
+/** OpenRouter's TOTAL limit is separate from direct state-plus-longest context. */
+export function decisionFitsGateway(payload) {
+    return decisionInputBudget(payload).gateway <= 32000;
+}
+/** JSON permits escaped lone UTF-16 units; Go replaces them after decoding. */
+function hasUnpairedSurrogate(value) {
+    for (let i = 0; i < value.length; i++) {
+        const unit = value.charCodeAt(i);
+        if (unit >= 0xd800 && unit <= 0xdbff) {
+            const next = value.charCodeAt(i + 1);
+            if (!(next >= 0xdc00 && next <= 0xdfff))
+                return true;
+            i++;
+        }
+        else if (unit >= 0xdc00 && unit <= 0xdfff)
+            return true;
+    }
+    return false;
+}
+function validateInput(payload, ctx) {
+    const fields = [
+        { value: payload.state, path: ['state'] },
+        { value: payload.instructions, path: ['instructions'] },
+    ];
+    for (const [index, question] of payload.questions.entries()) {
+        for (const field of ['id', 'question', 'criteria']) {
+            fields.push({ value: question[field], path: ['questions', index, field] });
+        }
+        if (question.kind === 'choice' || question.kind === 'score') {
+            const field = question.kind === 'choice' ? 'options' : 'levels';
+            const labels = question.kind === 'choice' ? question.options : question.levels;
+            for (const [labelIndex, value] of labels.entries()) {
+                fields.push({ value, path: ['questions', index, field, labelIndex] });
+            }
+        }
+    }
+    let invalidUnicode = false;
+    for (const { value, path } of fields) {
+        if (value !== undefined && hasUnpairedSurrogate(value)) {
+            invalidUnicode = true;
+            ctx.addIssue({
+                code: 'custom',
+                path,
+                message: 'Decisions require paired UTF-16 surrogates.',
+            });
+        }
+    }
+    // Reject before measuring/reserving text that the execution runtime would change.
+    if (invalidUnicode)
+        return;
+    if (new Set(payload.questions.map((q) => q.id)).size !== payload.questions.length)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['questions'],
+            message: 'Question IDs must be unique.',
+        });
+    for (const [index, question] of payload.questions.entries()) {
+        const labels = question.kind === 'choice'
+            ? question.options
+            : question.kind === 'score'
+                ? question.levels
+                : [];
+        if (new Set(labels).size !== labels.length)
+            ctx.addIssue({
+                code: 'custom',
+                path: ['questions', index],
+                message: 'Options and levels must be unique.',
+            });
+    }
+    const budget = decisionInputBudget(payload);
+    if (budget.total > 64000 || budget.context > 32000)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['state'],
+            message: 'Decisions exceed the serialized 64000-byte total or 32000-byte per-question context budget.',
+        });
+}
+export const decisionInputSchema = z.object(payloadFields).strict().superRefine(validateInput);
+export const decisionRequestSchema = z
+    .object({
+    model: modelReferenceSchema.refine((model) => model.includes('@'), 'Decisions require a revision-pinned model.'),
+    ...payloadFields,
+})
+    .strict()
+    .superRefine(validateInput);
+export const decisionAnswerSchema = z
+    .discriminatedUnion('kind', [
+    z
+        .object({
+        id,
+        kind: z.literal('choice'),
+        /** Actual provider-selected option. Never reconstructed from probabilities. */
+        reply: text,
+        /** Provider-returned confidence, not a correctness probability. */
+        confidence: probability,
+        probabilities: z.array(probability).min(2).max(255),
+    })
+        .strict(),
+    z
+        .object({
+        id,
+        kind: z.literal('score'),
+        /** Actual provider score. Kept separate from the validated expected index. */
+        reply: z.number().finite().min(0).max(9),
+        confidence: probability,
+        mean: z.number().finite().min(0).max(9),
+        distribution: z.array(probability).min(2).max(10),
+    })
+        .strict(),
+    z.object({ id, kind: z.literal('noul'), probability }).strict(),
+])
+    .superRefine((answer, ctx) => {
+    if (answer.kind === 'noul')
+        return;
+    if (answer.kind === 'score' && Math.abs(answer.reply - answer.mean) > tolerance) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['reply'],
+            message: 'Provider score must match the expected level index.',
+        });
+    }
+    const distribution = answer.kind === 'choice' ? answer.probabilities : answer.distribution;
+    if (Math.abs(distribution.reduce((sum, value) => sum + value, 0) - 1) > tolerance)
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Probabilities must sum to one.',
+        });
+    if (answer.kind === 'score' &&
+        Math.abs(distribution.reduce((sum, value, index) => sum + index * value, 0) - answer.mean) >
+            tolerance)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['mean'],
+            message: 'Mean must equal the expected zero-based level index.',
+        });
+});
+const resultFields = {
+    schemaVersion: z.literal(1),
+    requestId: requestIdSchema,
+    model: modelReferenceSchema.refine((model) => model.includes('@'), 'Decisions require an immutable model revision.'),
+    data: z.array(decisionAnswerSchema).min(1).max(255),
+};
+function uniqueAnswers(result, ctx) {
+    if (new Set(result.data.map((answer) => answer.id)).size !== result.data.length)
+        ctx.addIssue({
+            code: 'custom',
+            path: ['data'],
+            message: 'Answer IDs must be unique.',
+        });
+}
+export const decisionSuccessSchema = z
+    .object({
+    ...resultFields,
+    usage: z.array(usageQuantitySchema),
+    routingPolicy: routingPolicyReferenceSchema,
+})
+    .strict()
+    .superRefine(uniqueAnswers);
+/** Bind output to the exact request. Provider order is not semantic. */
+export function decisionAnswersMatch(input, answers) {
+    if (answers.length !== input.questions.length ||
+        new Set(answers.map((a) => a.id)).size !== answers.length)
+        return false;
+    return input.questions.every((question) => {
+        const answer = answers.find((candidate) => candidate.id === question.id);
+        if (!answer || !decisionAnswerSchema.safeParse(answer).success || answer.kind !== question.kind)
+            return false;
+        if (question.kind === 'choice' && answer.kind === 'choice') {
+            const index = question.options.indexOf(answer.reply);
+            return (question.options.length === answer.probabilities.length &&
+                index >= 0 &&
+                answer.probabilities[index] + tolerance >= Math.max(...answer.probabilities));
+        }
+        if (question.kind === 'score' && answer.kind === 'score')
+            return question.levels.length === answer.distribution.length;
+        return question.kind === 'noul';
+    });
+}

package/dist/public/embeddings.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `POST /v1/embeddings` — OpenAI-compatible, so a stock OpenAI client works
+ * against `https://kaana.ai/v1`.
+ *
+ * New in contract set 4.0.0 (Kaana ADR 0002, decision 7). The signed-lane
+ * result Kaana already produced (`embeddingSuccessSchema` in `/internal`)
+ * bounds what this surface can promise: at most 2048 inputs per request and
+ * vectors of at most 1024 dimensions.
+ */
+import { z } from 'zod';
+/** The most inputs one request may embed. */
+export declare const MAX_EMBEDDING_INPUTS = 2048;
+export declare const embeddingsRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    input: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    encoding_format: z.ZodOptional<z.ZodLiteral<"float">>;
+    dimensions: z.ZodOptional<z.ZodNumber>;
+    user: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const embeddingsResponseSchema: z.ZodObject<{
+    object: z.ZodLiteral<"list">;
+    data: z.ZodArray<z.ZodObject<{
+        object: z.ZodLiteral<"embedding">;
+        index: z.ZodNumber;
+        embedding: z.ZodArray<z.ZodNumber>;
+    }, z.core.$strict>>;
+    model: z.ZodString;
+    usage: z.ZodObject<{
+        prompt_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type EmbeddingsRequest = z.infer<typeof embeddingsRequestSchema>;
+export type EmbeddingsResponse = z.infer<typeof embeddingsResponseSchema>;

package/dist/public/embeddings.js

@@ -0,0 +1,66 @@
+/**
+ * `POST /v1/embeddings` — OpenAI-compatible, so a stock OpenAI client works
+ * against `https://kaana.ai/v1`.
+ *
+ * New in contract set 4.0.0 (Kaana ADR 0002, decision 7). The signed-lane
+ * result Kaana already produced (`embeddingSuccessSchema` in `/internal`)
+ * bounds what this surface can promise: at most 2048 inputs per request and
+ * vectors of at most 1024 dimensions.
+ */
+import { z } from 'zod';
+import { modelReferenceSchema } from './identifiers.js';
+/** The most inputs one request may embed. */
+export const MAX_EMBEDDING_INPUTS = 2048;
+export const embeddingsRequestSchema = z
+    .object({
+    /** A concrete model: an embedding space is a property of exact weights. */
+    model: modelReferenceSchema,
+    input: z.union([
+        z.string().min(1),
+        z.array(z.string().min(1)).min(1).max(MAX_EMBEDDING_INPUTS),
+    ]),
+    /** Only `float`: base64 vectors are an encoding the contract does not carry. */
+    encoding_format: z.literal('float').optional(),
+    /** Requested output dimension, for models that can shorten their vectors. */
+    dimensions: z.number().int().positive().max(1024).optional(),
+    /** OpenAI's end-user attribution field: the delegated user id, attribution only. */
+    user: z.string().min(1).max(64).optional(),
+})
+    .strict();
+export const embeddingsResponseSchema = z
+    .object({
+    object: z.literal('list'),
+    data: z
+        .array(z
+        .object({
+        object: z.literal('embedding'),
+        index: z.number().int().nonnegative(),
+        embedding: z.array(z.number()).min(1).max(1024),
+    })
+        .strict())
+        .min(1)
+        .max(MAX_EMBEDDING_INPUTS),
+    /** The revision that produced the vectors. */
+    model: modelReferenceSchema,
+    usage: z
+        .object({
+        prompt_tokens: z.number().int().nonnegative(),
+        total_tokens: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((response, ctx) => {
+    const indexes = response.data.map((vector) => vector.index);
+    if (new Set(indexes).size !== indexes.length) {
+        ctx.addIssue({ code: 'custom', path: ['data'], message: 'embedding indexes must be unique' });
+    }
+    const dimensions = new Set(response.data.map((vector) => vector.embedding.length));
+    if (dimensions.size > 1) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['data'],
+            message: 'every vector of one response has the same dimension',
+        });
+    }
+});