@kaana.ai/contracts 8.4.0 → 8.5.0

package/dist/index.d.ts

@@ -24,6 +24,7 @@ export * from './public/images.js';
 export * from './public/messages.js';
 export * from './public/money.js';
 export * from './public/policy.js';
+export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';

package/dist/index.js

@@ -24,6 +24,7 @@ export * from './public/images.js';
 export * from './public/messages.js';
 export * from './public/money.js';
 export * from './public/policy.js';
+export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';

package/dist/internal/catalogue.d.ts

@@ -314,10 +314,10 @@ export declare const routingProfileSchema: z.ZodObject<{
     displayName: z.ZodString;
     description: z.ZodOptional<z.ZodString>;
     optimiseFor: z.ZodEnum<{
-        quality: "quality";
-        price: "price";
         latency: "latency";
         throughput: "throughput";
+        quality: "quality";
+        price: "price";
         balanced: "balanced";
     }>;
     candidates: z.ZodArray<z.ZodObject<{

package/dist/public/chatCompletions.d.ts

@@ -2,9 +2,10 @@
  * `POST /v1/chat/completions` — the OpenAI-compatible surface.
  *
  * It speaks the flat OpenAI request and response shapes so an unmodified OpenAI
- * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key, and
- * it gains NO Kaana-specific request field: a capability with no OpenAI
- * representation lives on `/v1/responses`. `.strict()` everywhere: a stock SDK
+ * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key. Its
+ * one extension is `provider`, the OpenRouter-style routing preference (ADR
+ * 0008); every other capability with no OpenAI representation lives on
+ * `/v1/responses`. `.strict()` everywhere: a stock SDK
  * sending a parameter Kaana does not implement is told so rather than having it
  * silently dropped.
  *
@@ -214,6 +215,34 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
         }>;
     }, z.core.$strict>>;
     user: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodObject<{
+        order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allow_fallbacks: z.ZodOptional<z.ZodBoolean>;
+        require_parameters: z.ZodOptional<z.ZodBoolean>;
+        quantizations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            unknown: "unknown";
+            int4: "int4";
+            int8: "int8";
+            fp4: "fp4";
+            mxfp4: "mxfp4";
+            nvfp4: "nvfp4";
+            fp6: "fp6";
+            fp8: "fp8";
+            mxfp8: "mxfp8";
+            fp16: "fp16";
+            bf16: "bf16";
+            fp32: "fp32";
+        }>>>;
+        sort: z.ZodOptional<z.ZodEnum<{
+            latency: "latency";
+            throughput: "throughput";
+        }>>;
+        preferred_max_latency: z.ZodOptional<z.ZodNumber>;
+        preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    prompt_cache_key: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /** OpenAI's usage block, with the audio members only when audio tokens were metered. */
 export declare const chatCompletionUsageSchema: z.ZodObject<{

package/dist/public/chatCompletions.js

@@ -2,9 +2,10 @@
  * `POST /v1/chat/completions` — the OpenAI-compatible surface.
  *
  * It speaks the flat OpenAI request and response shapes so an unmodified OpenAI
- * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key, and
- * it gains NO Kaana-specific request field: a capability with no OpenAI
- * representation lives on `/v1/responses`. `.strict()` everywhere: a stock SDK
+ * SDK works against `baseURL: 'https://kaana.ai/v1'` with an `oxy_sk_…` key. Its
+ * one extension is `provider`, the OpenRouter-style routing preference (ADR
+ * 0008); every other capability with no OpenAI representation lives on
+ * `/v1/responses`. `.strict()` everywhere: a stock SDK
  * sending a parameter Kaana does not implement is told so rather than having it
  * silently dropped.
  *
@@ -18,6 +19,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { reasoningEffortSchema } from './catalogue.js';
 import { publicErrorCodeSchema } from './errors.js';
 import { inferenceContentPartSchema } from './messages.js';
+import { promptCacheKeySchema, providerPreferencesSchema } from './providerPreferences.js';
 import { modelTargetSchema } from './responses.js';
 /** `stop` in the OpenAI dialect: one sequence or a list of them. */
 const openAiStopSchema = z.union([
@@ -139,6 +141,10 @@ export const chatCompletionsRequestSchema = z
      * only. `X-Oxy-User-Id` wins when both are present.
      */
     user: z.string().check(minUtf16Length(1)).check(maxUtf16Length(64)).optional(),
+    /** Routing preferences that can only narrow what the grant admits (ADR 0008). */
+    provider: providerPreferencesSchema.optional(),
+    /** OpenAI's field: keeps requests sharing a prompt prefix on one deployment. */
+    prompt_cache_key: promptCacheKeySchema.optional(),
 })
     .strict()
     .superRefine((request, ctx) => {

package/dist/public/providerPreferences.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The `provider` object a caller may send on `POST /v1/chat/completions` and
+ * `POST /v1/responses` (Kaana ADR 0008, decision 6).
+ *
+ * It is a preference that can only NARROW. Oxy signs what a request may use and
+ * Kaana resolves the grant into routes; this object filters or reorders what
+ * the grant already admitted. It cannot add a provider, region, funding tier or
+ * price the grant did not, and a request it leaves with no route is refused
+ * rather than widened.
+ *
+ * The names are OpenRouter's, so a client written for OpenRouter's `provider`
+ * object works, and only the controls Kaana can honour are accepted:
+ * `sort: "price"`, `max_price`, `zdr`, `data_collection`, `preferred_*` with a
+ * percentile object, and `enforce_distillable_text` are refused by `.strict()`
+ * rather than silently ignored. `max_price` and the data policy stay Oxy's:
+ * Kaana never prices, and Oxy applies data policy when it computes the grant.
+ *
+ * Provider names here are Kaana provider slugs as a caller sees them in the
+ * catalogue. A response never names one.
+ */
+import { z } from 'zod';
+/** Quantization levels a route can be published at (the OpenRouter vocabulary). */
+export declare const providerQuantizationSchema: z.ZodEnum<{
+    unknown: "unknown";
+    int4: "int4";
+    int8: "int8";
+    fp4: "fp4";
+    mxfp4: "mxfp4";
+    nvfp4: "nvfp4";
+    fp6: "fp6";
+    fp8: "fp8";
+    mxfp8: "mxfp8";
+    fp16: "fp16";
+    bf16: "bf16";
+    fp32: "fp32";
+}>;
+export declare const providerPreferencesSchema: z.ZodObject<{
+    order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allow_fallbacks: z.ZodOptional<z.ZodBoolean>;
+    require_parameters: z.ZodOptional<z.ZodBoolean>;
+    quantizations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        unknown: "unknown";
+        int4: "int4";
+        int8: "int8";
+        fp4: "fp4";
+        mxfp4: "mxfp4";
+        nvfp4: "nvfp4";
+        fp6: "fp6";
+        fp8: "fp8";
+        mxfp8: "mxfp8";
+        fp16: "fp16";
+        bf16: "bf16";
+        fp32: "fp32";
+    }>>>;
+    sort: z.ZodOptional<z.ZodEnum<{
+        latency: "latency";
+        throughput: "throughput";
+    }>>;
+    preferred_max_latency: z.ZodOptional<z.ZodNumber>;
+    preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type ProviderPreferences = z.infer<typeof providerPreferencesSchema>;
+/**
+ * An opaque caller-chosen string that groups requests sharing a prompt prefix.
+ * Kaana keeps such requests on the deployment that last served them while it is
+ * still admitted, so the provider's prompt cache stays warm. It is never stored
+ * with a prompt and never leaves Kaana.
+ */
+export declare const promptCacheKeySchema: z.ZodString;

package/dist/public/providerPreferences.js

@@ -0,0 +1,75 @@
+/**
+ * The `provider` object a caller may send on `POST /v1/chat/completions` and
+ * `POST /v1/responses` (Kaana ADR 0008, decision 6).
+ *
+ * It is a preference that can only NARROW. Oxy signs what a request may use and
+ * Kaana resolves the grant into routes; this object filters or reorders what
+ * the grant already admitted. It cannot add a provider, region, funding tier or
+ * price the grant did not, and a request it leaves with no route is refused
+ * rather than widened.
+ *
+ * The names are OpenRouter's, so a client written for OpenRouter's `provider`
+ * object works, and only the controls Kaana can honour are accepted:
+ * `sort: "price"`, `max_price`, `zdr`, `data_collection`, `preferred_*` with a
+ * percentile object, and `enforce_distillable_text` are refused by `.strict()`
+ * rather than silently ignored. `max_price` and the data policy stay Oxy's:
+ * Kaana never prices, and Oxy applies data policy when it computes the grant.
+ *
+ * Provider names here are Kaana provider slugs as a caller sees them in the
+ * catalogue. A response never names one.
+ */
+import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
+const providerSlugSchema = z
+    .string()
+    .check(minUtf16Length(1))
+    .check(maxUtf16Length(64))
+    .regex(/^[a-z0-9][a-z0-9._-]*$/);
+const providerListSchema = z.array(providerSlugSchema).min(1).max(16);
+/** Quantization levels a route can be published at (the OpenRouter vocabulary). */
+export const providerQuantizationSchema = z.enum([
+    'int4',
+    'int8',
+    'fp4',
+    'mxfp4',
+    'nvfp4',
+    'fp6',
+    'fp8',
+    'mxfp8',
+    'fp16',
+    'bf16',
+    'fp32',
+    'unknown',
+]);
+export const providerPreferencesSchema = z
+    .object({
+    /** Providers to try first, in this order. Others still follow unless `allow_fallbacks` is false. */
+    order: providerListSchema.optional(),
+    /** Allow-list: only these providers may serve the request. */
+    only: providerListSchema.optional(),
+    /** Skip-list: these providers never serve the request. */
+    ignore: providerListSchema.optional(),
+    /**
+     * False keeps a single provider: the first of `order` that is admitted, or
+     * the best-ranked one. The request is never moved to another.
+     */
+    allow_fallbacks: z.boolean().optional(),
+    /** True keeps only routes that accept every parameter the request carries. */
+    require_parameters: z.boolean().optional(),
+    /** Keep only routes published at one of these quantizations; `unknown` admits unstated ones. */
+    quantizations: z.array(providerQuantizationSchema).min(1).max(12).optional(),
+    /** Prefer the route with the lowest recent latency or the highest recent throughput. */
+    sort: z.enum(['latency', 'throughput']).optional(),
+    /** Seconds. A route slower than this recently is tried later, never excluded (p50). */
+    preferred_max_latency: z.number().positive().max(600).optional(),
+    /** Output tokens per second. A route slower than this recently is tried later, never excluded (p50). */
+    preferred_min_throughput: z.number().positive().max(100_000).optional(),
+})
+    .strict();
+/**
+ * An opaque caller-chosen string that groups requests sharing a prompt prefix.
+ * Kaana keeps such requests on the deployment that last served them while it is
+ * still admitted, so the provider's prompt cache stays warm. It is never stored
+ * with a prompt and never leaves Kaana.
+ */
+export const promptCacheKeySchema = z.string().check(minUtf16Length(1)).check(maxUtf16Length(256));

package/dist/public/responses.d.ts

@@ -144,6 +144,34 @@ export declare const responsesRequestSchema: z.ZodObject<{
     }, z.core.$strict>>;
     labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     clientRequestId: z.ZodOptional<z.ZodString>;
+    provider: z.ZodOptional<z.ZodObject<{
+        order: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        only: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ignore: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allow_fallbacks: z.ZodOptional<z.ZodBoolean>;
+        require_parameters: z.ZodOptional<z.ZodBoolean>;
+        quantizations: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            unknown: "unknown";
+            int4: "int4";
+            int8: "int8";
+            fp4: "fp4";
+            mxfp4: "mxfp4";
+            nvfp4: "nvfp4";
+            fp6: "fp6";
+            fp8: "fp8";
+            mxfp8: "mxfp8";
+            fp16: "fp16";
+            bf16: "bf16";
+            fp32: "fp32";
+        }>>>;
+        sort: z.ZodOptional<z.ZodEnum<{
+            latency: "latency";
+            throughput: "throughput";
+        }>>;
+        preferred_max_latency: z.ZodOptional<z.ZodNumber>;
+        preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    promptCacheKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 /**
  * The non-streaming body. A streamed request answers with

package/dist/public/responses.js

@@ -14,6 +14,7 @@ import { generationIdSchema, modelReferenceSchema, requestIdSchema } from './ide
 import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, responseFormatSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
 import { usageQuantitySchema } from './money.js';
 import { routingPolicyReferenceSchema } from './policy.js';
+import { promptCacheKeySchema, providerPreferencesSchema } from './providerPreferences.js';
 import { inferenceFinishReasonSchema } from './streamEvents.js';
 /**
  * What a `model` field may name: a concrete model reference
@@ -60,6 +61,10 @@ export const responsesRequestSchema = z
     labels: requestLabelsSchema.optional(),
     /** The caller's own correlation id, echoed on the response. */
     clientRequestId: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)).optional(),
+    /** Routing preferences that can only narrow what the grant admits (ADR 0008). */
+    provider: providerPreferencesSchema.optional(),
+    /** Keeps requests sharing a prompt prefix on one deployment while its cache is warm. */
+    promptCacheKey: promptCacheKeySchema.optional(),
 })
     .strict()
     .superRefine((request, ctx) => {

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.4.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.5.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:
@@ -208,6 +208,12 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.4.0";
  * capabilities whose `false` is not evidence). Nothing in 8.3.0 changes and
  * nothing emits either yet: a consumer on 8.3.0 refuses a usage report carrying
  * the unit and a catalogue carrying the field, so Oxy reads them first.
+ *
+ * Contract set 8.5.0 is additive: the optional `provider` routing preference
+ * (`providerPreferencesSchema`) and the prompt-cache key (`prompt_cache_key`,
+ * `promptCacheKey`) on `POST /v1/chat/completions` and `POST /v1/responses`
+ * (Kaana ADR 0008). The preference only narrows what the grant admits. Nothing
+ * in 8.4.0 changes and the signed grant and envelope are untouched.
  */
 /** 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.4.0';
+export const INFERENCE_CONTRACT_VERSION = '8.5.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:
@@ -208,6 +208,12 @@ export const INFERENCE_CONTRACT_VERSION = '8.4.0';
  * capabilities whose `false` is not evidence). Nothing in 8.3.0 changes and
  * nothing emits either yet: a consumer on 8.3.0 refuses a usage report carrying
  * the unit and a catalogue carrying the field, so Oxy reads them first.
+ *
+ * Contract set 8.5.0 is additive: the optional `provider` routing preference
+ * (`providerPreferencesSchema`) and the prompt-cache key (`prompt_cache_key`,
+ * `promptCacheKey`) on `POST /v1/chat/completions` and `POST /v1/responses`
+ * (Kaana ADR 0008). The preference only narrows what the grant admits. Nothing
+ * in 8.4.0 changes and the signed grant and envelope are untouched.
  */
 /** 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.4.0",
+    "version": "8.5.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": [
@@ -3118,6 +3118,12 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 64
+          },
+          "provider": {
+            "$ref": "#/components/schemas/ProviderPreferences"
+          },
+          "prompt_cache_key": {
+            "$ref": "#/components/schemas/PromptCacheKey"
           }
         },
         "required": [
@@ -5114,6 +5120,98 @@
         ],
         "additionalProperties": false
       },
+      "PromptCacheKey": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 256
+      },
+      "ProviderPreferences": {
+        "type": "object",
+        "properties": {
+          "order": {
+            "minItems": 1,
+            "maxItems": 16,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[a-z0-9][a-z0-9._-]*$"
+            }
+          },
+          "only": {
+            "minItems": 1,
+            "maxItems": 16,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[a-z0-9][a-z0-9._-]*$"
+            }
+          },
+          "ignore": {
+            "minItems": 1,
+            "maxItems": 16,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 64,
+              "pattern": "^[a-z0-9][a-z0-9._-]*$"
+            }
+          },
+          "allow_fallbacks": {
+            "type": "boolean"
+          },
+          "require_parameters": {
+            "type": "boolean"
+          },
+          "quantizations": {
+            "minItems": 1,
+            "maxItems": 12,
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ProviderQuantization"
+            }
+          },
+          "sort": {
+            "type": "string",
+            "enum": [
+              "latency",
+              "throughput"
+            ]
+          },
+          "preferred_max_latency": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 600
+          },
+          "preferred_min_throughput": {
+            "type": "number",
+            "exclusiveMinimum": 0,
+            "maximum": 100000
+          }
+        },
+        "additionalProperties": false
+      },
+      "ProviderQuantization": {
+        "type": "string",
+        "enum": [
+          "int4",
+          "int8",
+          "fp4",
+          "mxfp4",
+          "nvfp4",
+          "fp6",
+          "fp8",
+          "mxfp8",
+          "fp16",
+          "bf16",
+          "fp32",
+          "unknown"
+        ]
+      },
       "PublicErrorCode": {
         "type": "string",
         "enum": [
@@ -7612,6 +7710,12 @@
             "type": "string",
             "minLength": 1,
             "maxLength": 128
+          },
+          "provider": {
+            "$ref": "#/components/schemas/ProviderPreferences"
+          },
+          "promptCacheKey": {
+            "$ref": "#/components/schemas/PromptCacheKey"
           }
         },
         "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaana.ai/contracts",
-  "version": "8.4.0",
+  "version": "8.5.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,