@oxy.so/contracts 4.2.0 → 4.4.0

package/dist/esm/index.js

@@ -134,7 +134,7 @@ export {
 priceVersionStatusSchema, priceVersionSchema, priceSnapshotSchema, } from './inference/priceVersion.js';
 export { 
 // The six distinct catalogue objects + the customer-safe projection.
-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';
+inferenceModalitySchema, reasoningEffortSchema, inferenceApiFormatSchema, realtimeSessionKindSchema, realtimeSessionTransportSchema, modelRealtimeCapabilitiesSchema, 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.
@@ -151,11 +151,14 @@ 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, inferenceReasoningSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, } from './inference/request.js';
+inferenceContentSourceSchema, inferenceContentPartSchema, inferenceToolCallSchema, inferenceMessageRoleSchema, inferenceMessageSchema, inferenceInputSchema, samplingParametersSchema, inferenceReasoningSchema, toolDefinitionSchema, toolChoiceSchema, responseFormatSchema, clientRequestMetadataSchema, inferenceRequestSchema, inferenceSpeechParametersSchema, inferenceAudioOutputParametersSchema, } 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';
 export { 
+// Realtime sessions: the signed session request, client commands, server events.
+MAX_REALTIME_AUDIO_FRAME_BASE64_LENGTH, MAX_REALTIME_SESSION_DURATION_MS, MAX_REALTIME_SESSION_AUDIO_BYTES, MAX_REALTIME_RESUME_WINDOW_MS, realtimeCommandIdSchema, realtimeItemIdSchema, realtimeResponseIdSchema, realtimeAudioFormatSchema, realtimeOutputModalitySchema, realtimeTurnDetectionSchema, realtimeInputTranscriptionSchema, realtimeTranslationSchema, realtimeSessionConfigSchema, realtimeSessionConfigUpdateSchema, realtimeSessionLimitsSchema, realtimeClientMetadataSchema, realtimeSessionRequestSchema, realtimeContentPartSchema, realtimeConversationItemSchema, realtimeResponseParametersSchema, realtimeSessionUpdateCommandSchema, realtimeItemCreateCommandSchema, realtimeItemDeleteCommandSchema, realtimeItemTruncateCommandSchema, realtimeInputAudioAppendCommandSchema, realtimeInputAudioCommitCommandSchema, realtimeInputAudioClearCommandSchema, realtimeResponseCreateCommandSchema, realtimeResponseCancelCommandSchema, realtimeSessionResumeCommandSchema, realtimeSessionCloseCommandSchema, realtimeClientCommandSchema, realtimeSessionCreatedEventSchema, realtimeSessionUpdatedEventSchema, realtimeSessionResumedEventSchema, realtimeCommandAcceptedEventSchema, realtimeItemAddedEventSchema, realtimeItemDoneEventSchema, realtimeItemDeletedEventSchema, realtimeItemTruncatedEventSchema, realtimeSpeechStartedEventSchema, realtimeSpeechStoppedEventSchema, realtimeInputAudioCommittedEventSchema, realtimeInputAudioClearedEventSchema, realtimeResponseCreatedEventSchema, realtimeOutputAudioDeltaEventSchema, realtimeOutputAudioDoneEventSchema, realtimeTranscriptSourceSchema, realtimeTranscriptDeltaEventSchema, realtimeTranscriptDoneEventSchema, realtimeTextDeltaEventSchema, realtimeToolCallEventSchema, realtimeResponseStatusSchema, realtimeResponseDoneEventSchema, realtimeErrorEventSchema, realtimeSessionCloseReasonSchema, realtimeSessionClosedEventSchema, realtimeServerEventSchema, } from './inference/realtime.js';
+export { 
 // Reserve → settle → refund.
 usageReservationRequestSchema, usageReservationStatusSchema, usageReservationSchema, inferenceRequestOutcomeSchema, normalizedUsageReportSchema, usageReceiptSchema, usageRefundSubjectSchema, usageRefundReasonSchema, usageRefundSchema, } from './inference/usage.js';
 export { 
@@ -178,3 +181,4 @@ export * from './linkedAccounts.js';
 export * from './federationInstanceFetch.js';
 export * from './notifications.js';
 export * from './email/messages.js';
+export * from './stickers.js';

package/dist/esm/inference/catalogue.js

@@ -49,6 +49,57 @@ export const inferenceModalitySchema = z.enum([
  * effort the resolved model does not advertise rather than dropping it.
  */
 export const reasoningEffortSchema = z.enum(['low', 'medium', 'high']);
+/**
+ * The public dialects a request can arrive in — `client.apiFormat` on the
+ * envelope, and the list a deployment declares it can execute.
+ *
+ * Named (contract set 3.2.0) rather than inline on the client metadata so the
+ * two uses cannot drift: a capability naming a dialect the envelope cannot
+ * carry, or the reverse, would authorize a request no route can serve.
+ */
+export const inferenceApiFormatSchema = z.enum([
+    'responses',
+    'chat_completions',
+    'embeddings',
+    'images_generations',
+    'audio_transcriptions',
+    'audio_speech',
+    'rerank',
+    'batches',
+]);
+/**
+ * What a realtime session is FOR. The three are different upstream products
+ * with different event families and different metering, not options of one:
+ *
+ *  - `conversation` — a speech-to-speech (or text) model holding a dialogue,
+ *    with responses, tool calls and interruption.
+ *  - `transcription` — live speech-to-text; the model never responds, it only
+ *    transcribes committed input audio.
+ *  - `translation` — live speech-to-speech translation into one target language.
+ */
+export const realtimeSessionKindSchema = z.enum([
+    'conversation',
+    'transcription',
+    'translation',
+]);
+/**
+ * How a realtime session is carried. One member today: a WebSocket, whose every
+ * frame is one JSON message (see `realtime.ts`). WebRTC and SIP are separate
+ * transports with separate media handling, and are added as members only when a
+ * deployment can actually execute them.
+ */
+export const realtimeSessionTransportSchema = z.enum(['websocket']);
+/**
+ * What a deployment can execute as a realtime session. Present only on a model
+ * that holds sessions; absent means it holds none, which is the state of every
+ * catalogue written before contract set 3.2.0.
+ */
+export const modelRealtimeCapabilitiesSchema = z
+    .object({
+    transports: z.array(realtimeSessionTransportSchema).min(1),
+    sessionKinds: z.array(realtimeSessionKindSchema).min(1),
+})
+    .strict();
 /**
  * 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
@@ -74,8 +125,60 @@ export const modelCapabilitiesSchema = z
     promptCaching: z.boolean(),
     maxContextTokens: z.number().int().positive().safe(),
     maxOutputTokens: z.number().int().positive().safe(),
+    /**
+     * The request dialects a route to this model can EXECUTE. Modalities say
+     * what a model consumes and produces; they do not say which request shape a
+     * route can carry, and catalogue presence is not that evidence either — a
+     * speech-to-speech model is `audio` in and out and still cannot answer a
+     * `/v1/audio/transcriptions` upload. Oxy authorizes a request only when its
+     * `client.apiFormat` is listed here.
+     *
+     * Added in contract set 3.2.0. ABSENT means undeclared — a catalogue from an
+     * older producer — never "every format": a consumer then applies the rules it
+     * applied before this field existed, and authorizes no format that needs a
+     * declaration (audio output on `chat_completions`, a realtime session).
+     */
+    apiFormats: z.array(inferenceApiFormatSchema).min(1).optional(),
+    /** Realtime sessions this model holds; absent means none. Contract set 3.2.0. */
+    realtime: modelRealtimeCapabilitiesSchema.optional(),
 })
-    .strict();
+    .strict()
+    .superRefine((capabilities, ctx) => {
+    const formats = capabilities.apiFormats;
+    if (formats !== undefined && new Set(formats).size !== formats.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['apiFormats'],
+            message: 'each API format is declared at most once',
+        });
+    }
+    const realtime = capabilities.realtime;
+    if (realtime === undefined)
+        return;
+    if (new Set(realtime.sessionKinds).size !== realtime.sessionKinds.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['realtime', 'sessionKinds'],
+            message: 'each session kind is declared at most once',
+        });
+    }
+    if (new Set(realtime.transports).size !== realtime.transports.length) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['realtime', 'transports'],
+            message: 'each transport is declared at most once',
+        });
+    }
+    // A realtime session consumes audio: a model that declares sessions and no
+    // audio input is a declaration no session could honour.
+    if (!capabilities.inputModalities.includes('audio')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['realtime'],
+            message: 'a model that holds realtime sessions consumes audio',
+        });
+    }
+});
 /**
  * License terms, including the two questions that decide whether Oxy may serve
  * a model to third parties at all: is commercial use permitted, and must the

package/dist/esm/inference/money.js

@@ -112,6 +112,26 @@ export const moneySchema = z
  * output_tokens = completion_tokens - completion_tokens_details.reasoning_tokens
  * ```
  *
+ * **Audio tokens are siblings too** (added in contract set 3.2.0). A model that
+ * consumes or produces audio AS TOKENS — OpenAI's audio chat and Realtime
+ * models — reports them inside the same totals, and they are priced several
+ * times higher than text tokens, so folding them into `input_tokens` would
+ * under-charge by exactly the audio. They are subtracted out the same way:
+ *
+ * ```text
+ * cached_audio_input_tokens = prompt_tokens_details.cached_tokens_details.audio_tokens
+ * audio_input_tokens        = prompt_tokens_details.audio_tokens - cached_audio_input_tokens
+ * input_tokens              = prompt_tokens - (text AND audio cached) - audio_input_tokens
+ * audio_output_tokens       = completion_tokens_details.audio_tokens
+ * output_tokens             = completion_tokens - reasoning_tokens - audio_output_tokens
+ * ```
+ *
+ * `audio_input_milliseconds` and `audio_output_milliseconds` remain the units
+ * for audio metered by DURATION (file transcription, speech synthesis). A
+ * report carries one reading of a given audio, never both: the same audio
+ * reported as tokens and as milliseconds is the double charge this rule exists
+ * to prevent.
+ *
  * No refinement in this package can enforce it, and saying so is part of the
  * rule: a nested report and a disjoint one are the same four non-negative
  * integers, so no predicate over a single report can tell them apart. The two
@@ -145,6 +165,9 @@ export const USAGE_UNITS = [
     'video_milliseconds',
     'characters',
     'embeddings',
+    'audio_input_tokens',
+    'cached_audio_input_tokens',
+    'audio_output_tokens',
 ];
 export const usageUnitSchema = z.enum(USAGE_UNITS);
 /**