@kaana.ai/contracts 8.10.0 → 8.11.0

package/dist/index.d.ts

@@ -26,6 +26,7 @@ export * from './public/money.js';
 export * from './public/policy.js';
 export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
+export * from './public/rerank.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';
 export * from './public/version.js';

package/dist/index.js

@@ -26,6 +26,7 @@ export * from './public/money.js';
 export * from './public/policy.js';
 export * from './public/providerPreferences.js';
 export * from './public/realtime.js';
+export * from './public/rerank.js';
 export * from './public/responses.js';
 export * from './public/streamEvents.js';
 export * from './public/version.js';

package/dist/internal/grant.d.ts

@@ -40,6 +40,7 @@ export declare const grantOperationSchema: z.ZodEnum<{
     images_generations: "images_generations";
     audio_transcriptions: "audio_transcriptions";
     audio_speech: "audio_speech";
+    rerank: "rerank";
     realtime_session: "realtime_session";
 }>;
 /**
@@ -101,6 +102,7 @@ export declare const inferenceAuthorizationRequestSchema: z.ZodObject<{
         images_generations: "images_generations";
         audio_transcriptions: "audio_transcriptions";
         audio_speech: "audio_speech";
+        rerank: "rerank";
         realtime_session: "realtime_session";
     }>;
     target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -181,6 +183,7 @@ export declare const authorizationRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
         images_generations: "images_generations";
         audio_transcriptions: "audio_transcriptions";
         audio_speech: "audio_speech";
+        rerank: "rerank";
         realtime_session: "realtime_session";
     }>;
     target: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -383,6 +386,7 @@ export declare const grantSchema: z.ZodObject<{
         images_generations: "images_generations";
         audio_transcriptions: "audio_transcriptions";
         audio_speech: "audio_speech";
+        rerank: "rerank";
         realtime_session: "realtime_session";
     }>;
     issuedAt: z.ZodString;

package/dist/internal/grant.js

@@ -65,6 +65,7 @@ export const grantOperationSchema = z.enum([
     'images_generations',
     'decisions',
     'realtime_session',
+    'rerank',
 ]);
 /**
  * What the caller asked to be served: a model line, optionally pinned to a

package/dist/public/rerank.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `POST /v1/rerank` — rank documents by relevance to a query.
+ *
+ * New in contract set 8.11.0, CONTRACT ONLY: these shapes and the `rerank` grant
+ * operation are declared so Oxy can support the operation before Kaana serves
+ * it. Kaana does not serve the route yet and emits no `rerank` operation.
+ *
+ * Version 1 takes string documents only. The response carries a relevance score
+ * per document and the token usage; it never carries an amount.
+ */
+import { z } from 'zod';
+/** The most documents one rerank request may carry. */
+export declare const MAX_RERANK_DOCUMENTS = 1000;
+export declare const rerankRequestSchema: z.ZodObject<{
+    model: z.ZodString;
+    query: z.ZodString;
+    documents: z.ZodArray<z.ZodString>;
+    top_n: z.ZodOptional<z.ZodNumber>;
+    return_documents: z.ZodOptional<z.ZodBoolean>;
+    user: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const rerankResponseSchema: z.ZodObject<{
+    id: z.ZodString;
+    model: z.ZodString;
+    results: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        relevance_score: z.ZodNumber;
+        document: z.ZodOptional<z.ZodObject<{
+            text: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    usage: z.ZodObject<{
+        prompt_tokens: z.ZodNumber;
+        total_tokens: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type RerankRequest = z.infer<typeof rerankRequestSchema>;
+export type RerankResponse = z.infer<typeof rerankResponseSchema>;

package/dist/public/rerank.js

@@ -0,0 +1,63 @@
+/**
+ * `POST /v1/rerank` — rank documents by relevance to a query.
+ *
+ * New in contract set 8.11.0, CONTRACT ONLY: these shapes and the `rerank` grant
+ * operation are declared so Oxy can support the operation before Kaana serves
+ * it. Kaana does not serve the route yet and emits no `rerank` operation.
+ *
+ * Version 1 takes string documents only. The response carries a relevance score
+ * per document and the token usage; it never carries an amount.
+ */
+import { z } from 'zod';
+import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
+import { generationIdSchema, modelReferenceSchema } from './identifiers.js';
+/** The most documents one rerank request may carry. */
+export const MAX_RERANK_DOCUMENTS = 1000;
+export const rerankRequestSchema = z
+    .object({
+    /** `publisher/model` or `publisher/model@revision`. */
+    model: modelReferenceSchema,
+    query: z.string().check(minUtf16Length(1)),
+    /** String documents only. */
+    documents: z
+        .array(z.string().check(minUtf16Length(1)))
+        .min(1)
+        .max(MAX_RERANK_DOCUMENTS),
+    /** How many of the most relevant documents to return; all when absent. */
+    top_n: z.number().int().min(1).optional(),
+    /** Echo each ranked document's text in its result. */
+    return_documents: z.boolean().optional(),
+    /** The delegated end-user id, attribution only (as on `/v1/embeddings`). */
+    user: z.string().check(minUtf16Length(1)).check(maxUtf16Length(64)).optional(),
+})
+    .strict();
+export const rerankResponseSchema = z
+    .object({
+    id: generationIdSchema,
+    /** The revision that produced the scores. */
+    model: modelReferenceSchema,
+    /** Most relevant first. */
+    results: z
+        .array(z
+        .object({
+        /** The position of the document in the request's `documents`. */
+        index: z.number().int().nonnegative(),
+        relevance_score: z.number(),
+        document: z.object({ text: z.string() }).strict().optional(),
+    })
+        .strict())
+        .max(MAX_RERANK_DOCUMENTS),
+    usage: z
+        .object({
+        prompt_tokens: z.number().int().nonnegative(),
+        total_tokens: z.number().int().nonnegative(),
+    })
+        .strict(),
+})
+    .strict()
+    .superRefine((response, ctx) => {
+    const indexes = response.results.map((result) => result.index);
+    if (new Set(indexes).size !== indexes.length) {
+        ctx.addIssue({ code: 'custom', path: ['results'], message: 'result indexes must be unique' });
+    }
+});

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.10.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.11.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:
@@ -236,6 +236,11 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.10.0";
  * 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.
+ *
+ * Contract set 8.11.0 is additive and CONTRACT ONLY: the `rerank` grant
+ * operation (`grantOperationSchema`, last member) and the public `POST /v1/rerank`
+ * shapes (`rerankRequestSchema`, `rerankResponseSchema`). Kaana emits no `rerank`
+ * operation and serves no route yet; Oxy supports the operation first.
  */
 /** 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.10.0';
+export const INFERENCE_CONTRACT_VERSION = '8.11.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:
@@ -236,6 +236,11 @@ export const INFERENCE_CONTRACT_VERSION = '8.10.0';
  * 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.
+ *
+ * Contract set 8.11.0 is additive and CONTRACT ONLY: the `rerank` grant
+ * operation (`grantOperationSchema`, last member) and the public `POST /v1/rerank`
+ * shapes (`rerankRequestSchema`, `rerankResponseSchema`). Kaana emits no `rerank`
+ * operation and serves no route yet; Oxy supports the operation first.
  */
 /** 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.10.0",
+    "version": "8.11.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": [
@@ -7718,6 +7718,118 @@
           "maxLength": 256
         }
       },
+      "RerankRequest": {
+        "type": "object",
+        "properties": {
+          "model": {
+            "$ref": "#/components/schemas/ModelReference"
+          },
+          "query": {
+            "type": "string",
+            "minLength": 1
+          },
+          "documents": {
+            "minItems": 1,
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "top_n": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "return_documents": {
+            "type": "boolean"
+          },
+          "user": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          }
+        },
+        "required": [
+          "model",
+          "query",
+          "documents"
+        ],
+        "additionalProperties": false
+      },
+      "RerankResponse": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "$ref": "#/components/schemas/GenerationId"
+          },
+          "model": {
+            "$ref": "#/components/schemas/ModelReference"
+          },
+          "results": {
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "index": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                },
+                "relevance_score": {
+                  "type": "number"
+                },
+                "document": {
+                  "type": "object",
+                  "properties": {
+                    "text": {
+                      "type": "string"
+                    }
+                  },
+                  "required": [
+                    "text"
+                  ],
+                  "additionalProperties": false
+                }
+              },
+              "required": [
+                "index",
+                "relevance_score"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "usage": {
+            "type": "object",
+            "properties": {
+              "prompt_tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "total_tokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "required": [
+              "prompt_tokens",
+              "total_tokens"
+            ],
+            "additionalProperties": false
+          }
+        },
+        "required": [
+          "id",
+          "model",
+          "results",
+          "usage"
+        ],
+        "additionalProperties": false
+      },
       "ResponseFormat": {
         "oneOf": [
           {

package/package.json

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