@kaana.ai/contracts 8.8.0 → 8.10.0

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<{
+        price: "price";
         latency: "latency";
         throughput: "throughput";
         quality: "quality";
-        price: "price";
         balanced: "balanced";
     }>;
     candidates: z.ZodArray<z.ZodObject<{

package/dist/public/chatCompletions.d.ts

@@ -250,9 +250,14 @@ export declare const chatCompletionsRequestSchema: z.ZodObject<{
             fp32: "fp32";
         }>>>;
         sort: z.ZodOptional<z.ZodEnum<{
+            price: "price";
             latency: "latency";
             throughput: "throughput";
         }>>;
+        max_price: z.ZodOptional<z.ZodObject<{
+            prompt: z.ZodOptional<z.ZodNumber>;
+            completion: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
         preferred_max_latency: z.ZodOptional<z.ZodNumber>;
         preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;

package/dist/public/providerPreferences.d.ts

@@ -9,11 +9,17 @@
  * 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.
+ * object works, and only the controls Kaana can honour are accepted: `zdr`,
+ * `data_collection`, `preferred_*` with a percentile object and
+ * `enforce_distillable_text` are refused by `.strict()` rather than silently
+ * ignored, because the data policy is Oxy's and is applied when it computes the
+ * grant.
+ *
+ * `max_price` and `sort: "price"` read the DECLARED LIST PRICE of a model line,
+ * the price Oxy rates the grant at, in USD per million tokens. They are about
+ * which model line serves the request, because every route of one line costs
+ * the customer the same: they never expose an amount, and a line whose price
+ * the catalogue does not state is neither within a ceiling nor cheap.
  *
  * Provider names here are Kaana provider slugs as a caller sees them in the
  * catalogue. A response never names one.
@@ -55,9 +61,14 @@ export declare const providerPreferencesSchema: z.ZodObject<{
         fp32: "fp32";
     }>>>;
     sort: z.ZodOptional<z.ZodEnum<{
+        price: "price";
         latency: "latency";
         throughput: "throughput";
     }>>;
+    max_price: z.ZodOptional<z.ZodObject<{
+        prompt: z.ZodOptional<z.ZodNumber>;
+        completion: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
     preferred_max_latency: z.ZodOptional<z.ZodNumber>;
     preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;

package/dist/public/providerPreferences.js

@@ -9,11 +9,17 @@
  * 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.
+ * object works, and only the controls Kaana can honour are accepted: `zdr`,
+ * `data_collection`, `preferred_*` with a percentile object and
+ * `enforce_distillable_text` are refused by `.strict()` rather than silently
+ * ignored, because the data policy is Oxy's and is applied when it computes the
+ * grant.
+ *
+ * `max_price` and `sort: "price"` read the DECLARED LIST PRICE of a model line,
+ * the price Oxy rates the grant at, in USD per million tokens. They are about
+ * which model line serves the request, because every route of one line costs
+ * the customer the same: they never expose an amount, and a line whose price
+ * the catalogue does not state is neither within a ceiling nor cheap.
  *
  * Provider names here are Kaana provider slugs as a caller sees them in the
  * catalogue. A response never names one.
@@ -58,8 +64,26 @@ export const providerPreferencesSchema = z
     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(),
+    /**
+     * Prefer the model line with the lowest declared list price, or the route
+     * with the lowest recent latency or the highest recent throughput.
+     */
+    sort: z.enum(['price', 'latency', 'throughput']).optional(),
+    /**
+     * A ceiling on the declared list price of the model line, in USD per million
+     * tokens. A line over it, or one whose price is not stated, is not used; the
+     * request is refused rather than served above it.
+     */
+    max_price: z
+        .object({
+        prompt: z.number().positive().max(1_000_000).optional(),
+        completion: z.number().positive().max(1_000_000).optional(),
+    })
+        .strict()
+        .refine((ceiling) => ceiling.prompt !== undefined || ceiling.completion !== undefined, {
+        message: 'max_price names prompt, completion or both',
+    })
+        .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). */

package/dist/public/responses.d.ts

@@ -23,6 +23,33 @@ export declare const modelTargetSchema: z.ZodUnion<readonly [z.ZodString, z.ZodE
     pro: "pro";
     ultra: "ultra";
 }>]>;
+/**
+ * The response format of `POST /v1/responses`: the signed request's format
+ * (`responseFormatSchema`) and, on the two JSON formats, `repair` (contract set
+ * 8.9.0, Kaana ADR 0009 decision 5).
+ *
+ * `repair: true` asks Kaana to repair nearly valid JSON in the final text of a
+ * non-streaming answer that ended with `stop`: a surrounding code fence, prose
+ * around the value, trailing commas, closers a normal stop forgot. It never
+ * changes text that already parses, never repairs an answer cut by the token
+ * limit (`length`) or ended by a filter, a refusal or a tool call, and checks
+ * nothing against `schema` (Kaana carries no validator). A repaired answer is
+ * marked by the response header `Kaana-Repaired: true`, never by a body
+ * member. It is refused on `text` and with `stream: true`, and it is not part of
+ * the signed request: no provider and no Oxy sees it. Default off.
+ */
+export declare const responsesResponseFormatSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"json_object">;
+    repair: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>, z.ZodObject<{
+    type: z.ZodLiteral<"json_schema">;
+    name: z.ZodString;
+    schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    strict: z.ZodBoolean;
+    repair: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>], "type">;
 /**
  * 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
@@ -137,11 +164,13 @@ export declare const responsesRequestSchema: z.ZodObject<{
         type: z.ZodLiteral<"text">;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"json_object">;
+        repair: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>, z.ZodObject<{
         type: z.ZodLiteral<"json_schema">;
         name: z.ZodString;
         schema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
         strict: z.ZodBoolean;
+        repair: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>], "type">>;
     reasoning: z.ZodOptional<z.ZodObject<{
         effort: z.ZodOptional<z.ZodEnum<{
@@ -175,9 +204,14 @@ export declare const responsesRequestSchema: z.ZodObject<{
             fp32: "fp32";
         }>>>;
         sort: z.ZodOptional<z.ZodEnum<{
+            price: "price";
             latency: "latency";
             throughput: "throughput";
         }>>;
+        max_price: z.ZodOptional<z.ZodObject<{
+            prompt: z.ZodOptional<z.ZodNumber>;
+            completion: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
         preferred_max_latency: z.ZodOptional<z.ZodNumber>;
         preferred_min_throughput: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>>;
@@ -294,6 +328,7 @@ export declare const responseSchema: z.ZodObject<{
     }, z.core.$strict>;
     latencyMs: z.ZodNumber;
 }, z.core.$strict>;
+export type ResponsesResponseFormat = z.infer<typeof responsesResponseFormatSchema>;
 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

@@ -11,7 +11,7 @@ import { z } from 'zod';
 import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { powerLevelSchema } from './catalogue.js';
 import { generationIdSchema, modelReferenceSchema, requestIdSchema } from './identifiers.js';
-import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, responseFormatSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
+import { inferenceMessageSchema, inferenceReasoningSchema, requestLabelsSchema, toolChoiceSchema, toolDefinitionSchema, } from './messages.js';
 import { usageQuantitySchema } from './money.js';
 import { routingPolicyReferenceSchema } from './policy.js';
 import { promptCacheKeySchema, providerPreferencesSchema } from './providerPreferences.js';
@@ -23,6 +23,34 @@ import { inferenceFinishReasonSchema } from './streamEvents.js';
  * the string alone).
  */
 export const modelTargetSchema = z.union([modelReferenceSchema, powerLevelSchema]);
+/**
+ * The response format of `POST /v1/responses`: the signed request's format
+ * (`responseFormatSchema`) and, on the two JSON formats, `repair` (contract set
+ * 8.9.0, Kaana ADR 0009 decision 5).
+ *
+ * `repair: true` asks Kaana to repair nearly valid JSON in the final text of a
+ * non-streaming answer that ended with `stop`: a surrounding code fence, prose
+ * around the value, trailing commas, closers a normal stop forgot. It never
+ * changes text that already parses, never repairs an answer cut by the token
+ * limit (`length`) or ended by a filter, a refusal or a tool call, and checks
+ * nothing against `schema` (Kaana carries no validator). A repaired answer is
+ * marked by the response header `Kaana-Repaired: true`, never by a body
+ * member. It is refused on `text` and with `stream: true`, and it is not part of
+ * the signed request: no provider and no Oxy sees it. Default off.
+ */
+export const responsesResponseFormatSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('text') }).strict(),
+    z.object({ type: z.literal('json_object'), repair: z.boolean().optional() }).strict(),
+    z
+        .object({
+        type: z.literal('json_schema'),
+        name: z.string().check(minUtf16Length(1)).check(maxUtf16Length(128)),
+        schema: z.record(z.string(), z.unknown()),
+        strict: z.boolean(),
+        repair: z.boolean().optional(),
+    })
+        .strict(),
+]);
 /** The message-or-text input `/v1/responses` accepts. */
 const responsesInputSchema = z.union([
     z.string().check(minUtf16Length(1)),
@@ -55,7 +83,7 @@ export const responsesRequestSchema = z
         .optional(),
     tools: z.array(toolDefinitionSchema).max(128).optional(),
     toolChoice: toolChoiceSchema.optional(),
-    responseFormat: responseFormatSchema.optional(),
+    responseFormat: responsesResponseFormatSchema.optional(),
     /** Refused when the resolved model does not advertise the effort. */
     reasoning: inferenceReasoningSchema.optional(),
     labels: requestLabelsSchema.optional(),
@@ -68,6 +96,16 @@ export const responsesRequestSchema = z
 })
     .strict()
     .superRefine((request, ctx) => {
+    if (request.responseFormat !== undefined &&
+        'repair' in request.responseFormat &&
+        request.responseFormat.repair === true &&
+        request.stream === true) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['responseFormat', 'repair'],
+            message: 'repair works on a whole answer and cannot be used with stream: true',
+        });
+    }
     if (request.toolChoice !== undefined && (request.tools ?? []).length === 0) {
         ctx.addIssue({
             code: 'custom',

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.8.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.10.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:
@@ -223,6 +223,19 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.8.0";
  * is emitted only to a request that carried `reasoning`. A consumer on 8.5.0 or
  * earlier (Oxy's legacy signed lane) refuses a message or request that carries
  * what is new, so Oxy reads it before a customer sends it.
+ *
+ * Contract set 8.9.0 is additive: the optional `repair` member of
+ * `POST /v1/responses`'s `responseFormat` (`responsesResponseFormatSchema`, Kaana
+ * ADR 0009 decision 5) and the response header `Kaana-Repaired`. It is a public
+ * request member only: the signed grant and envelope are unchanged, and a
+ * response carries no new body member, so every older reader parses what 8.9.0
+ * serves.
+ *
+ * Contract set 8.10.0 is additive: `max_price` and `sort: "price"` in the
+ * `provider` routing preference (`providerPreferencesSchema`, Kaana ADR 0008).
+ * Both read the declared list price of a model line, in USD per million tokens.
+ * Public request members only: the signed grant and envelope are unchanged and
+ * no response carries an amount.
  */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";
@@ -254,6 +267,12 @@ export declare const KAANA_USAGE_HEADER = "Kaana-Usage";
  */
 export declare const KAANA_ROUTING_POLICY_ID_HEADER = "Kaana-Routing-Policy-Id";
 export declare const KAANA_ROUTING_POLICY_VERSION_HEADER = "Kaana-Routing-Policy-Version";
+/**
+ * The response header Kaana sets to `true` when it changed the model's JSON
+ * text because the request asked for `responseFormat.repair` (contract set
+ * 8.9.0). Absent otherwise.
+ */
+export declare const KAANA_REPAIRED_HEADER = "Kaana-Repaired";
 /** The request header that names the end user a service token acts for. */
 export declare const KAANA_ON_BEHALF_OF_HEADER = "X-Oxy-User-Id";
 /** The request header that makes a request idempotent. */

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.8.0';
+export const INFERENCE_CONTRACT_VERSION = '8.10.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:
@@ -223,6 +223,19 @@ export const INFERENCE_CONTRACT_VERSION = '8.8.0';
  * is emitted only to a request that carried `reasoning`. A consumer on 8.5.0 or
  * earlier (Oxy's legacy signed lane) refuses a message or request that carries
  * what is new, so Oxy reads it before a customer sends it.
+ *
+ * Contract set 8.9.0 is additive: the optional `repair` member of
+ * `POST /v1/responses`'s `responseFormat` (`responsesResponseFormatSchema`, Kaana
+ * ADR 0009 decision 5) and the response header `Kaana-Repaired`. It is a public
+ * request member only: the signed grant and envelope are unchanged, and a
+ * response carries no new body member, so every older reader parses what 8.9.0
+ * serves.
+ *
+ * Contract set 8.10.0 is additive: `max_price` and `sort: "price"` in the
+ * `provider` routing preference (`providerPreferencesSchema`, Kaana ADR 0008).
+ * Both read the declared list price of a model line, in USD per million tokens.
+ * Public request members only: the signed grant and envelope are unchanged and
+ * no response carries an amount.
  */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';
@@ -254,6 +267,12 @@ export const KAANA_USAGE_HEADER = 'Kaana-Usage';
  */
 export const KAANA_ROUTING_POLICY_ID_HEADER = 'Kaana-Routing-Policy-Id';
 export const KAANA_ROUTING_POLICY_VERSION_HEADER = 'Kaana-Routing-Policy-Version';
+/**
+ * The response header Kaana sets to `true` when it changed the model's JSON
+ * text because the request asked for `responseFormat.repair` (contract set
+ * 8.9.0). Absent otherwise.
+ */
+export const KAANA_REPAIRED_HEADER = 'Kaana-Repaired';
 /** The request header that names the end user a service token acts for. */
 export const KAANA_ON_BEHALF_OF_HEADER = 'X-Oxy-User-Id';
 /** The request header that makes a request idempotent. */

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.8.0",
+    "version": "8.10.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": [
@@ -5506,10 +5506,27 @@
           "sort": {
             "type": "string",
             "enum": [
+              "price",
               "latency",
               "throughput"
             ]
           },
+          "max_price": {
+            "type": "object",
+            "properties": {
+              "prompt": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "maximum": 1000000
+              },
+              "completion": {
+                "type": "number",
+                "exclusiveMinimum": 0,
+                "maximum": 1000000
+              }
+            },
+            "additionalProperties": false
+          },
           "preferred_max_latency": {
             "type": "number",
             "exclusiveMinimum": 0,
@@ -8026,7 +8043,7 @@
             "$ref": "#/components/schemas/ToolChoice"
           },
           "responseFormat": {
-            "$ref": "#/components/schemas/ResponseFormat"
+            "$ref": "#/components/schemas/ResponsesResponseFormat"
           },
           "reasoning": {
             "$ref": "#/components/schemas/InferenceReasoning"
@@ -8051,6 +8068,73 @@
         ],
         "additionalProperties": false
       },
+      "ResponsesResponseFormat": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "text"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "json_object"
+              },
+              "repair": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "type"
+            ],
+            "additionalProperties": false
+          },
+          {
+            "type": "object",
+            "properties": {
+              "type": {
+                "type": "string",
+                "const": "json_schema"
+              },
+              "name": {
+                "type": "string",
+                "minLength": 1,
+                "maxLength": 128
+              },
+              "schema": {
+                "type": "object",
+                "propertyNames": {
+                  "type": "string"
+                },
+                "additionalProperties": {}
+              },
+              "strict": {
+                "type": "boolean"
+              },
+              "repair": {
+                "type": "boolean"
+              }
+            },
+            "required": [
+              "type",
+              "name",
+              "schema",
+              "strict"
+            ],
+            "additionalProperties": false
+          }
+        ]
+      },
       "RoutingPolicyReference": {
         "type": "object",
         "properties": {

package/package.json

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