@zuplo/runtime 7.4.7 → 7.5.1

package/out/types/index.d.ts

@@ -1065,6 +1065,154 @@ export declare interface AIGatewaySemanticCacheV2InboundPolicyOptions {
   onUnknownShape?: OnUnknownShape_2;
 }
 
+/**
+ * Reads and writes the Smart Router result for an AI Gateway request.
+ *
+ * The built-in Smart Router policy `set()`s this after a successful
+ * classification. Custom policies can `get()` it later in the same request,
+ * or `set()` a compatible result of their own.
+ *
+ * @public
+ * @example
+ * ```typescript
+ * import { AIGatewaySmartRouter } from "@zuplo/runtime";
+ *
+ * const result = AIGatewaySmartRouter.get(context);
+ * if (result?.profile.intent === "code") {
+ *   // ...
+ * }
+ * ```
+ */
+export declare const AIGatewaySmartRouter: {
+  set(context: ZuploContext, result: AIGatewaySmartRouterResult): void;
+  get(context: ZuploContext): AIGatewaySmartRouterResult | undefined;
+};
+
+/**
+ * Prompt-complexity label produced by Smart Router.
+ *
+ * @public
+ */
+export declare type AIGatewaySmartRouterComplexity = "low" | "medium" | "high";
+
+/**
+ * Smart Router Inbound Policy for the AI Gateway
+ * @title Smart Router
+ * @product ai-gateway
+ * @requiresAI
+ *
+ * Classifies the last user prompt by calling a dedicated classifier AI
+ * Gateway app, stores the result on `AIGatewaySmartRouter`, and
+ * optionally overwrites completions routing from `modelsByComplexity`.
+ * Classification failures, timeouts, and invalid options fail open: the
+ * original request is forwarded.
+ *
+ * @param request - The ZuploRequest
+ * @param context - The ZuploContext
+ * @param options - The policy options set in policies.json
+ * @param policyName - The name of the policy as set in policies.json
+ * @returns A Request or a Response
+ */
+export declare function AIGatewaySmartRouterInboundPolicy(
+  request: ZuploRequest,
+  context: ZuploContext,
+  unparsedOptions: unknown,
+  policyName: string
+): Promise<ZuploRequest | Response>;
+
+/**
+ * Options for the Smart Router policy: classify the last user prompt with a dedicated classifier AI Gateway app, then optionally route by complexity.
+ * @public
+ */
+export declare interface AIGatewaySmartRouterInboundPolicyOptions {
+  classifierAppID: ClassifierAppID;
+  classifierAppApiKey: ClassifierAppAPIKey;
+  classifierModel: ClassifierModel;
+  smartRoutingEnabled?: SmartRoutingEnabled;
+  modelsByComplexity?: ModelsByComplexity;
+  intents?: Intents;
+  classifierPrompt?: ClassifierPrompt;
+  minConfidenceForRouting?: MinimumConfidenceForRouting;
+  classifierTimeoutMs?: ClassifierTimeoutMs;
+  maxPromptChars?: MaxPromptCharacters;
+}
+
+/**
+ * Structured classification of the last user prompt.
+ *
+ * @public
+ */
+export declare interface AIGatewaySmartRouterProfile {
+  intent: string;
+  complexity: AIGatewaySmartRouterComplexity;
+  confidence: number;
+  reasons: string[];
+}
+
+/**
+ * Where the classified text was taken from on the request.
+ *
+ * @public
+ */
+export declare type AIGatewaySmartRouterPromptSource = "user" | "prior-user";
+
+/**
+ * Why Smart Router did or did not change the request's model.
+ *
+ * @public
+ */
+export declare type AIGatewaySmartRouterReason =
+  | "applied"
+  | "disabled"
+  | "low-confidence"
+  | "no-model"
+  | "internal-error"
+  | "unknown-intent";
+
+/**
+ * Result produced by the Smart Router policy for the current request.
+ * Custom inbound policies can read this after Smart Router runs.
+ *
+ * @public
+ */
+export declare interface AIGatewaySmartRouterResult {
+  profile: AIGatewaySmartRouterProfile;
+  usage: AIGatewaySmartRouterTokenUsage;
+  classifierModel: string;
+  routing: AIGatewaySmartRouterRoutingDecision;
+  durationMs: number;
+  promptSource: AIGatewaySmartRouterPromptSource;
+  promptLength: number;
+  promptTruncated: boolean;
+  unknownIntent: boolean;
+  smartRouting: {
+    enabled: boolean;
+    applied: boolean;
+    reason: AIGatewaySmartRouterReason;
+    minConfidence: number;
+  };
+}
+
+/**
+ * Model chosen from `modelsByComplexity` for the classified complexity, if any.
+ *
+ * @public
+ */
+export declare interface AIGatewaySmartRouterRoutingDecision {
+  model?: string;
+}
+
+/**
+ * Classifier token usage reported by the classifier chat/completions call.
+ *
+ * @public
+ */
+export declare interface AIGatewaySmartRouterTokenUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+}
+
 /**
  * The options for this policy.
  * @public
@@ -3589,6 +3737,36 @@ declare type Claim = string;
  */
 declare type ClaimCheck = EqualsRule | InRule | StartsWithRule;
 
+/**
+ * API key sent as `Authorization: Bearer` when invoking the classifier app.
+ * @public
+ */
+declare type ClassifierAppAPIKey = string;
+
+/**
+ * The AI Gateway application id whose `/v1/chat/completions` route runs the classifier. The policy calls `/{classifierAppID}/v1/chat/completions` via `context.invokeRoute`.
+ * @public
+ */
+declare type ClassifierAppID = string;
+
+/**
+ * The `providerName/model` reference the classifier chat/completions request should use.
+ * @public
+ */
+declare type ClassifierModel = string;
+
+/**
+ * System prompt for the classifier. If it includes `{{intents}}`, that placeholder is replaced with the configured intent id/description list. A string or an array of lines (joined with newlines). Omit to use the built-in classifier prompt.
+ * @public
+ */
+declare type ClassifierPrompt = string | [string, ...string[]];
+
+/**
+ * How long to wait for the classifier `invokeRoute` call before skipping classification and forwarding the original request.
+ * @public
+ */
+declare type ClassifierTimeoutMs = number;
+
 /**
  * Removes all headers from the incoming request except for those in the exclude list.
  *
@@ -5778,6 +5956,12 @@ declare interface HeaderCredentialsConfig {
   headerName: string;
 }
 
+/**
+ * Model used for prompts classified as high complexity.
+ * @public
+ */
+declare type HighComplexityModel = string;
+
 /**
  * Sets HTTP deprecation headers on the outgoing response following the IETF
  * HTTP Deprecation Header standard. Supports the Deprecation, Sunset, and Link
@@ -7654,6 +7838,35 @@ declare interface InRule {
   in: [string | number | boolean, ...(string | number | boolean)[]];
 }
 
+/**
+ * Short description shown to the classifier for this intent.
+ * @public
+ */
+declare type IntentDescription = string;
+
+/**
+ * Stable intent identifier written into the classifier JSON schema enum.
+ * @public
+ */
+declare type IntentID = string;
+
+/**
+ * Labels the classifier may assign. Used to build the JSON schema enum and injected into `classifierPrompt` at `{{intents}}`. Omit to use the built-in taxonomy (code, summarization, translation, qa, conversation, classification, creative_writing, agentic, document_qa, other).
+ *
+ * @minItems 1
+ * @public
+ */
+declare type Intents = [
+  {
+    id: IntentID;
+    description: IntentDescription;
+  },
+  ...{
+    id: IntentID;
+    description: IntentDescription;
+  }[],
+];
+
 /**
  * Restricts which client IP addresses can call a route using an allow list, a
  * deny list, or both. Entries are individual IP addresses or CIDR ranges, in
@@ -8298,12 +8511,24 @@ declare type LokiTransportVersion = 1 | 2;
 
 /* Excluded from this release type: LookupResult */
 
+/**
+ * Model used for prompts classified as low complexity.
+ * @public
+ */
+declare type LowComplexityModel = string;
+
 /**
  * Skip caching entirely when the conversation has more than this many messages. Unset by default (no limit). Set a bound to guard against topic drift: the cache key covers only the last recentMessageCount messages, so the deeper a conversation goes, the more likely a match on recent messages alone ignores earlier context that should change the answer.
  * @public
  */
 declare type MaxConversationLength = number;
 
+/**
+ * Maximum characters of user prompt sent to the classifier. Longer prompts are truncated.
+ * @public
+ */
+declare type MaxPromptCharacters = number;
+
 /**
  * Authenticate MCP gateway requests using a gateway-issued OAuth access token,
  * with browser login delegated to Auth0.
@@ -10087,6 +10312,12 @@ export declare interface McpWorkosOAuthInboundPolicyOptions {
   };
 }
 
+/**
+ * Model used for prompts classified as medium complexity.
+ * @public
+ */
+declare type MediumComplexityModel = string;
+
 declare interface MemoryCacheOptions {
   maxSize: number;
 }
@@ -10270,6 +10501,12 @@ declare interface MetricsType {
   responseContentLength?: boolean;
 }
 
+/**
+ * Minimum confidence (0–1) required before applying model routing. Unknown intents are capped strictly below this threshold.
+ * @public
+ */
+declare type MinimumConfidenceForRouting = number;
+
 /**
  * The options for this policy.
  * @public
@@ -10322,6 +10559,16 @@ declare interface Models {
   embeddings?: EmbeddingsModels;
 }
 
+/**
+ * Optional `providerName/model` routing by classified complexity. Used only when `smartRoutingEnabled` is true.
+ * @public
+ */
+declare interface ModelsByComplexity {
+  low?: LowComplexityModel;
+  medium?: MediumComplexityModel;
+  high?: HighComplexityModel;
+}
+
 declare type Modify<T, R> = Omit<T, keyof R> & R;
 
 declare interface MoesifContext {
@@ -13907,6 +14154,12 @@ export declare interface SleepInboundPolicyOptions {
   sleepInMs: number;
 }
 
+/**
+ * When true, apply model routing from `modelsByComplexity` when confidence is high enough and the intent is known. Classification still runs when false.
+ * @public
+ */
+declare type SmartRoutingEnabled = boolean;
+
 declare interface SplunkLoggingOptions {
   /**
    * The URL for the Splunk HTTP Event Collector (HEC) endpoint.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "7.4.7",
+  "version": "7.5.1",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {