@game-infra/ai-schemas 0.3.0

package/dist/preset.js

@@ -0,0 +1,212 @@
+import { createSuccessResponseSchema } from "@game-infra/api-schemas-core";
+import { array, boolean, integer, maxLength, maxValue, minLength, minValue, number, object, optional, picklist, pipe, regex, string, } from "valibot";
+import { ProviderIdSchema, ProviderTierSchema } from "./provider.js";
+/**
+ * A preset is a stored answer to "which model, and if that one is not
+ * available, then what".
+ *
+ * Callers name a preset instead of a model, which is what lets a deployment
+ * change where its work runs without touching the caller. The preset holds two
+ * orderings and they answer different questions: the model list says which
+ * models are acceptable and in what order of preference, and the tier and
+ * provider preferences say how to reach whichever model is being tried. Keeping
+ * them apart is what makes "prefer the subscription, fall back to OpenRouter
+ * rather than to Cloudflare" expressible without writing out every combination.
+ */
+/** Lowercase, dash-separated key a request names a preset by. */
+export const PresetSlugSchema = pipe(string(), minLength(1), maxLength(64), regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "must be lowercase words separated by single dashes"));
+/**
+ * One model in a preset's order of preference.
+ *
+ * The entry's position in the list is its priority: the first entry whose model
+ * some enabled provider can serve wins. Everything else on the entry is a
+ * narrowing of how that model may be reached.
+ */
+export const PresetModelEntrySchema = object({
+    /** Canonical model id, matched against each provider's route table. */
+    model: pipe(string(), minLength(1), maxLength(160)),
+    /**
+     * Reach this model only through this provider. A pin turns off fallback for
+     * the entry: if the named provider is disabled, uncredentialed or does not
+     * serve the model, the entry contributes nothing and routing moves to the
+     * next model rather than quietly using a different provider. That is the
+     * point of pinning, so it is stated rather than treated as a hint.
+     */
+    provider: optional(ProviderIdSchema),
+    /** Tier order for this model only. Absent means the preset's own order. */
+    tierPreference: optional(array(ProviderTierSchema)),
+    /** Provider order for this model only. Absent means the preset's own order. */
+    providerPreference: optional(array(ProviderIdSchema)),
+    /** Sampling temperature for this model. Absent means the preset default. */
+    temperature: optional(pipe(number(), minValue(0), maxValue(2))),
+    /** Output-token cap for this model. Absent means the preset default. */
+    maxOutputTokens: optional(pipe(number(), integer(), minValue(1), maxValue(200_000))),
+});
+/**
+ * What a preset does when the only route left is a locked subscription.
+ *
+ * - `fall-back` — skip it and try the metered routes. The default, because a
+ *   caller that could not supply a password still wants an answer.
+ * - `require` — serve this preset from a subscription or not at all. Every
+ *   route that is not one is dropped from the plan with
+ *   `subscription_required`, so a request carrying no password is refused with
+ *   428 and one whose subscription is disabled, absent or failing is refused
+ *   rather than quietly billed. For work whose whole point is that it must not
+ *   be billed per token, where falling back is the failure rather than the
+ *   recovery.
+ */
+export const LOCKED_SUBSCRIPTION_POLICIES = ["fall-back", "require"];
+export const LockedSubscriptionPolicySchema = picklist(LOCKED_SUBSCRIPTION_POLICIES);
+/** A stored routing preset. */
+export const PresetSchema = object({
+    id: string(),
+    slug: PresetSlugSchema,
+    name: pipe(string(), minLength(1), maxLength(120)),
+    description: optional(pipe(string(), maxLength(600))),
+    /** Models in order of preference. A preset with none can route nothing. */
+    models: array(PresetModelEntrySchema),
+    /**
+     * Tier order. A preference REORDERS rather than filters: tiers left out are
+     * appended in the built-in order, so a preset written before a tier existed
+     * keeps working and gains the new tier as a last resort rather than being
+     * silently unable to reach it.
+     */
+    tierPreference: array(ProviderTierSchema),
+    /**
+     * Provider order inside a tier, which is where "OpenRouter before Cloudflare"
+     * is expressed. Providers not named come after the named ones, ordered by
+     * their own id so the result is stable rather than dependent on insertion
+     * order in the database.
+     */
+    providerPreference: array(ProviderIdSchema),
+    lockedSubscriptionPolicy: LockedSubscriptionPolicySchema,
+    /** Sampling temperature applied to any entry that does not set its own. */
+    temperature: optional(pipe(number(), minValue(0), maxValue(2))),
+    /** Output-token cap applied to any entry that does not set its own. */
+    maxOutputTokens: optional(pipe(number(), integer(), minValue(1), maxValue(200_000))),
+    /**
+     * How many routes a single request may try before giving up. Bounds the tail
+     * latency of a request whose preset lists many models across many gateways:
+     * without it, one request against a broadly-configured deployment can spend
+     * a minute failing through routes nobody is waiting for any more.
+     */
+    maxAttempts: pipe(number(), integer(), minValue(1), maxValue(10)),
+    /** Whether callers may name this preset. */
+    enabled: boolean(),
+    createdAt: string(),
+    updatedAt: string(),
+});
+/** Fields accepted when creating a preset. */
+export const CreatePresetRequestSchema = object({
+    slug: PresetSlugSchema,
+    name: pipe(string(), minLength(1), maxLength(120)),
+    description: optional(pipe(string(), maxLength(600))),
+    models: array(PresetModelEntrySchema),
+    tierPreference: optional(array(ProviderTierSchema)),
+    providerPreference: optional(array(ProviderIdSchema)),
+    lockedSubscriptionPolicy: optional(LockedSubscriptionPolicySchema),
+    temperature: optional(pipe(number(), minValue(0), maxValue(2))),
+    maxOutputTokens: optional(pipe(number(), integer(), minValue(1), maxValue(200_000))),
+    maxAttempts: optional(pipe(number(), integer(), minValue(1), maxValue(10))),
+    enabled: optional(boolean()),
+});
+/** Fields accepted when updating a preset. Absent means unchanged. */
+export const UpdatePresetRequestSchema = object({
+    name: optional(pipe(string(), minLength(1), maxLength(120))),
+    description: optional(pipe(string(), maxLength(600))),
+    models: optional(array(PresetModelEntrySchema)),
+    tierPreference: optional(array(ProviderTierSchema)),
+    providerPreference: optional(array(ProviderIdSchema)),
+    lockedSubscriptionPolicy: optional(LockedSubscriptionPolicySchema),
+    temperature: optional(pipe(number(), minValue(0), maxValue(2))),
+    maxOutputTokens: optional(pipe(number(), integer(), minValue(1), maxValue(200_000))),
+    maxAttempts: optional(pipe(number(), integer(), minValue(1), maxValue(10))),
+    enabled: optional(boolean()),
+});
+/**
+ * One route a request could take, as the planner ordered them.
+ *
+ * This is the same list the executor walks, exposed so a preset can be checked
+ * before anything is spent on it. A preset that reads correctly and routes to
+ * nothing is the failure mode worth catching here rather than in production,
+ * and it is invisible from the stored preset alone: it depends on which
+ * providers are enabled and what they were told they serve.
+ */
+export const RouteCandidateSchema = object({
+    /** Position in the plan, zero-based. */
+    order: pipe(number(), integer(), minValue(0)),
+    /** Canonical model this route serves. */
+    model: string(),
+    /** The id the provider serves it under. */
+    providerModelId: string(),
+    providerId: string(),
+    providerName: string(),
+    tier: ProviderTierSchema,
+    /**
+     * For a subscription route, whether the request as it stands could unlock it.
+     * A plan built without a password reports `false` here, which is what tells
+     * an operator that their subscription-first preset is quietly running on API
+     * keys.
+     */
+    unlockable: optional(boolean()),
+});
+/**
+ * Why a configured route was left out of the plan.
+ *
+ * A dry run that answered only with the routes it kept would be no help with
+ * the question people actually ask it, which is why the subscription they
+ * configured is not being used. Each reason names one fixable thing.
+ */
+export const ROUTE_EXCLUSION_REASONS = [
+    /** No enabled provider maps this canonical model at all. */
+    "model_not_served",
+    /** The provider exists but is switched off. */
+    "provider_disabled",
+    /** The provider needs a key and none is stored. */
+    "credential_missing",
+    /** A subscription route with no password on the request to open it. */
+    "subscription_locked",
+    /** A subscription owned by somebody other than the caller. */
+    "subscription_not_owned",
+    /**
+     * The route is not a subscription and the preset's `lockedSubscriptionPolicy`
+     * is `require`, so only subscription routes are eligible.
+     */
+    "subscription_required",
+    /** The entry pins a provider that does not exist or does not serve the model. */
+    "pinned_provider_unavailable",
+    /** The request carries images and this route is declared text-only. */
+    "model_no_image_input",
+    /** The request carries images and nobody has declared whether this route reads them. */
+    "unknown_model_image_input",
+    /** `/generate/object` against a route declared to have no structured-output path. */
+    "structured_output_unsupported",
+    /** The route was valid but fell outside the preset's attempt budget. */
+    "attempt_budget_exhausted",
+];
+export const RouteExclusionReasonSchema = picklist(ROUTE_EXCLUSION_REASONS);
+/** A route that was considered and dropped, with the reason it was dropped. */
+export const RouteExclusionSchema = object({
+    model: string(),
+    providerId: optional(string()),
+    tier: optional(ProviderTierSchema),
+    reason: RouteExclusionReasonSchema,
+    /** Operator-facing wording for {@link reason}, naming this specific route. */
+    detail: string(),
+});
+/** The plan a preset produces against the current configuration. */
+export const RoutePlanResponseSchema = createSuccessResponseSchema({
+    preset: optional(string()),
+    candidates: optional(array(RouteCandidateSchema)),
+    /** Routes considered and dropped. Empty is a real answer, not a missing one. */
+    excluded: optional(array(RouteExclusionSchema)),
+});
+/** One preset. */
+export const PresetResponseSchema = createSuccessResponseSchema({
+    preset: optional(PresetSchema),
+});
+/** Every stored preset. */
+export const PresetListResponseSchema = createSuccessResponseSchema({
+    presets: optional(array(PresetSchema)),
+});
+//# sourceMappingURL=preset.js.map

package/dist/preset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preset.js","sourceRoot":"","sources":["../src/preset.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAC3E,OAAO,EAEL,KAAK,EACL,OAAO,EACP,OAAO,EACP,SAAS,EACT,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,MAAM,EACN,MAAM,EACN,QAAQ,EACR,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,MAAM,GACP,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAErE;;;;;;;;;;;GAWG;AAEH,iEAAiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAClC,MAAM,EAAE,EACR,SAAS,CAAC,CAAC,CAAC,EACZ,SAAS,CAAC,EAAE,CAAC,EACb,KAAK,CAAC,4BAA4B,EAAE,oDAAoD,CAAC,CAC1F,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;IAC3C,uEAAuE;IACvE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IACnD;;;;;;OAMG;IACH,QAAQ,EAAE,QAAQ,CAAC,gBAAgB,CAAC;IACpC,2EAA2E;IAC3E,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACnD,+EAA+E;IAC/E,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrD,4EAA4E;IAC5E,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,wEAAwE;IACxE,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;CACrF,CAAC,CAAC;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,WAAW,EAAE,SAAS,CAAU,CAAC;AAC9E,MAAM,CAAC,MAAM,8BAA8B,GAAG,QAAQ,CAAC,4BAA4B,CAAC,CAAC;AAGrF,+BAA+B;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC;IACjC,EAAE,EAAE,MAAM,EAAE;IACZ,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IAClD,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,2EAA2E;IAC3E,MAAM,EAAE,KAAK,CAAC,sBAAsB,CAAC;IACrC;;;;;OAKG;IACH,cAAc,EAAE,KAAK,CAAC,kBAAkB,CAAC;IACzC;;;;;OAKG;IACH,kBAAkB,EAAE,KAAK,CAAC,gBAAgB,CAAC;IAC3C,wBAAwB,EAAE,8BAA8B;IACxD,2EAA2E;IAC3E,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,uEAAuE;IACvE,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACpF;;;;;OAKG;IACH,WAAW,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;IACjE,4CAA4C;IAC5C,OAAO,EAAE,OAAO,EAAE;IAClB,SAAS,EAAE,MAAM,EAAE;IACnB,SAAS,EAAE,MAAM,EAAE;CACpB,CAAC,CAAC;AAIH,8CAA8C;AAC9C,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;IAC9C,IAAI,EAAE,gBAAgB;IACtB,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC;IAClD,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,EAAE,KAAK,CAAC,sBAAsB,CAAC;IACrC,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACnD,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrD,wBAAwB,EAAE,QAAQ,CAAC,8BAA8B,CAAC;IAClE,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACpF,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;CAC7B,CAAC,CAAC;AAIH,sEAAsE;AACtE,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC;IAC9C,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5D,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC;IAC/C,cAAc,EAAE,QAAQ,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACnD,kBAAkB,EAAE,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;IACrD,wBAAwB,EAAE,QAAQ,CAAC,8BAA8B,CAAC;IAClE,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,eAAe,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;IACpF,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;CAC7B,CAAC,CAAC;AAIH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;IACzC,wCAAwC;IACxC,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IAC7C,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE;IACf,2CAA2C;IAC3C,eAAe,EAAE,MAAM,EAAE;IACzB,UAAU,EAAE,MAAM,EAAE;IACpB,YAAY,EAAE,MAAM,EAAE;IACtB,IAAI,EAAE,kBAAkB;IACxB;;;;;OAKG;IACH,UAAU,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;CAChC,CAAC,CAAC;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,4DAA4D;IAC5D,kBAAkB;IAClB,+CAA+C;IAC/C,mBAAmB;IACnB,mDAAmD;IACnD,oBAAoB;IACpB,uEAAuE;IACvE,qBAAqB;IACrB,8DAA8D;IAC9D,wBAAwB;IACxB;;;OAGG;IACH,uBAAuB;IACvB,iFAAiF;IACjF,6BAA6B;IAC7B,uEAAuE;IACvE,sBAAsB;IACtB,wFAAwF;IACxF,2BAA2B;IAC3B,qFAAqF;IACrF,+BAA+B;IAC/B,wEAAwE;IACxE,0BAA0B;CAClB,CAAC;AACX,MAAM,CAAC,MAAM,0BAA0B,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAG5E,+EAA+E;AAC/E,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC;IACzC,KAAK,EAAE,MAAM,EAAE;IACf,UAAU,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC9B,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC;IAClC,MAAM,EAAE,0BAA0B;IAClC,8EAA8E;IAC9E,MAAM,EAAE,MAAM,EAAE;CACjB,CAAC,CAAC;AAIH,oEAAoE;AACpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,2BAA2B,CAAC;IACjE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IAC1B,UAAU,EAAE,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;IACjD,gFAAgF;IAChF,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,oBAAoB,CAAC,CAAC;CAChD,CAAC,CAAC;AAIH,kBAAkB;AAClB,MAAM,CAAC,MAAM,oBAAoB,GAAG,2BAA2B,CAAC;IAC9D,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC;CAC/B,CAAC,CAAC;AAGH,2BAA2B;AAC3B,MAAM,CAAC,MAAM,wBAAwB,GAAG,2BAA2B,CAAC;IAClE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;CACvC,CAAC,CAAC"}