@oxyhq/contracts 0.26.0 → 0.28.0

package/dist/cjs/inference/request.js

@@ -0,0 +1,288 @@
+"use strict";
+/**
+ * The normalized inference request — the canonical internal envelope Oxy's
+ * public edge forwards to the data plane.
+ *
+ * The public surface speaks several dialects (`/v1/responses`,
+ * `/v1/chat/completions`, embeddings, images, audio). Exactly one of them is
+ * normalized here, at the edge, so that routing, metering, policy enforcement
+ * and settlement are written once against one shape instead of once per dialect.
+ * `client.apiFormat` records which dialect the customer used, because the
+ * response has to be rendered back in it.
+ *
+ * What the envelope carries that a provider request does not: the resolved
+ * attribution block (who pays, which application, which credential, which
+ * delegated user), the exact routing policy reference and the customer's
+ * idempotency key. Those are the fields that make a request billable and
+ * explainable, and they are resolved BEFORE the request enters the data plane.
+ *
+ * Decided in: docs/adr/0010-public-api-compatibility.md.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inferenceRequestSchema = exports.clientRequestMetadataSchema = exports.responseFormatSchema = exports.toolChoiceSchema = exports.toolDefinitionSchema = exports.samplingParametersSchema = exports.inferenceInputSchema = exports.inferenceMessageSchema = exports.inferenceMessageRoleSchema = exports.inferenceToolCallSchema = exports.inferenceContentPartSchema = exports.inferenceContentSourceSchema = void 0;
+const zod_1 = require("zod");
+const attribution_1 = require("./attribution");
+const catalogue_1 = require("./catalogue");
+const identifiers_1 = require("./identifiers");
+const routingPolicy_1 = require("./routingPolicy");
+/* -------------------------------------------------------------------------- */
+/*  Input                                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * Where binary or remote content comes from.
+ *
+ * `url` is fetched by the data plane; `inline` carries base64 the customer sent
+ * with the request. Both are transient: neither is persisted by default, and
+ * neither appears in a receipt, a log line or a telemetry event.
+ */
+exports.inferenceContentSourceSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('url'), url: zod_1.z.string().min(1).max(4096) }).strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('inline'),
+        mediaType: zod_1.z.string().min(1).max(255),
+        data: zod_1.z.string().min(1),
+    })
+        .strict(),
+]);
+/** One part of a message's content. A message is always a list of parts. */
+exports.inferenceContentPartSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({ type: zod_1.z.literal('text'), text: zod_1.z.string() }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal('image'),
+        source: exports.inferenceContentSourceSchema,
+        /** Provider-independent hint; providers that ignore it are unaffected. */
+        detail: zod_1.z.enum(['auto', 'low', 'high']).optional(),
+    })
+        .strict(),
+    zod_1.z.object({ type: zod_1.z.literal('audio'), source: exports.inferenceContentSourceSchema }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal('file'),
+        source: exports.inferenceContentSourceSchema,
+        filename: zod_1.z.string().max(255).optional(),
+    })
+        .strict(),
+]);
+/**
+ * A tool call an assistant made, in the normalized form.
+ *
+ * `arguments` is the JSON TEXT the model emitted, not a parsed object: models
+ * emit invalid JSON often enough that parsing it here would turn a recoverable
+ * model mistake into a rejected message.
+ */
+exports.inferenceToolCallSchema = zod_1.z
+    .object({
+    id: zod_1.z.string().min(1).max(128),
+    name: zod_1.z.string().min(1).max(128),
+    arguments: zod_1.z.string(),
+})
+    .strict();
+exports.inferenceMessageRoleSchema = zod_1.z.enum([
+    'system',
+    'developer',
+    'user',
+    'assistant',
+    'tool',
+]);
+/**
+ * One normalized message.
+ *
+ * The role-specific fields are refined rather than modelled as a discriminated
+ * union so the shape stays the one a caller recognises from the OpenAI-style
+ * dialects; the refinement is what stops `toolCallId` from riding on a user
+ * message, where every provider would silently ignore it.
+ */
+exports.inferenceMessageSchema = zod_1.z
+    .object({
+    role: exports.inferenceMessageRoleSchema,
+    content: zod_1.z.array(exports.inferenceContentPartSchema),
+    /** Participant name, where the dialect supports naming participants. */
+    name: zod_1.z.string().max(128).optional(),
+    /** The tool call this message answers. Required on, and only on, `tool`. */
+    toolCallId: zod_1.z.string().min(1).max(128).optional(),
+    /** Tool calls the assistant made. Only on `assistant`. */
+    toolCalls: zod_1.z.array(exports.inferenceToolCallSchema).optional(),
+})
+    .strict()
+    .superRefine((message, ctx) => {
+    if (message.role === 'tool' && message.toolCallId === undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['toolCallId'],
+            message: 'a tool message must name the tool call it answers',
+        });
+    }
+    if (message.role !== 'tool' && message.toolCallId !== undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['toolCallId'],
+            message: 'only a tool message answers a tool call',
+        });
+    }
+    if (message.role !== 'assistant' && message.toolCalls !== undefined) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['toolCalls'],
+            message: 'only an assistant message makes tool calls',
+        });
+    }
+});
+/**
+ * The request's input.
+ *
+ * Three formats, because the modalities genuinely differ: a chat request is a
+ * conversation, an embedding request is a string or a batch of strings, and
+ * pretending the latter is a one-message conversation loses the batch boundary
+ * that both metering and provider translation depend on.
+ */
+exports.inferenceInputSchema = zod_1.z.discriminatedUnion('format', [
+    zod_1.z
+        .object({
+        format: zod_1.z.literal('messages'),
+        messages: zod_1.z.array(exports.inferenceMessageSchema).min(1),
+    })
+        .strict(),
+    zod_1.z.object({ format: zod_1.z.literal('text'), text: zod_1.z.string() }).strict(),
+    zod_1.z
+        .object({
+        format: zod_1.z.literal('text_batch'),
+        texts: zod_1.z.array(zod_1.z.string()).min(1).max(2048),
+    })
+        .strict(),
+]);
+/* -------------------------------------------------------------------------- */
+/*  Generation controls                                                       */
+/* -------------------------------------------------------------------------- */
+/** Sampling parameters, all optional: absent means the route's own default. */
+exports.samplingParametersSchema = zod_1.z
+    .object({
+    temperature: zod_1.z.number().min(0).max(2).optional(),
+    topP: zod_1.z.number().min(0).max(1).optional(),
+    topK: zod_1.z.number().int().positive().safe().optional(),
+    frequencyPenalty: zod_1.z.number().min(-2).max(2).optional(),
+    presencePenalty: zod_1.z.number().min(-2).max(2).optional(),
+    /** A seed makes a request reproducible on providers that honour one. */
+    seed: zod_1.z.number().int().safe().optional(),
+    stopSequences: zod_1.z.array(zod_1.z.string().min(1).max(256)).max(8).optional(),
+})
+    .strict();
+/**
+ * A tool the model may call. `parameters` is a JSON Schema document, carried
+ * as an opaque object: validating the customer's JSON Schema against a meta
+ * schema here would reject documents providers accept.
+ */
+exports.toolDefinitionSchema = zod_1.z
+    .object({
+    type: zod_1.z.literal('function'),
+    name: zod_1.z.string().min(1).max(128),
+    description: zod_1.z.string().max(2000).optional(),
+    parameters: zod_1.z.record(zod_1.z.unknown()),
+    /** Ask the provider to enforce the schema, where it supports enforcement. */
+    strict: zod_1.z.boolean().optional(),
+})
+    .strict();
+/** Whether, and which, tool the model must call. */
+exports.toolChoiceSchema = zod_1.z.union([
+    zod_1.z.enum(['auto', 'none', 'required']),
+    zod_1.z.object({ type: zod_1.z.literal('function'), name: zod_1.z.string().min(1).max(128) }).strict(),
+]);
+/** Structured-output request: free text, any JSON object, or a named schema. */
+exports.responseFormatSchema = zod_1.z.discriminatedUnion('type', [
+    zod_1.z.object({ type: zod_1.z.literal('text') }).strict(),
+    zod_1.z.object({ type: zod_1.z.literal('json_object') }).strict(),
+    zod_1.z
+        .object({
+        type: zod_1.z.literal('json_schema'),
+        name: zod_1.z.string().min(1).max(128),
+        schema: zod_1.z.record(zod_1.z.unknown()),
+        strict: zod_1.z.boolean(),
+    })
+        .strict(),
+]);
+/* -------------------------------------------------------------------------- */
+/*  Client metadata                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * What the edge records about the CALL, as opposed to its content.
+ *
+ * `.strict()` is a privacy control, not tidiness. Oxy never persists a user IP
+ * — raw, hashed or geo-derived — and this object is the natural place somebody
+ * would add one "for security". Strict means a producer that attaches `ip`,
+ * `country`, `userAgent` or `forwardedFor` fails the parse instead of quietly
+ * shipping it into the data plane and the telemetry stream behind it.
+ *
+ * `labels` is customer-supplied cost-attribution metadata (a team name, a
+ * feature flag). It is echoed on the receipt, so it must never be used for
+ * anything the customer would not want to read back to themselves.
+ */
+exports.clientRequestMetadataSchema = zod_1.z
+    .object({
+    /** The public dialect the customer called. The response is rendered in it. */
+    apiFormat: zod_1.z.enum([
+        'responses',
+        'chat_completions',
+        'embeddings',
+        'images_generations',
+        'audio_transcriptions',
+        'audio_speech',
+        'rerank',
+        'batches',
+    ]),
+    /** The public path, e.g. `/v1/responses`. */
+    endpoint: zod_1.z.string().min(1).max(256),
+    /** The customer's own correlation id, when they sent one. */
+    clientRequestId: zod_1.z.string().min(1).max(128).optional(),
+    receivedAt: identifiers_1.inferenceTimestampSchema,
+    labels: zod_1.z.record(zod_1.z.string().max(256)).optional(),
+})
+    .strict();
+/* -------------------------------------------------------------------------- */
+/*  The envelope                                                              */
+/* -------------------------------------------------------------------------- */
+/**
+ * The canonical internal request Oxy forwards to the data plane.
+ *
+ * `target` distinguishes the two questions a caller can ask — "serve THIS
+ * model" versus "choose one for me" — structurally. Everything downstream that
+ * must not silently substitute a model reads that discriminant rather than
+ * inferring intent from a string.
+ */
+exports.inferenceRequestSchema = zod_1.z
+    .object({
+    /** See `version.ts`: this is the Oxy→data-plane request envelope. */
+    schemaVersion: zod_1.z.literal(1),
+    attribution: attribution_1.inferenceAttributionSchema,
+    target: routingPolicy_1.routingTargetSchema,
+    modality: catalogue_1.inferenceModalitySchema,
+    input: exports.inferenceInputSchema,
+    stream: zod_1.z.boolean(),
+    maxOutputTokens: zod_1.z.number().int().positive().safe().optional(),
+    sampling: exports.samplingParametersSchema,
+    tools: zod_1.z.array(exports.toolDefinitionSchema).default([]),
+    toolChoice: exports.toolChoiceSchema.optional(),
+    responseFormat: exports.responseFormatSchema.optional(),
+    client: exports.clientRequestMetadataSchema,
+    /** Present when the operation is safe to deduplicate on retry. */
+    idempotencyKey: identifiers_1.idempotencyKeySchema.optional(),
+    /** The exact policy revision this request is served under. */
+    routingPolicy: routingPolicy_1.routingPolicyReferenceSchema,
+})
+    .superRefine((request, ctx) => {
+    if (request.toolChoice !== undefined && request.tools.length === 0) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['toolChoice'],
+            message: 'a tool choice requires at least one tool definition',
+        });
+    }
+    const toolNames = request.tools.map((tool) => tool.name);
+    if (new Set(toolNames).size !== toolNames.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['tools'],
+            message: 'tool names must be unique within one request',
+        });
+    }
+});

package/dist/cjs/inference/routingPolicy.js

@@ -0,0 +1,213 @@
+"use strict";
+/**
+ * Routing policy — the customer-facing routing configuration.
+ *
+ * Stored under an Oxy account or application (the control plane owns it),
+ * executed by the data plane, which owns execution. Every request records the
+ * exact `{routingPolicyId, policyVersion}` it was served under, so a route
+ * decision months old can be explained against the policy that was in force,
+ * not against the policy that exists now.
+ *
+ * Two rules shape the fallback controls:
+ *
+ *  - **Same-model deployment failover is not cross-model fallback.** Moving
+ *    between two deployments of the SAME revision is an availability decision
+ *    and is on by default; serving a DIFFERENT model is a substitution the
+ *    customer must have authorized by name.
+ *  - **A request for a concrete model is never silently replaced.** Cross-model
+ *    fallback is an explicit list of references, and a switch that uses it emits
+ *    a customer-visible route-switch event.
+ *
+ * The controls are flat and independent, matching what Console renders — which
+ * means contradictory combinations are EXPRESSIBLE and must therefore be
+ * REJECTED, rather than being quietly resolved by whichever field the executor
+ * happens to read first. That rejection is `routingPolicySchema`'s refinement.
+ *
+ * Decided in: docs/adr/0008-catalogue-concept-separation.md, issue #972 workstream 6.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.routingPolicyReferenceSchema = exports.routingPolicySchema = exports.routingFallbackPolicySchema = exports.routingPolicyScopeSchema = exports.routingTargetSchema = void 0;
+const zod_1 = require("zod");
+const identifiers_1 = require("./identifiers");
+const money_1 = require("./money");
+/**
+ * What a policy resolves to when a caller names no model.
+ *
+ * A discriminated union rather than two optional fields, so "which one did the
+ * customer configure" is never a question about which field is non-null.
+ */
+exports.routingTargetSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('model'),
+        modelReference: identifiers_1.modelReferenceSchema,
+    })
+        .strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('routing_profile'),
+        routingProfile: identifiers_1.routingProfileSlugSchema,
+    })
+        .strict(),
+]);
+/**
+ * Which account or application a policy governs.
+ *
+ * Application-scoped policies are the common case; an account-scoped policy is
+ * the floor its applications inherit, and inheritance is resolved by the control
+ * plane before a policy reaches the data plane.
+ */
+exports.routingPolicyScopeSchema = zod_1.z.discriminatedUnion('kind', [
+    zod_1.z.object({ kind: zod_1.z.literal('account'), accountId: identifiers_1.oxyAccountIdSchema }).strict(),
+    zod_1.z
+        .object({
+        kind: zod_1.z.literal('application'),
+        accountId: identifiers_1.oxyAccountIdSchema,
+        applicationId: identifiers_1.oxyApplicationIdSchema,
+    })
+        .strict(),
+]);
+/**
+ * The fallback controls, kept together so a reviewer sees all three at once.
+ *
+ * `authorizedCrossModel` is a list of model references the customer has
+ * explicitly permitted as substitutes — never a boolean, because "allow
+ * fallback" without naming the destination is exactly the silent substitution
+ * the invariant forbids.
+ */
+exports.routingFallbackPolicySchema = zod_1.z
+    .object({
+    disabled: zod_1.z.boolean(),
+    sameModelDeployment: zod_1.z.boolean(),
+    authorizedCrossModel: zod_1.z.array(identifiers_1.modelReferenceSchema).default([]),
+})
+    .strict();
+/**
+ * A versioned routing policy.
+ *
+ * `policyVersion` is the CUSTOMER's revision of their own configuration and is
+ * unrelated to `schemaVersion`, which is the version of this wire shape. They
+ * are two different clocks: a customer edits their policy without any contract
+ * change, and a contract change does not renumber anybody's policy.
+ */
+exports.routingPolicySchema = zod_1.z
+    .object({
+    /** See `version.ts`: exchanged with the data plane on its own. */
+    schemaVersion: zod_1.z.literal(1),
+    routingPolicyId: zod_1.z.string().min(1).max(128),
+    policyVersion: zod_1.z.number().int().positive().safe(),
+    scope: exports.routingPolicyScopeSchema,
+    /** Absent when every request must name its own model. */
+    defaultTarget: exports.routingTargetSchema.optional(),
+    /** Empty means "no allowlist" — every provider qualifies unless denied. */
+    providerAllowlist: zod_1.z.array(identifiers_1.inferenceProviderSlugSchema).default([]),
+    providerDenylist: zod_1.z.array(identifiers_1.inferenceProviderSlugSchema).default([]),
+    /** Empty means "no residency constraint". */
+    allowedRegions: zod_1.z.array(identifiers_1.inferenceRegionSchema).default([]),
+    deniedRegions: zod_1.z.array(identifiers_1.inferenceRegionSchema).default([]),
+    requireZeroDataRetention: zod_1.z.boolean(),
+    prohibitTrainingOnCustomerData: zod_1.z.boolean(),
+    /** Ceilings on what a route may cost the customer, quoted like catalogue prices. */
+    maxPricePerUnit: zod_1.z.array(money_1.unitPriceSchema).default([]),
+    maxPricePerRequest: zod_1.z
+        .object({ amount: money_1.exactDecimalSchema, currency: money_1.currencyCodeSchema })
+        .strict()
+        .optional(),
+    /** What to optimise for among the routes that qualify. */
+    optimiseFor: zod_1.z.enum(['price', 'latency', 'throughput', 'balanced']),
+    /** Serve only from Oxy's own hosting of open-weight models. */
+    oxyHostedOnly: zod_1.z.boolean(),
+    /** License / usage-right constraints. Empty license list means unconstrained. */
+    allowedLicenseIds: zod_1.z.array(zod_1.z.string().min(1).max(128)).default([]),
+    requireCommercialUseRights: zod_1.z.boolean(),
+    fallback: exports.routingFallbackPolicySchema,
+    /** Whether the customer's own provider credentials may or must be used. */
+    byokPreference: zod_1.z.enum(['disabled', 'prefer', 'require']),
+    /** Enterprise reserved capacity rather than shared endpoints. */
+    dedicatedCapacity: zod_1.z.enum(['disabled', 'prefer', 'require']),
+    updatedAt: identifiers_1.inferenceTimestampSchema,
+})
+    .superRefine((policy, ctx) => {
+    // "Requires a denied provider": the allowlist is the requirement, so a
+    // provider named in both lists is a policy that can never resolve. This is
+    // also the shape an Oxy-hosted-only policy takes when it pins a provider it
+    // has itself denied — whether a provider is Oxy-hosted is a property of the
+    // catalogue entry, not of its slug, so the data plane resolves it, not this
+    // schema.
+    const denied = new Set(policy.providerDenylist);
+    for (const [index, provider] of policy.providerAllowlist.entries()) {
+        if (denied.has(provider)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['providerAllowlist', index],
+                message: `provider ${provider} is both required by the allowlist and denied`,
+            });
+        }
+    }
+    const deniedRegions = new Set(policy.deniedRegions);
+    for (const [index, region] of policy.allowedRegions.entries()) {
+        if (deniedRegions.has(region)) {
+            ctx.addIssue({
+                code: zod_1.z.ZodIssueCode.custom,
+                path: ['allowedRegions', index],
+                message: `region ${region} is both allowed and denied`,
+            });
+        }
+    }
+    // Fallback disabled is an instruction to fail the request rather than serve
+    // it elsewhere. Combined with a fallback route it is not a strict policy but
+    // an ambiguous one, and the ambiguity resolves differently in each executor.
+    if (policy.fallback.disabled && policy.fallback.sameModelDeployment) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['fallback', 'sameModelDeployment'],
+            message: 'fallback is disabled, so same-model deployment failover cannot be enabled',
+        });
+    }
+    if (policy.fallback.disabled && policy.fallback.authorizedCrossModel.length > 0) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['fallback', 'authorizedCrossModel'],
+            message: 'fallback is disabled, so no cross-model fallback may be authorized',
+        });
+    }
+    // BYOK routes run on the customer's own upstream provider account, which is
+    // by definition not Oxy's hosting.
+    if (policy.oxyHostedOnly && policy.byokPreference === 'require') {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['byokPreference'],
+            message: 'an Oxy-hosted-only policy cannot also require a customer provider credential',
+        });
+    }
+    const ceilingUnits = policy.maxPricePerUnit.map((ceiling) => ceiling.unit);
+    if (new Set(ceilingUnits).size !== ceilingUnits.length) {
+        ctx.addIssue({
+            code: zod_1.z.ZodIssueCode.custom,
+            path: ['maxPricePerUnit'],
+            message: 'a unit may carry only one price ceiling',
+        });
+    }
+    if (policy.maxPricePerRequest !== undefined) {
+        for (const [index, ceiling] of policy.maxPricePerUnit.entries()) {
+            if (ceiling.currency !== policy.maxPricePerRequest.currency) {
+                ctx.addIssue({
+                    code: zod_1.z.ZodIssueCode.custom,
+                    path: ['maxPricePerUnit', index, 'currency'],
+                    message: 'every price ceiling in one policy must use the same currency',
+                });
+            }
+        }
+    }
+});
+/**
+ * The reference a request records: which policy, at which of the customer's own
+ * revisions. Embedded in the request envelope and in the settled receipt, so a
+ * charge can be explained against the exact configuration that produced it.
+ */
+exports.routingPolicyReferenceSchema = zod_1.z
+    .object({
+    routingPolicyId: zod_1.z.string().min(1).max(128),
+    policyVersion: zod_1.z.number().int().positive().safe(),
+})
+    .strict();