@adaptic/utils 0.0.1038 → 0.0.1040

package/dist/types/llm/fallback-chain.d.ts

@@ -10,24 +10,31 @@
  * why the budget is enforced here — at the only place that knows both the
  * caller's deadline and how many legs are left to spend it on.
  *
+ * Each leg is first run as a group of SAME-MODEL attempts (see `hedge.ts`):
+ * hedged at the model's healthy p90, replaced after a measured timeout, and
+ * reaching the same model at another provider before the leg is given up.
+ * Only then does the walk move to the next leg — and a leg that serves a
+ * different model than the configured one runs only when the caller's
+ * cross-model policy allows it. With no latency evidence and no equivalent
+ * configured, each group is a single attempt with the leg's budget, which is
+ * the serial walk exactly.
+ *
  * Nothing here ever substitutes a value for an outcome. When every leg is
- * exhausted the caller gets a typed error naming each leg and why it failed,
- * because a default returned in place of an answer is a wrong answer that
- * nobody is told about.
+ * exhausted the caller gets a typed error naming each leg and why it failed —
+ * `LlmDeadlineExceededError` when the caller's deadline is what ran out,
+ * `ChainExhaustedError` with reason `cross_model_denied` when policy stopped
+ * the walk — because a default returned in place of an answer is a wrong
+ * answer that nobody is told about.
  *
  * @module llm/fallback-chain
  */
 import type { CircuitBreakerRegistry } from "./circuit-breaker";
-import { UnsupportedCapabilityError } from "./param-matrix";
-import type { AliasAttemptRecord, LlmTransport, LlmTransportRequest, LlmTransportResponse, LlmUsageRecord, ResolvedRoute } from "./types";
-/** What one leg of the chain needs in order to run. */
-export interface ChainLeg {
-    readonly route: ResolvedRoute;
-    /** The transport that will carry this leg. */
-    readonly transport: LlmTransport;
-    /** Provider-normalised parameters, or the error that made this leg unusable. */
-    readonly params: Record<string, unknown> | UnsupportedCapabilityError;
-}
+import type { AttemptFields, SameModelPolicy } from "./hedge";
+import type { ChainLeg } from "./leg-attempt";
+import type { LegLatencyTracker } from "./leg-latency-tracker";
+import type { AliasAttemptRecord, LlmCrossModelPolicy, LlmModelClassRelation, LlmTransportRequest, LlmTransportResponse, LlmUsageRecord, ResolvedRoute } from "./types";
+export { isCapacitySignal } from "./leg-attempt";
+export type { ChainLeg } from "./leg-attempt";
 /** Everything the executor needs for one call. */
 export interface ChainExecution {
     readonly legs: readonly ChainLeg[];
@@ -53,8 +60,25 @@ export interface ChainExecution {
     readonly deadlineAtMs?: number;
     /** Clock, injected so elapsed time is observable in tests without waiting. */
     readonly now?: () => number;
-    /** Invoked once per leg after it settles, for metrics and shadow comparison. */
+    /** Invoked once per attempt after it settles, for metrics and shadow comparison. */
     readonly onAttempt?: (record: AliasAttemptRecord) => void;
+    /**
+     * Same-model controls. Absent: every leg is one attempt with its full
+     * budget, as in the serial chain.
+     */
+    readonly hedging?: SameModelPolicy;
+    /** Healthy-latency evidence the hedging controls read, and the chain feeds. */
+    readonly latency?: LegLatencyTracker;
+    /** Whether a duplicate same-provider attempt may start; absent means never. */
+    readonly admitDuplicate?: (route: ResolvedRoute, reserveFraction: number) => boolean;
+    /** Whether a different-model leg may run. Absent means `allow_record`. */
+    readonly crossModelPolicy?: LlmCrossModelPolicy;
+    /**
+     * The configured model's class. Absent means the first leg's; supplied when
+     * the legs are a subset of the chain (the degraded direct path), whose first
+     * leg is not the configured model.
+     */
+    readonly configuredModelClass?: string;
 }
 /** Result of walking a chain to a successful leg. */
 export interface ChainOutcome<T> {
@@ -62,7 +86,13 @@ export interface ChainOutcome<T> {
     readonly servedBy: ResolvedRoute;
     readonly attempts: readonly AliasAttemptRecord[];
     readonly totalUsage: LlmUsageRecord;
+    /** Whether the answer came from the configured model. */
+    readonly modelClassRelation: LlmModelClassRelation;
+    /** Whether the answering attempt was a same-model hedge. */
+    readonly hedged: boolean;
 }
+/** Why a chain ended without an answer. */
+export type ChainExhaustionReason = "exhausted" | "cross_model_denied" | "deadline_exceeded";
 /**
  * Thrown when every leg of a chain has been tried and none produced an answer.
  *
@@ -78,12 +108,44 @@ export declare class ChainExhaustedError extends Error {
     readonly attempts: readonly AliasAttemptRecord[];
     /** Usage spent across the failed attempts, so the spend is still accounted for. */
     readonly totalUsage: LlmUsageRecord;
+    /**
+     * Why the chain ended. `cross_model_denied`: the configured model's attempts
+     * were spent and policy forbade a different model. Callers map every reason
+     * to no decision; the reason says which remedy applies.
+     */
+    readonly reason: ChainExhaustionReason;
+    /**
+     * @param alias The alias.
+     * @param attempts The attempt record.
+     * @param totalUsage Usage spent across all attempts.
+     * @param reason Why the chain ended; defaults to plain exhaustion.
+     */
+    constructor(alias: string, attempts: readonly AliasAttemptRecord[], totalUsage: LlmUsageRecord, reason?: ChainExhaustionReason);
+}
+/**
+ * Thrown when the caller's deadline ran out before any leg answered.
+ *
+ * A subclass of {@link ChainExhaustedError}, so a consumer that already treats
+ * exhaustion as "no answer" keeps doing so, while one that needs to tell "the
+ * models failed" from "we ran out of time" can match this class — the two call
+ * for different remedies (a provider problem versus a budget problem), and
+ * both map to no decision, never to a default.
+ */
+export declare class LlmDeadlineExceededError extends ChainExhaustedError {
+    /** Discriminant for consumers that switch on shape rather than class. */
+    readonly kind: "deadline_exceeded";
+    /** The whole-call budget the chain started with, in milliseconds. */
+    readonly deadlineMs: number;
+    /** The model class of the last attempt dispatched, or null when none was. */
+    readonly lastModelClass: string | null;
     /**
      * @param alias The alias.
      * @param attempts The attempt record.
      * @param totalUsage Usage spent across all attempts.
+     * @param deadlineMs The budget the chain started with.
+     * @param lastModelClass The last dispatched attempt's model class.
      */
-    constructor(alias: string, attempts: readonly AliasAttemptRecord[], totalUsage: LlmUsageRecord);
+    constructor(alias: string, attempts: readonly AliasAttemptRecord[], totalUsage: LlmUsageRecord, deadlineMs: number, lastModelClass: string | null);
 }
 /**
  * Add two usage records.
@@ -117,23 +179,47 @@ export declare function sumUsage(a: LlmUsageRecord, b: LlmUsageRecord | undefine
  */
 export declare function legBudgetMs(routeBudgetMs: number, deadlineAtMs: number | undefined, nowMs: number): number;
 /**
- * Whether a failure is the provider saying it is full rather than broken.
+ * The model a leg serves, independent of which provider hosts it.
+ *
+ * @param route The leg's route.
+ * @returns Its model class.
+ */
+export declare function modelClassOf(route: ResolvedRoute): string;
+/**
+ * Whether a provider-reported model names the model a route addressed.
+ *
+ * Providers report with or without an organisation prefix and in their own
+ * case, so the comparison is case-insensitive and accepts one side being a
+ * `/`-suffix of the other.
+ *
+ * @param reported The provider's report.
+ * @param expected The route's model id.
+ * @returns Whether they name the same model.
+ */
+export declare function isSameReportedModel(reported: string, expected: string): boolean;
+/**
+ * How an attempt's model relates to the configured one.
  *
- * Read by shape rather than by class, because the same signal reaches the
- * chain from more than one transport and not every transport's error class is
- * importable here.
+ * A leg addressed to a different model class is `different` whatever it
+ * reported. A leg addressed to the configured class is `same` only when it
+ * answered and the provider named the expected model; `different` when the
+ * provider named another; `unknown` when it answered without saying. An
+ * attempt that never answered carries the relation of the model it was
+ * addressed to.
  *
- * @param error The thrown value.
- * @param reason Its message.
- * @returns Whether it is a capacity signal.
+ * @param route The attempt's route.
+ * @param configuredClass The configured model class.
+ * @param fields What the attempt recorded.
+ * @returns The relation.
  */
-export declare function isCapacitySignal(error: unknown, reason: string): boolean;
+export declare function modelClassRelationOf(route: ResolvedRoute, configuredClass: string, fields: Pick<AttemptFields, "outcome" | "servedModel">): LlmModelClassRelation;
 /**
  * Walk a chain until a leg answers.
  *
  * @param alias The alias being served, for error attribution.
  * @param execution The call context.
  * @returns The first successful leg's answer, with the full attempt record.
+ * @throws {LlmDeadlineExceededError} When the caller's deadline ran out first.
  * @throws {ChainExhaustedError} When no leg produced an answer.
  */
 export declare function executeChain<T>(alias: string, execution: ChainExecution): Promise<ChainOutcome<T>>;

package/dist/types/llm/fallback-chain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fallback-chain.d.ts","sourceRoot":"","sources":["../../../src/llm/fallback-chain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fallback-chain.d.ts","sourceRoot":"","sources":["../../../src/llm/fallback-chain.ts"],"names":[],"mappings":"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"}

package/dist/types/llm/hedge.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Same-model attempts for one leg: hedging, measured attempt timeouts, and
+ * reserving deadline for a same-model alternative.
+ *
+ * A leg is a model. Before the chain gives up on it and reaches a DIFFERENT
+ * model — which changes the answer's quality, not just its latency — it is
+ * worth spending the leg's budget on every way of getting that same model to
+ * answer: the same model at another provider (an "equivalent"), or a second
+ * request to the same provider when that provider has capacity to spare (a
+ * "duplicate"). This module runs those attempts as one group.
+ *
+ * Three mechanics, all bounded by the leg's budget and none of them selecting
+ * a different model:
+ *
+ * - **Hedging.** Once an attempt has run past the model's healthy p90 (from
+ *   the latency tracker), the next same-model attempt starts beside it. The
+ *   first answer wins and every other attempt is cancelled through its own
+ *   abort signal. A hedge that loses, or an attempt cancelled because another
+ *   won, says nothing about the provider and never touches its breaker.
+ *
+ * - **Measured attempt timeout.** With latency evidence, an attempt that has
+ *   run past `k × p99` of healthy latency is replaced by a same-model
+ *   alternative instead of holding the budget to its end. It is replaced only
+ *   when an alternative exists: with none, cutting it short would only move
+ *   the call to a different model sooner, and it runs to the leg budget as
+ *   before.
+ *
+ * - **Deadline reservation.** When a same-model equivalent exists, no single
+ *   attempt holds more than `max_attempt_share` of the remaining budget before
+ *   the equivalent starts beside it, so a slow first attempt cannot consume the
+ *   whole deadline while the equivalent that could have answered never runs.
+ *
+ * With no latency evidence and no equivalent, none of the three can act and
+ * the group is exactly one attempt with the leg's full budget: the serial
+ * chain's behaviour, which a fresh process therefore starts from.
+ *
+ * @module llm/hedge
+ */
+import type { CircuitBreakerRegistry } from "./circuit-breaker";
+import type { AttemptRequest, ChainLeg } from "./leg-attempt";
+import type { LegLatencyTracker } from "./leg-latency-tracker";
+import type { AliasAttemptRecord, LlmHedgingDefaults, LlmTransportResponse, LlmUsageRecord, ResolvedRoute } from "./types";
+/** Same-model controls, read from the route table's `hedging` defaults. */
+export interface SameModelPolicy {
+    readonly maxExtraAttempts: number;
+    readonly hedgeQuantile: number;
+    readonly timeoutQuantile: number;
+    readonly kTimeout: number;
+    readonly attemptTimeoutFloorMs: number;
+    readonly maxAttemptShare: number;
+    readonly duplicateReserve: number;
+}
+/**
+ * Read the policy from the table's defaults.
+ *
+ * @param defaults The `hedging` defaults.
+ * @returns The policy.
+ */
+export declare function sameModelPolicyFrom(defaults: LlmHedgingDefaults): SameModelPolicy;
+/** The legacy fields of one attempt record; the chain adds provenance. */
+export type AttemptFields = Omit<AliasAttemptRecord, "servedProvider" | "modelClass" | "modelClassRelation" | "hedged" | "attemptIndex">;
+/** What the group needs from the chain around it. */
+export interface SameModelGroupContext {
+    readonly request: AttemptRequest;
+    readonly breakers: CircuitBreakerRegistry;
+    readonly now: () => number;
+    /** Absent: no hedging, no measured timeouts — one attempt with the full budget. */
+    readonly policy?: SameModelPolicy;
+    readonly tracker?: LegLatencyTracker;
+    readonly promptTokens: number | null;
+    readonly admitDuplicate: (route: ResolvedRoute, reserveFraction: number) => boolean;
+    /** Record one settled attempt. `servedProvider` is the provider's own report, if any. */
+    readonly record: (route: ResolvedRoute, fields: AttemptFields, dispatch: {
+        readonly hedged: boolean;
+        readonly attemptIndex: number;
+    }, servedProvider: string | null | undefined) => void;
+    /** The next zero-based dispatch index across the whole call. */
+    readonly nextAttemptIndex: () => number;
+}
+/** How a group ended. */
+export interface SameModelGroupResult<T> {
+    readonly answer?: {
+        readonly response: LlmTransportResponse<T>;
+        readonly route: ResolvedRoute;
+        readonly hedged: boolean;
+    };
+    /** Usage billed by every attempt in the group, answered or not. */
+    readonly billed: readonly LlmUsageRecord[];
+    /** Whether the group ended because the caller's deadline ran out. */
+    readonly deadlineBound: boolean;
+}
+/**
+ * Run every same-model attempt for one leg until one answers or the budget,
+ * the alternatives, or the caller run out.
+ *
+ * The caller has already found the leg servable (breaker allows it, budget
+ * positive). The returned promise settles only once every attempt it started
+ * has been recorded, so the call's attempt record is complete when it returns.
+ *
+ * @param leg The leg, with its equivalents.
+ * @param groupBudgetMs The leg's budget: its route budget cut to the deadline.
+ * @param budgetIsDeadline Whether that budget was cut by the caller's deadline.
+ * @param ctx The chain around the group.
+ * @returns How the group ended.
+ */
+export declare function runSameModelGroup<T>(leg: ChainLeg, groupBudgetMs: number, budgetIsDeadline: boolean, ctx: SameModelGroupContext): Promise<SameModelGroupResult<T>>;
+//# sourceMappingURL=hedge.d.ts.map

package/dist/types/llm/hedge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hedge.d.ts","sourceRoot":"","sources":["../../../src/llm/hedge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAShE,OAAO,KAAK,EAAiB,cAAc,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC7E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,KAAK,EACV,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,EACpB,cAAc,EACd,aAAa,EACd,MAAM,SAAS,CAAC;AAEjB,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,kBAAkB,GAAG,eAAe,CAUjF;AAED,0EAA0E;AAC1E,MAAM,MAAM,aAAa,GAAG,IAAI,CAC9B,kBAAkB,EAClB,gBAAgB,GAAG,YAAY,GAAG,oBAAoB,GAAG,QAAQ,GAAG,cAAc,CACnF,CAAC;AAEF,qDAAqD;AACrD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAC3B,mFAAmF;IACnF,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC;IACrC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,cAAc,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,KAAK,OAAO,CAAC;IACpF,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,CACf,KAAK,EAAE,aAAa,EACpB,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE,EACrE,cAAc,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,KACtC,IAAI,CAAC;IACV,gEAAgE;IAChE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,MAAM,CAAC;CACzC;AAED,yBAAyB;AACzB,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC,CAAC,CAAC;QAC3C,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;IACF,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAC;IAC3C,qEAAqE;IACrE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;CACjC;AAkCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,QAAQ,EACb,aAAa,EAAE,MAAM,EACrB,gBAAgB,EAAE,OAAO,EACzB,GAAG,EAAE,qBAAqB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,CA6WlC"}

package/dist/types/llm/index.d.ts

@@ -8,13 +8,16 @@
  *
  * @module llm
  */
-export { callLLMByAlias, configureLlmClient, llmAliases, llmBreakers } from "./alias-client";
-export { ChainExhaustedError, legBudgetMs, sumUsage, } from "./fallback-chain";
+export { callLLMByAlias, configureLlmClient, llmAliases, llmBreakers, llmLatencyTracker, } from "./alias-client";
+export { ChainExhaustedError, LlmDeadlineExceededError, isSameReportedModel, legBudgetMs, modelClassOf, modelClassRelationOf, sumUsage, } from "./fallback-chain";
+export type { ChainExhaustionReason } from "./fallback-chain";
+export { LegLatencyTracker, estimatePromptTokens } from "./leg-latency-tracker";
+export type { LatencyTrackerConfig } from "./leg-latency-tracker";
 export type { AliasAttemptRecord } from "./types";
-export { NoServableRouteError, UnknownAliasError, closedIncumbentLeg, gatewayModelNameFor, listAliases, orderedRoutes, resolveChain, routeKeyFor, routeTable, } from "./route-table";
+export { EQUIVALENT_SEPARATOR, NoServableRouteError, UnknownAliasError, closedIncumbentLeg, gatewayModelNameFor, listAliases, orderedRoutes, resolveChain, routeKeyFor, routeTable, tailLatencyViolations, } from "./route-table";
 export type { ResolvedChain, RouteExclusion } from "./route-table";
 export { ToolChoiceIgnoredError, UnsupportedCapabilityError, assertToolChoiceHonoured, normaliseParams, routeSupports, } from "./param-matrix";
-export { RateGuardTimeoutError, guardSnapshots, limitsFor, limitsInventory, resetProviderGuards, withProviderGuards, } from "./rate-guard";
+export { RateGuardTimeoutError, guardSnapshots, hasDuplicateHeadroom, limitsFor, limitsInventory, resetProviderGuards, withProviderGuards, } from "./rate-guard";
 export type { GuardCallScope, GuardSnapshot, ModelLimitOverride, ProviderLimitBasis, ProviderLimitScope, ProviderLimits, } from "./rate-guard";
 export { LlmResponseFormatError } from "./structured-content";
 export type { StructuredResponseFormat } from "./structured-content";
@@ -24,9 +27,9 @@ export { SchemaRetryExhaustedError, buildRetryPrompt, callWithValidation } from
 export type { ValidatedOutcome } from "./schema-retry";
 export { StreamProviderError, StreamTruncatedError, collectStream, normaliseAnthropicStream, normaliseOpenAiStream, normaliseStream, } from "./streaming";
 export type { StreamChunk } from "./streaming";
-export { GatewayResponseError, GatewayUnreachableError, createGatewayTransport, } from "./transports/gateway";
+export { GatewayResponseError, GatewayUnreachableError, SERVED_MODEL_HEADER, SERVED_PROVIDER_HEADER, createGatewayTransport, servedModelOf, } from "./transports/gateway";
 export type { GatewayTransportConfig } from "./transports/gateway";
 export { DirectTransportRefusedError, createDirectTransport, resolveDefaultDirectCaller, } from "./transports/direct";
 export type { DirectCaller, DirectCallerUsage, DirectTransportConfig, } from "./transports/direct";
-export type { AliasCallOptions, AliasCallResult, LlmAlias, LlmAliasBudget, LlmAliasDefinition, LlmClientConfig, LlmCriticality, LlmLatencyClass, LlmModelIdStatus, LlmOpenItem, LlmPriceAnchor, LlmProvider, LlmProviderTier, LlmResponseFormat, LlmRoute, LlmRouteDefaults, LlmRouteParams, LlmRouteRole, LlmRouteTable, LlmToolCall, LlmToolChoice, LlmTransport, LlmTransportRequest, LlmTransportResponse, LlmUsageRecord, LlmValidationOutcome, ResolvedRoute, } from "./types";
+export type { AliasCallOptions, AliasCallResult, LlmAlias, LlmAliasBudget, LlmAliasDefinition, LlmClientConfig, LlmCriticality, LlmCrossModelPolicy, LlmHedgingDefaults, LlmLatencyClass, LlmLatencyTripDefaults, LlmModelClassRelation, LlmModelIdStatus, LlmOpenItem, LlmPriceAnchor, LlmProvider, LlmProviderTier, LlmResponseFormat, LlmRoute, LlmRouteDefaults, LlmRouteEquivalent, LlmRouteParams, LlmRouteRole, LlmRouteTable, LlmToolCall, LlmToolChoice, LlmTransport, LlmTransportRequest, LlmTransportResponse, LlmUsageRecord, LlmValidationOutcome, ResolvedRoute, } from "./types";
 //# sourceMappingURL=index.d.ts.map

package/dist/types/llm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/llm/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7F,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,QAAQ,GACT,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAElD,OAAO,EACL,oBAAoB,EACpB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,WAAW,EACX,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAEnE,OAAO,EACL,sBAAsB,EACtB,0BAA0B,EAC1B,wBAAwB,EACxB,eAAe,EACf,aAAa,GACd,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,qBAAqB,EACrB,cAAc,EACd,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,cAAc,GACf,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,YAAY,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAErE,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EAAE,kBAAkB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE3F,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACjG,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EACL,mBAAmB,EACnB,oBAAoB,EACpB,aAAa,EACb,wBAAwB,EACxB,qBAAqB,EACrB,eAAe,GAChB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAEnE,OAAO,EACL,2BAA2B,EAC3B,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,WAAW,EACX,cAAc,EACd,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,aAAa,EACb,YAAY,EACZ,mBAAmB,EACnB,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACpB,aAAa,GACd,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/llm/index.ts"],"names":[],"mappings":"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"}

package/dist/types/llm/leg-attempt.d.ts

@@ -0,0 +1,165 @@
+/**
+ * One attempt against one leg: dispatch under a hard timeout, and the
+ * classification of how it ended.
+ *
+ * Split from the chain walker so the same-model hedge runner and the walker
+ * share exactly one definition of what a timeout, a capacity refusal, a
+ * cancellation and a superseded attempt are. Two copies of that
+ * classification would drift, and the breaker would then read the same event
+ * differently depending on which code path produced it.
+ *
+ * @module llm/leg-attempt
+ */
+import { UnsupportedCapabilityError } from "./param-matrix";
+import type { BreakerFailureKind } from "./circuit-breaker";
+import type { AliasAttemptRecord, LlmTransport, LlmTransportRequest, LlmTransportResponse, LlmUsageRecord, ResolvedRoute } from "./types";
+/** What one leg of the chain needs in order to run. */
+export interface ChainLeg {
+    readonly route: ResolvedRoute;
+    /** The transport that will carry this leg. */
+    readonly transport: LlmTransport;
+    /** Provider-normalised parameters, or the error that made this leg unusable. */
+    readonly params: Record<string, unknown> | UnsupportedCapabilityError;
+    /**
+     * The same model at other live providers, prepared like the leg itself.
+     * Reached before any different-model leg, and only through hedging.
+     */
+    readonly equivalents?: readonly ChainLeg[];
+}
+/** The request-shaped part of a call that every attempt carries unchanged. */
+export interface AttemptRequest {
+    readonly content: string | readonly unknown[];
+    readonly responseFormat: LlmTransportRequest["responseFormat"];
+    readonly developerPrompt?: string;
+    readonly context?: readonly unknown[];
+    readonly correlationId?: string;
+    /** The caller's own cancellation, honoured ahead of any per-attempt budget. */
+    readonly callerSignal?: AbortSignal;
+}
+/** Raised internally when an attempt exceeds its hard budget. */
+export declare class LegTimeoutError extends Error {
+    /**
+     * @param routeKey The leg that timed out.
+     * @param budgetMs Its budget in milliseconds.
+     */
+    constructor(routeKey: string, budgetMs: number);
+}
+/**
+ * Raised internally when an attempt ran past its MEASURED timeout and was
+ * replaced by another attempt on the same model.
+ *
+ * Not a verdict on the provider: the measured timeout is the chain's own
+ * impatience, applied only because a same-model alternative could take over,
+ * so the breaker learns nothing from it.
+ */
+export declare class AttemptSupersededError extends Error {
+    /**
+     * @param routeKey The attempt's leg.
+     * @param afterMs How long it ran before it was replaced.
+     */
+    constructor(routeKey: string, afterMs: number);
+}
+/**
+ * Raised internally on an attempt that was still running when another
+ * attempt on the same model answered first. Not a verdict on the provider.
+ */
+export declare class HedgeLoserError extends Error {
+    /**
+     * @param routeKey The losing attempt's leg.
+     */
+    constructor(routeKey: string);
+}
+/** An attempt in flight. */
+export interface AttemptHandle<T> {
+    readonly promise: Promise<LlmTransportResponse<T>>;
+    /** Cancel the attempt, recording why; the first reason given is kept. */
+    readonly abort: (reason: Error) => void;
+    /** The reason this attempt was cancelled by the chain, if it was. */
+    readonly abortReason: () => Error | undefined;
+    /** Whether the attempt's hard budget ran out. */
+    readonly timedOut: () => boolean;
+}
+/**
+ * Start one attempt under a hard timeout, honouring the caller's own cancellation.
+ *
+ * The timer is always cleared and the abort listener always removed, including
+ * on the success path. A long-lived process that leaked one timer per LLM call
+ * would accumulate them at exactly the rate it does useful work.
+ *
+ * @param leg The leg to run.
+ * @param params Normalised parameters for this leg.
+ * @param request The call's request fields and cancellation.
+ * @param budgetMs The attempt's hard budget.
+ * @returns A handle on the attempt.
+ */
+export declare function startAttempt<T>(leg: ChainLeg, params: Record<string, unknown>, request: AttemptRequest, budgetMs: number): AttemptHandle<T>;
+/**
+ * Whether a failure is the provider saying it is full rather than broken.
+ *
+ * Read by shape rather than by class, because the same signal reaches the
+ * chain from more than one transport and not every transport's error class is
+ * importable here.
+ *
+ * @param error The thrown value.
+ * @param reason Its message.
+ * @returns Whether it is a capacity signal.
+ */
+export declare function isCapacitySignal(error: unknown, reason: string): boolean;
+/** What the chain learned from one failed leg. */
+export interface LegFailure {
+    readonly outcome: AliasAttemptRecord["outcome"];
+    readonly reason: string;
+    readonly countsAgainstHealth: boolean;
+    /** Which cooldown the failure earns, when it counts against health. */
+    readonly failureKind: BreakerFailureKind;
+}
+/**
+ * Classify why a leg failed.
+ *
+ * The distinction matters to the breaker: a timeout and a 5xx are evidence the
+ * provider is unhealthy, while the caller cancelling is not. Counting a
+ * cancellation as a provider failure would let a burst of user-cancelled
+ * requests open the breaker on a perfectly healthy route.
+ *
+ * Among failures that do count, a capacity signal (the provider said it is
+ * busy, or the leg ran out its budget waiting on it) is told apart from a hard
+ * failure so the breaker can re-admit a busy route sooner than a broken one. A
+ * timeout is read as capacity: on a reachable provider it is what a full queue
+ * looks like from outside, and a provider that is actually down still costs no
+ * more than one probe per capacity cooldown.
+ *
+ * An attempt the chain itself cancelled — replaced after its measured
+ * timeout, or beaten by a same-model attempt — is not a verdict on the
+ * provider either, and is classified by the chain's reason rather than by
+ * whatever the transport happened to throw on the way out.
+ *
+ * @param error The thrown value.
+ * @param callerSignal The caller's cancellation signal, if any.
+ * @returns The outcome and whether it counts against route health.
+ */
+export declare function classify(error: unknown, callerSignal: AbortSignal | undefined): LegFailure;
+/**
+ * Whether the caller has stopped waiting.
+ *
+ * Read through a function rather than inline, because `AbortSignal.aborted` is
+ * a live getter: it can flip to true while a leg is in flight, but a compiler
+ * that narrowed it at the top of the loop would prove the later check
+ * unreachable and invite its removal. The check is not redundant — it is the
+ * only thing that stops the chain spending money on an answer nobody will read.
+ *
+ * @param signal The caller's signal, if any.
+ * @returns Whether the call has been cancelled.
+ */
+export declare function isAborted(signal: AbortSignal | undefined): boolean;
+/**
+ * The usage a failed leg was billed for, when the leg reached an answer.
+ *
+ * A leg that failed after the provider answered — content that does not parse,
+ * or prose where a tool call was mandatory — was still charged. A leg that
+ * never answered (timeout, outage, skip) carries no usage, and none is invented.
+ *
+ * @param error The thrown value.
+ * @returns The billed usage, or undefined when the leg never produced an answer.
+ */
+export declare function billedUsageOf(error: unknown): LlmUsageRecord | undefined;
+//# sourceMappingURL=leg-attempt.d.ts.map

package/dist/types/llm/leg-attempt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"leg-attempt.d.ts","sourceRoot":"","sources":["../../../src/llm/leg-attempt.ts"],"names":[],"mappings":"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"}