@kaana.ai/contracts 8.1.0 → 8.2.0

package/dist/internal/catalogue.d.ts

@@ -562,6 +562,26 @@ export declare const modelCatalogueEntrySchema: z.ZodObject<{
         ultra: "ultra";
     }>>;
 }, z.core.$strip>;
+/**
+ * What a model line's image input costs at most, as the line's own documented
+ * rule states it (contract set 8.2.0, Kaana ADR 0007). Internal: Oxy reads it
+ * from the declared catalogue to bound the input of a request carrying images;
+ * `GET /v1/models` does not serve it.
+ *
+ * `maxInputTokensPerImage` is the most input tokens the line's provider bills
+ * for ONE image the contract admits (`checkImageInput`), at any `detail` the
+ * contract offers, from the publisher's documented resize and tokenization
+ * rule. Images are billed as input tokens at the line's `input_tokens` price;
+ * this figure only sizes a hold and qualifies a route, the settlement is the
+ * provider's own count.
+ *
+ * ABSENT means undeclared, even on a model whose `inputModalities` lists
+ * `image`: nobody has stated what one image costs on it, so no request carrying
+ * an image is authorized on it.
+ */
+export declare const declaredImageInputSchema: z.ZodObject<{
+    maxInputTokensPerImage: z.ZodNumber;
+}, z.core.$strict>;
 /**
  * One model as Kaana DECLARES it in `configs/public-catalogue.json` (Kaana ADR
  * 0002, amendment 2026-10-15): the public `modelSchema` without the three
@@ -791,6 +811,9 @@ export declare const declaredModelSchema: z.ZodObject<{
         platform_internal: "platform_internal";
         public: "public";
     }>;
+    imageInput: z.ZodOptional<z.ZodObject<{
+        maxInputTokensPerImage: z.ZodNumber;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 /**
  * The declared catalogue: identity, publisher, licence, provenance, data
@@ -1019,9 +1042,13 @@ export declare const declaredCatalogueSchema: z.ZodObject<{
             platform_internal: "platform_internal";
             public: "public";
         }>;
+        imageInput: z.ZodOptional<z.ZodObject<{
+            maxInputTokensPerImage: z.ZodNumber;
+        }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export type DeclaredModel = z.infer<typeof declaredModelSchema>;
+export type DeclaredImageInput = z.infer<typeof declaredImageInputSchema>;
 export type DeclaredCatalogue = z.infer<typeof declaredCatalogueSchema>;
 export type AvailabilityScope = z.infer<typeof availabilityScopeSchema>;
 export type CommercialPermission = z.infer<typeof commercialPermissionSchema>;

package/dist/internal/catalogue.js

@@ -354,6 +354,28 @@ export const modelCatalogueEntrySchema = z.object({
      */
     powerClass: modelPowerClassSchema.optional(),
 });
+/**
+ * What a model line's image input costs at most, as the line's own documented
+ * rule states it (contract set 8.2.0, Kaana ADR 0007). Internal: Oxy reads it
+ * from the declared catalogue to bound the input of a request carrying images;
+ * `GET /v1/models` does not serve it.
+ *
+ * `maxInputTokensPerImage` is the most input tokens the line's provider bills
+ * for ONE image the contract admits (`checkImageInput`), at any `detail` the
+ * contract offers, from the publisher's documented resize and tokenization
+ * rule. Images are billed as input tokens at the line's `input_tokens` price;
+ * this figure only sizes a hold and qualifies a route, the settlement is the
+ * provider's own count.
+ *
+ * ABSENT means undeclared, even on a model whose `inputModalities` lists
+ * `image`: nobody has stated what one image costs on it, so no request carrying
+ * an image is authorized on it.
+ */
+export const declaredImageInputSchema = z
+    .object({
+    maxInputTokensPerImage: z.number().int().positive().safe(),
+})
+    .strict();
 /**
  * One model as Kaana DECLARES it in `configs/public-catalogue.json` (Kaana ADR
  * 0002, amendment 2026-10-15): the public `modelSchema` without the three
@@ -368,8 +390,20 @@ export const modelCatalogueEntrySchema = z.object({
  */
 export const declaredModelSchema = modelSchema
     .omit({ schemaVersion: true, currentRevision: true, availableRevisions: true })
-    .extend({ audience: z.enum(['public', 'platform_internal']) })
-    .strict();
+    .extend({
+    audience: z.enum(['public', 'platform_internal']),
+    imageInput: declaredImageInputSchema.optional(),
+})
+    .strict()
+    .superRefine((model, ctx) => {
+    if (model.imageInput !== undefined && !model.capabilities.inputModalities.includes('image')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['imageInput'],
+            message: 'a model that bounds its image input takes image input',
+        });
+    }
+});
 /**
  * The declared catalogue: identity, publisher, licence, provenance, data
  * policy, capabilities, voices and the LIST PRICE per unit of every model

package/dist/internal/grant.d.ts

@@ -74,6 +74,7 @@ export declare const grantRequestFactsSchema: z.ZodObject<{
     audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
     embeddingInputs: z.ZodOptional<z.ZodNumber>;
     images: z.ZodOptional<z.ZodNumber>;
+    inputImages: z.ZodOptional<z.ZodNumber>;
     declaredTools: z.ZodNumber;
     stream: z.ZodBoolean;
     realtimeSessionKind: z.ZodOptional<z.ZodEnum<{
@@ -125,6 +126,7 @@ export declare const inferenceAuthorizationRequestSchema: z.ZodObject<{
         audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
         embeddingInputs: z.ZodOptional<z.ZodNumber>;
         images: z.ZodOptional<z.ZodNumber>;
+        inputImages: z.ZodOptional<z.ZodNumber>;
         declaredTools: z.ZodNumber;
         stream: z.ZodBoolean;
         realtimeSessionKind: z.ZodOptional<z.ZodEnum<{
@@ -204,6 +206,7 @@ export declare const authorizationRequestSchema: z.ZodDiscriminatedUnion<[z.ZodO
         audioInputMilliseconds: z.ZodOptional<z.ZodNumber>;
         embeddingInputs: z.ZodOptional<z.ZodNumber>;
         images: z.ZodOptional<z.ZodNumber>;
+        inputImages: z.ZodOptional<z.ZodNumber>;
         declaredTools: z.ZodNumber;
         stream: z.ZodBoolean;
         realtimeSessionKind: z.ZodOptional<z.ZodEnum<{

package/dist/internal/grant.js

@@ -22,7 +22,7 @@ import { maxUtf16Length, minUtf16Length } from '../stringBounds.js';
 import { powerLevelSchema, realtimeSessionKindSchema } from '../public/catalogue.js';
 import { generationRecordSchema } from '../public/generations.js';
 import { delegatedUserIdSchema, generationIdSchema, idempotencyKeySchema, inferenceEnvironmentSchema, inferenceRegionSchema, inferenceTimestampSchema, modelIdSchema, modelRevisionLabelSchema, oxyApplicationIdSchema, oxyCredentialIdSchema, requestIdSchema, } from '../public/identifiers.js';
-import { requestLabelsSchema } from '../public/messages.js';
+import { MAX_INPUT_IMAGES, requestLabelsSchema } from '../public/messages.js';
 import { moneySchema } from '../public/money.js';
 import { routingPolicyReferenceSchema } from '../public/policy.js';
 import { inferenceScopeSchema } from './attribution.js';
@@ -107,6 +107,13 @@ export const grantRequestFactsSchema = z
     /** Embeddings: how many inputs. Images: how many images. */
     embeddingInputs: z.number().int().positive().max(2048).optional(),
     images: z.number().int().positive().max(10).optional(),
+    /**
+     * Completions: how many image parts the input carries (contract set 8.2.0,
+     * Kaana ADR 0007), present exactly when it carries one. Their bytes are not
+     * in `estimatedInputTokens`: Oxy bounds each image by the line's declared
+     * `imageInput.maxInputTokensPerImage` and admits only lines that declare it.
+     */
+    inputImages: z.number().int().positive().max(MAX_INPUT_IMAGES).optional(),
     /** How many tools the request declares; their definitions stay in Kaana. */
     declaredTools: z.number().int().nonnegative().max(128),
     stream: z.boolean(),

package/dist/public/messages.d.ts

@@ -95,6 +95,61 @@ export declare const inferenceContentPartSchema: z.ZodDiscriminatedUnion<[z.ZodO
     type: z.ZodLiteral<"refusal">;
     text: z.ZodString;
 }, z.core.$strict>], "type">;
+/**
+ * The image formats a request may carry. Every provider that serves image input
+ * on a Kaana route reads these four: Anthropic (`image/jpeg`, `image/png`,
+ * `image/gif`, `image/webp`) and OpenAI (PNG, JPEG, WEBP, non-animated GIF).
+ */
+export declare const INPUT_IMAGE_MEDIA_TYPES: readonly ["image/png", "image/jpeg", "image/webp", "image/gif"];
+/**
+ * The most image parts one request may carry, across every message. Above 20
+ * images Anthropic applies a stricter per-image dimension limit to EVERY image
+ * of the request, so 20 is the most a request can carry and keep one rule per
+ * image on every route.
+ */
+export declare const MAX_INPUT_IMAGES = 20;
+/**
+ * The most decoded bytes one image may carry: 3,750,000, whose base64 is
+ * 5,000,000 characters, the smallest per-image limit a provider serving these
+ * routes documents (Anthropic on Amazon Bedrock: 5 MB base64-encoded).
+ */
+export declare const MAX_INPUT_IMAGE_BYTES = 3750000;
+/** Why one image part cannot be carried, before anything is held. Never the image itself. */
+export interface ImageInputIssue {
+    /** The message, as its index in the request's message list. */
+    readonly messageIndex: number;
+    /** The part, as its index in that message's content; absent for the request-wide count. */
+    readonly partIndex?: number;
+    /** The field at fault, relative to the part. */
+    readonly field: 'role' | 'source' | 'source.mediaType' | 'source.data' | 'count';
+    readonly message: string;
+}
+/**
+ * Check the image parts of a conversation against the contract's image rules
+ * (Kaana ADR 0007). Kaana refuses a request with `invalid_request` and the first
+ * issue BEFORE it asks Oxy for a grant; Oxy applies the same rules on its own
+ * edge; a client may run it first.
+ *
+ *  - an image is `inline`: no component fetches an image URL, and a `url`
+ *    source is never forwarded to a provider to fetch either;
+ *  - its media type is one of {@link INPUT_IMAGE_MEDIA_TYPES};
+ *  - its data is canonical base64 of at most {@link MAX_INPUT_IMAGE_BYTES} bytes;
+ *  - it rides on a `user` or `tool` message;
+ *  - the request carries at most {@link MAX_INPUT_IMAGES} of them.
+ *
+ * Returns the number of image parts and every issue, in message order. An issue
+ * names where and why, never the bytes: an image is payload and is never echoed
+ * into an error, a log line or a record.
+ */
+export declare function checkImageInput(messages: readonly InferenceMessage[]): {
+    readonly images: number;
+    readonly issues: ImageInputIssue[];
+};
+/**
+ * The decoded length of canonical base64 (RFC 4648 section 4, padded, no line
+ * breaks), or `undefined` when the text is not that. Counted, never decoded.
+ */
+export declare function base64DecodedLength(data: string): number | undefined;
 /**
  * A tool call an assistant made, in the normalized form.
  *

package/dist/public/messages.js

@@ -86,6 +86,113 @@ export const inferenceContentPartSchema = z.discriminatedUnion('type', [
      */
     z.object({ type: z.literal('refusal'), text: z.string() }).strict(),
 ]);
+/* -------------------------------------------------------------------------- */
+/*  Image input (contract set 8.2.0, Kaana ADR 0007)                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * The image formats a request may carry. Every provider that serves image input
+ * on a Kaana route reads these four: Anthropic (`image/jpeg`, `image/png`,
+ * `image/gif`, `image/webp`) and OpenAI (PNG, JPEG, WEBP, non-animated GIF).
+ */
+export const INPUT_IMAGE_MEDIA_TYPES = [
+    'image/png',
+    'image/jpeg',
+    'image/webp',
+    'image/gif',
+];
+/**
+ * The most image parts one request may carry, across every message. Above 20
+ * images Anthropic applies a stricter per-image dimension limit to EVERY image
+ * of the request, so 20 is the most a request can carry and keep one rule per
+ * image on every route.
+ */
+export const MAX_INPUT_IMAGES = 20;
+/**
+ * The most decoded bytes one image may carry: 3,750,000, whose base64 is
+ * 5,000,000 characters, the smallest per-image limit a provider serving these
+ * routes documents (Anthropic on Amazon Bedrock: 5 MB base64-encoded).
+ */
+export const MAX_INPUT_IMAGE_BYTES = 3_750_000;
+/**
+ * Check the image parts of a conversation against the contract's image rules
+ * (Kaana ADR 0007). Kaana refuses a request with `invalid_request` and the first
+ * issue BEFORE it asks Oxy for a grant; Oxy applies the same rules on its own
+ * edge; a client may run it first.
+ *
+ *  - an image is `inline`: no component fetches an image URL, and a `url`
+ *    source is never forwarded to a provider to fetch either;
+ *  - its media type is one of {@link INPUT_IMAGE_MEDIA_TYPES};
+ *  - its data is canonical base64 of at most {@link MAX_INPUT_IMAGE_BYTES} bytes;
+ *  - it rides on a `user` or `tool` message;
+ *  - the request carries at most {@link MAX_INPUT_IMAGES} of them.
+ *
+ * Returns the number of image parts and every issue, in message order. An issue
+ * names where and why, never the bytes: an image is payload and is never echoed
+ * into an error, a log line or a record.
+ */
+export function checkImageInput(messages) {
+    const issues = [];
+    let images = 0;
+    for (const [messageIndex, message] of messages.entries()) {
+        for (const [partIndex, part] of message.content.entries()) {
+            if (part.type !== 'image')
+                continue;
+            images += 1;
+            const at = { messageIndex, partIndex };
+            if (message.role !== 'user' && message.role !== 'tool') {
+                issues.push({ ...at, field: 'role', message: 'an image rides on a user or tool message' });
+            }
+            const source = part.source;
+            if (source.kind !== 'inline') {
+                issues.push({
+                    ...at,
+                    field: 'source',
+                    message: 'an image is sent inline as base64; no image URL is fetched',
+                });
+                continue;
+            }
+            if (!INPUT_IMAGE_MEDIA_TYPES.includes(source.mediaType)) {
+                issues.push({
+                    ...at,
+                    field: 'source.mediaType',
+                    message: `an image is one of ${INPUT_IMAGE_MEDIA_TYPES.join(', ')}`,
+                });
+            }
+            const bytes = base64DecodedLength(source.data);
+            if (bytes === undefined) {
+                issues.push({ ...at, field: 'source.data', message: 'image data is canonical base64' });
+            }
+            else if (bytes > MAX_INPUT_IMAGE_BYTES) {
+                issues.push({
+                    ...at,
+                    field: 'source.data',
+                    message: `an image is at most ${MAX_INPUT_IMAGE_BYTES} bytes`,
+                });
+            }
+        }
+    }
+    if (images > MAX_INPUT_IMAGES) {
+        issues.push({
+            messageIndex: messages.length - 1,
+            field: 'count',
+            message: `a request carries at most ${MAX_INPUT_IMAGES} images`,
+        });
+    }
+    return { images, issues };
+}
+const BASE64_BODY = /^[A-Za-z0-9+/]*$/;
+/**
+ * The decoded length of canonical base64 (RFC 4648 section 4, padded, no line
+ * breaks), or `undefined` when the text is not that. Counted, never decoded.
+ */
+export function base64DecodedLength(data) {
+    if (data.length === 0 || data.length % 4 !== 0)
+        return undefined;
+    const padding = data.endsWith('==') ? 2 : data.endsWith('=') ? 1 : 0;
+    if (!BASE64_BODY.test(data.slice(0, data.length - padding)))
+        return undefined;
+    return (data.length / 4) * 3 - padding;
+}
 /**
  * A tool call an assistant made, in the normalized form.
  *

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.1.0";
+export declare const INFERENCE_CONTRACT_VERSION = "8.2.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:
@@ -187,6 +187,14 @@ export declare const INFERENCE_CONTRACT_VERSION = "8.1.0";
  * `transcript.interim` event it asks for, the provisional text of an input
  * item that the item's deltas and its `transcript.done` supersede. Any other
  * kind asking for interim text is refused. Nothing in 8.0.0 changes.
+ *
+ * Contract set 8.2.0 (Kaana ADR 0007) is additive: image input. The rules an
+ * image part answers to (`checkImageInput`, `INPUT_IMAGE_MEDIA_TYPES`,
+ * `MAX_INPUT_IMAGES`, `MAX_INPUT_IMAGE_BYTES`), the internal declared model's
+ * `imageInput` (the most input tokens one image costs on the line) and the
+ * grant fact `inputImages`. Every 8.1.0 message parses the same; a consumer on
+ * 8.1.0 or earlier refuses a declared catalogue or an authorization carrying
+ * what is new, so Oxy reads them before Kaana publishes them.
  */
 /** 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.1.0';
+export const INFERENCE_CONTRACT_VERSION = '8.2.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:
@@ -187,6 +187,14 @@ export const INFERENCE_CONTRACT_VERSION = '8.1.0';
  * `transcript.interim` event it asks for, the provisional text of an input
  * item that the item's deltas and its `transcript.done` supersede. Any other
  * kind asking for interim text is refused. Nothing in 8.0.0 changes.
+ *
+ * Contract set 8.2.0 (Kaana ADR 0007) is additive: image input. The rules an
+ * image part answers to (`checkImageInput`, `INPUT_IMAGE_MEDIA_TYPES`,
+ * `MAX_INPUT_IMAGES`, `MAX_INPUT_IMAGE_BYTES`), the internal declared model's
+ * `imageInput` (the most input tokens one image costs on the line) and the
+ * grant fact `inputImages`. Every 8.1.0 message parses the same; a consumer on
+ * 8.1.0 or earlier refuses a declared catalogue or an authorization carrying
+ * what is new, so Oxy reads them before Kaana publishes them.
  */
 /** 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.1.0",
+    "version": "8.2.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": [

package/package.json

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