@kaana.ai/contracts 8.14.0 → 8.15.0

package/dist/internal/request.d.ts

@@ -351,6 +351,11 @@ export declare const inferenceRequestSchema: z.ZodObject<{
             b64_json: "b64_json";
         }>>;
     }, z.core.$strict>>;
+    rerank: z.ZodOptional<z.ZodObject<{
+        documents: z.ZodArray<z.ZodString>;
+        topN: z.ZodOptional<z.ZodNumber>;
+        returnDocuments: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
     transcription: z.ZodOptional<z.ZodObject<{
         language: z.ZodOptional<z.ZodString>;
         prompt: z.ZodOptional<z.ZodString>;

package/dist/internal/request.js

@@ -8,7 +8,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { inferenceApiFormatSchema, inferenceModalitySchema } from '../public/catalogue.js';
 import { decisionInputSchema } from '../public/decisions.js';
 import { idempotencyKeySchema, inferenceTimestampSchema } from '../public/identifiers.js';
-import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceImageParametersSchema, inferenceSpeechParametersSchema, inferenceTranscriptionParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
+import { inferenceAudioOutputParametersSchema, inferenceMessageSchema, inferenceReasoningSchema, inferenceImageParametersSchema, inferenceRerankParametersSchema, inferenceSpeechParametersSchema, inferenceTranscriptionParametersSchema, responseFormatSchema, samplingParametersSchema, toolChoiceSchema, toolDefinitionSchema, } from '../public/messages.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceAttributionSchema } from './attribution.js';
 import { authorizedRouteSchema, routingTargetSchema } from './routing.js';
@@ -95,6 +95,8 @@ const inferenceRequestObjectSchema = z.object({
     speech: inferenceSpeechParametersSchema.optional(),
     /** Text-to-image controls. Contract set 8.12.0. */
     image: inferenceImageParametersSchema.optional(),
+    /** The documents and controls of a rerank request. Contract set 8.15.0. */
+    rerank: inferenceRerankParametersSchema.optional(),
     /** File transcription parameters. Contract set 4.5.0. */
     transcription: inferenceTranscriptionParametersSchema.optional(),
     /** Spoken output from a conversational model. Contract set 3.2.0. */
@@ -171,6 +173,7 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             request.reasoning !== undefined ||
             request.speech !== undefined ||
             request.image !== undefined ||
+            request.rerank !== undefined ||
             request.transcription !== undefined ||
             request.audioOutput !== undefined) {
             ctx.addIssue({
@@ -209,6 +212,19 @@ export const inferenceRequestSchema = inferenceRequestObjectSchema.superRefine((
             message: 'image parameters require the images_generations API format with image modality and text input',
         });
     }
+    if ((request.rerank !== undefined || request.client.apiFormat === 'rerank') &&
+        (request.rerank === undefined ||
+            request.client.apiFormat !== 'rerank' ||
+            request.modality !== 'text' ||
+            request.input.format !== 'text' ||
+            request.input.text.length === 0 ||
+            request.stream)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['rerank'],
+            message: 'a rerank request needs the rerank API format, text modality, a non-empty text query, no streaming and rerank parameters',
+        });
+    }
     if (request.transcription !== undefined &&
         (request.client.apiFormat !== 'audio_transcriptions' ||
             request.modality !== 'audio' ||

package/dist/public/messages.d.ts

@@ -361,6 +361,16 @@ export declare const inferenceImageParametersSchema: z.ZodObject<{
         b64_json: "b64_json";
     }>>;
 }, z.core.$strict>;
+/**
+ * The documents and controls of a rerank request (contract set 8.15.0), carried
+ * in the signed envelope beside the query (the envelope's text input). Strings
+ * only, as on the public request. Customer data: never logged or persisted.
+ */
+export declare const inferenceRerankParametersSchema: z.ZodObject<{
+    documents: z.ZodArray<z.ZodString>;
+    topN: z.ZodOptional<z.ZodNumber>;
+    returnDocuments: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
 /**
  * Parameters for a file transcription, preserved in the signed request
  * (contract set 4.5.0). `language` is the caller's statement of what is spoken,
@@ -404,6 +414,7 @@ export declare const inferenceAudioOutputParametersSchema: z.ZodObject<{
  * Moved from the Oxy edge (`packages/api/src/schemas/inferenceEdge.schemas.ts`).
  */
 export declare const requestLabelsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export type InferenceRerankParameters = z.infer<typeof inferenceRerankParametersSchema>;
 export type InferenceImageParameters = z.infer<typeof inferenceImageParametersSchema>;
 export type InferenceSpeechParameters = z.infer<typeof inferenceSpeechParametersSchema>;
 export type InferenceTranscriptionParameters = z.infer<typeof inferenceTranscriptionParametersSchema>;

package/dist/public/messages.js

@@ -429,6 +429,21 @@ export const inferenceImageParametersSchema = z
     responseFormat: z.enum(['url', 'b64_json']).optional(),
 })
     .strict();
+/**
+ * The documents and controls of a rerank request (contract set 8.15.0), carried
+ * in the signed envelope beside the query (the envelope's text input). Strings
+ * only, as on the public request. Customer data: never logged or persisted.
+ */
+export const inferenceRerankParametersSchema = z
+    .object({
+    documents: z
+        .array(z.string().check(minUtf16Length(1)))
+        .min(1)
+        .max(1000),
+    topN: z.number().int().min(1).optional(),
+    returnDocuments: z.boolean().optional(),
+})
+    .strict();
 /**
  * Parameters for a file transcription, preserved in the signed request
  * (contract set 4.5.0). `language` is the caller's statement of what is spoken,

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.14.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.15.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:
@@ -255,6 +255,16 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.14.0";
  * public inference shapes are unchanged; publishing does not activate native
  * economic authorization or enroll any customer.
  */
+/**
+ * Contract set 8.15.0 is additive: the signed envelope's optional `rerank`
+ * member (`inferenceRerankParametersSchema`: `documents`, `topN`,
+ * `returnDocuments`), which carries a rerank request's documents and controls to
+ * the adapter beside the query (the envelope's text input). It is valid only
+ * with the `rerank` API format, text modality and text input. The public
+ * request and response shapes and the grant are unchanged; Kaana now serves
+ * `POST /v1/rerank` and emits the `rerank` operation for a model some deployment
+ * can serve.
+ */
 /** The public API's one origin and version. */
 export declare const KAANA_API_BASE_URL = "https://kaana.ai/v1";
 /** The response header that carries the request id. */

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.14.0';
+export const INFERENCE_CONTRACT_VERSION = '8.15.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:
@@ -255,6 +255,16 @@ export const INFERENCE_CONTRACT_VERSION = '8.14.0';
  * public inference shapes are unchanged; publishing does not activate native
  * economic authorization or enroll any customer.
  */
+/**
+ * Contract set 8.15.0 is additive: the signed envelope's optional `rerank`
+ * member (`inferenceRerankParametersSchema`: `documents`, `topN`,
+ * `returnDocuments`), which carries a rerank request's documents and controls to
+ * the adapter beside the query (the envelope's text input). It is valid only
+ * with the `rerank` API format, text modality and text input. The public
+ * request and response shapes and the grant are unchanged; Kaana now serves
+ * `POST /v1/rerank` and emits the `rerank` operation for a model some deployment
+ * can serve.
+ */
 /** The public API's one origin and version. */
 export const KAANA_API_BASE_URL = 'https://kaana.ai/v1';
 /** The response header that carries the request id. */

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Kaana API",
-    "version": "8.14.0",
+    "version": "8.15.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": [
@@ -4440,6 +4440,32 @@
           "failed"
         ]
       },
+      "InferenceRerankParameters": {
+        "type": "object",
+        "properties": {
+          "documents": {
+            "minItems": 1,
+            "maxItems": 1000,
+            "type": "array",
+            "items": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "topN": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 9007199254740991
+          },
+          "returnDocuments": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "documents"
+        ],
+        "additionalProperties": false
+      },
       "InferenceSpeechParameters": {
         "type": "object",
         "properties": {

package/package.json

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