@oxy.so/contracts 1.3.0 → 1.4.0

package/dist/esm/index.js

@@ -138,7 +138,7 @@ export {
 priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
 export { 
 // The six distinct catalogue objects + the customer-safe projection.
-inferenceModalitySchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
+inferenceModalitySchema, reasoningEffortSchema, modelCapabilitiesSchema, modelLicenseSchema, modelProvenanceSchema, inferenceDataPolicySchema, availabilityScopeSchema, commercialPermissionSchema, modelDeprecationSchema, modelEvaluationResultSchema, modelSafetyMetadataSchema, modelPublisherSchema, catalogueModelSchema, modelRevisionSchema, inferenceProviderSchema, modelDeploymentSchema, routingProfileCandidateSchema, routingProfileSchema, cataloguePublisherSummarySchema, catalogueServingProviderSummarySchema, modelCatalogueEntrySchema, } from './inference/catalogue.js';
 export { 
 // Routing policy: every control, plus the refinement that rejects a policy
 // no route could ever satisfy.
@@ -155,7 +155,7 @@ export {
 modelDistributionMethodSchema, modelSystemicRiskTierSchema, trainingComputeFlopsSchema, SYSTEMIC_RISK_COMPUTE_THRESHOLD_FLOPS, modelDownstreamDocumentationSchema, modelGpaiDocumentationSchema, modelLineDeclarationSchema, modelReleaseIngestionRequestSchema, modelReleaseIngestionResultSchema, modelDocumentationSchema, } from './inference/modelDocumentation.js';
 export { 
 // The normalized Oxy→data-plane request envelope.
-inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, inferenceReasoningSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
 export { 
 // Normalized SSE events.
 inferenceStreamStartEventSchema, inferenceStreamDeltaEventSchema, inferenceAudioMediaTypeSchema, MAX_INFERENCE_AUDIO_BYTES, inferenceStreamAudioEventSchema, inferenceStreamToolCallEventSchema, inferenceStreamUsageEventSchema, inferenceRouteSwitchDetailSchema, inferenceRouteSwitchReasonSchema, inferenceStreamRouteSwitchEventSchema, inferenceStreamErrorEventSchema, inferenceFinishReasonSchema, inferenceStreamDoneEventSchema, inferenceStreamEventSchema, } from './inference/streamEvents.js';

package/dist/esm/inference/catalogue.js

@@ -40,6 +40,15 @@ export const inferenceModalitySchema = z.enum([
     'video',
     'embedding',
 ]);
+/**
+ * How hard a reasoning model is asked to think before it answers.
+ *
+ * A closed, provider-neutral vocabulary: Kaana translates each value into the
+ * serving provider's own control. A model advertises the subset it accepts in
+ * `modelCapabilitiesSchema.reasoningEfforts`, and Oxy refuses a request for an
+ * effort the resolved model does not advertise rather than dropping it.
+ */
+export const reasoningEffortSchema = z.enum(['low', 'medium', 'high']);
 /**
  * What a model can do, in the terms a caller has to decide against before
  * sending a request: can it call tools, does it accept images, will it honour a
@@ -54,6 +63,13 @@ export const modelCapabilitiesSchema = z
     structuredOutput: z.boolean(),
     jsonMode: z.boolean(),
     reasoning: z.boolean(),
+    /**
+     * The reasoning efforts a request may name for this model, in the order
+     * low → high. Empty means the model takes no effort control at all (it may
+     * still reason: `reasoning` answers that). Added in contract set 3.1.0;
+     * absent on the wire from an older producer, it parses as `[]`.
+     */
+    reasoningEfforts: z.array(reasoningEffortSchema).default([]),
     streaming: z.boolean(),
     promptCaching: z.boolean(),
     maxContextTokens: z.number().int().positive().safe(),
@@ -469,6 +485,12 @@ export const modelCatalogueEntrySchema = z.object({
     provenance: modelProvenanceSchema,
     knowledgeCutoff: inferenceDateSchema.optional(),
     releasedOn: inferenceDateSchema.optional(),
+    /**
+     * When the upstream provider first published this model, as that provider
+     * reports it. Present only when a provider reported it; never an Oxy or Kaana
+     * observation time. Lets a picker order models newest first.
+     */
+    releasedAt: inferenceTimestampSchema.optional(),
     regions: z.array(inferenceRegionSchema).default([]),
     servingProviders: z.array(catalogueServingProviderSummarySchema).default([]),
     dataPolicy: inferenceDataPolicySchema,

package/dist/esm/inference/request.js

@@ -25,7 +25,7 @@
  */
 import { z } from "zod";
 import { inferenceAttributionSchema } from "./attribution.js";
-import { inferenceModalitySchema } from "./catalogue.js";
+import { inferenceModalitySchema, reasoningEffortSchema } from "./catalogue.js";
 import { idempotencyKeySchema, inferenceTimestampSchema } from "./identifiers.js";
 import { authorizedRouteSchema, routingPolicyReferenceSchema, routingTargetSchema, } from "./routingPolicy.js";
 /* -------------------------------------------------------------------------- */
@@ -260,6 +260,16 @@ export const responseFormatSchema = z.discriminatedUnion("type", [
     })
         .strict(),
 ]);
+/**
+ * The caller's reasoning control. Strict, like every leaf: a provider-specific
+ * knob (`budget_tokens`, `summary`) is refused rather than silently dropped.
+ *
+ * Oxy forwards it only after checking the resolved model advertises the effort
+ * in its catalogue `reasoningEfforts`; Kaana translates it per provider.
+ */
+export const inferenceReasoningSchema = z
+    .object({ effort: reasoningEffortSchema })
+    .strict();
 /* -------------------------------------------------------------------------- */
 /*  Client metadata                                                           */
 /* -------------------------------------------------------------------------- */
@@ -336,6 +346,8 @@ export const inferenceRequestSchema = z
     stream: z.boolean(),
     maxOutputTokens: z.number().int().positive().safe().optional(),
     sampling: samplingParametersSchema,
+    /** Absent means the route's own default reasoning behaviour. */
+    reasoning: inferenceReasoningSchema.optional(),
     speech: inferenceSpeechParametersSchema.optional(),
     tools: z.array(toolDefinitionSchema).default([]),
     toolChoice: toolChoiceSchema.optional(),

package/dist/esm/inference/version.js

@@ -99,4 +99,4 @@
  * 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 = '3.0.0';
+export const INFERENCE_CONTRACT_VERSION = '3.1.0';