@adaptic/utils 0.0.1014 → 0.0.1016

package/dist/types/llm/route-table.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Typed access to the canonical alias route table.
+ *
+ * The table is imported rather than fetched so an alias always resolves, even
+ * when the gateway is unreachable. A client that could only learn its routes
+ * from the gateway would have no way to fall back when the gateway itself is
+ * the thing that failed, which would make the mandatory fallback chain of PD-3
+ * conditional on the very component it exists to survive.
+ *
+ * Resolution is deliberately conservative in three ways. An unknown alias is an
+ * error rather than a default, because a typo silently served by whichever
+ * model happened to be configured is worse than a loud failure. A route whose
+ * vendor model id is unconfirmed is excluded, because a guessed id fails at the
+ * first live call rather than at review. And a shadow-only route is never
+ * served, because a candidate that can answer a live request has stopped being
+ * a candidate.
+ *
+ * @module llm/route-table
+ */
+import type { LlmAlias, LlmAliasDefinition, LlmProvider, LlmRoute, LlmRouteTable, ResolvedRoute } from "./types";
+/** Suffix naming an alias's research-isolated variant (PD-9). */
+export declare const ISOLATED_SUFFIX = ".isolated";
+/**
+ * The canonical route table.
+ *
+ * Exposed as a readonly view so a consumer can inspect routing without being
+ * able to mutate it. A table that could be edited at runtime would let one
+ * caller change every other caller's routing.
+ */
+export declare const routeTable: LlmRouteTable;
+/**
+ * Every alias the table defines.
+ *
+ * @returns The alias names, sorted for stable iteration.
+ */
+export declare function listAliases(): LlmAlias[];
+/**
+ * Look up an alias definition.
+ *
+ * @param alias The alias to resolve.
+ * @returns Its definition.
+ * @throws When the alias is not defined by the route table.
+ */
+export declare function aliasDefinition(alias: LlmAlias): LlmAliasDefinition;
+/**
+ * Look up a provider registry entry.
+ *
+ * @param name The provider key.
+ * @returns Its registry entry.
+ * @throws When the provider is not registered.
+ */
+export declare function providerEntry(name: string): LlmProvider;
+/** Thrown when a caller names an alias the route table does not define. */
+export declare class UnknownAliasError extends Error {
+    /** The alias that was requested. */
+    readonly alias: string;
+    /** The aliases that do exist, so the message is actionable. */
+    readonly known: readonly string[];
+    /**
+     * @param alias The unrecognised alias.
+     * @param known The aliases the table defines.
+     */
+    constructor(alias: string, known: readonly string[]);
+}
+/** Thrown when an alias exists but has no leg that can currently serve a caller. */
+export declare class NoServableRouteError extends Error {
+    /** The alias that could not be served. */
+    readonly alias: string;
+    /** Why each of its legs was excluded, in chain order. */
+    readonly exclusions: readonly string[];
+    /**
+     * @param alias The alias.
+     * @param exclusions Per-leg reasons, in chain order.
+     */
+    constructor(alias: string, exclusions: readonly string[]);
+}
+/**
+ * Order an alias's routes into the chain the client walks.
+ *
+ * @param definition The alias definition.
+ * @returns Routes ordered primary -> secondary -> closed incumbent.
+ */
+export declare function orderedRoutes(definition: LlmAliasDefinition): LlmRoute[];
+/**
+ * Stable identity for one leg, used to key its circuit breaker and its metrics.
+ *
+ * Keyed by alias, isolation and role rather than by provider and model, because
+ * the breaker guards a position in a chain: reverting an alias to a different
+ * model at the same position should inherit that position's health rather than
+ * start blind, and the isolated variant must never share a breaker with the
+ * shared one.
+ *
+ * @param alias The alias.
+ * @param isolated Whether this is the isolated variant.
+ * @param role The leg's role.
+ * @returns The route key.
+ */
+export declare function routeKeyFor(alias: LlmAlias, isolated: boolean, role: string): string;
+/** Why a leg was left out of a resolved chain. */
+export interface RouteExclusion {
+    readonly role: string;
+    readonly provider: string;
+    readonly reason: string;
+}
+/** A resolved chain, with the reasons any leg was excluded. */
+export interface ResolvedChain {
+    readonly alias: LlmAlias;
+    readonly isolated: boolean;
+    readonly routes: readonly ResolvedRoute[];
+    readonly exclusions: readonly RouteExclusion[];
+}
+/**
+ * Resolve an alias to the ordered chain of legs that can serve it today.
+ *
+ * Exclusions are returned rather than discarded so an exhausted chain can say
+ * why each leg was unavailable. "No route available" without that detail sends
+ * an operator to read config; with it, the answer is in the error.
+ *
+ * @param alias The alias to resolve.
+ * @param options Resolution options.
+ * @param options.isolated Route through the isolated variant (PD-9).
+ * @param options.timeoutMsOverride Per-leg budget override, never wider than the caller's own deadline.
+ * @returns The resolved chain.
+ * @throws {UnknownAliasError} When the alias is not defined.
+ */
+export declare function resolveChain(alias: LlmAlias, options?: {
+    isolated?: boolean;
+    timeoutMsOverride?: number;
+}): ResolvedChain;
+/**
+ * The permanent closed-incumbent leg of an alias (PD-11).
+ *
+ * Found by provider tier rather than by role, because an alias whose primary is
+ * already a closed vendor has that primary as its revert target. Both shapes
+ * therefore hold the same guarantee: there is always a configured route that
+ * needs no new account and no code change to fall back to.
+ *
+ * @param chain A resolved chain.
+ * @returns The closed leg, or undefined when none is currently servable.
+ */
+export declare function closedIncumbentLeg(chain: ResolvedChain): ResolvedRoute | undefined;
+/**
+ * The name the gateway knows a leg by.
+ *
+ * The head of a chain is addressed by the bare alias so a caller never learns a
+ * leg name; every other leg carries the derived name the renderer gives it.
+ * Keeping this derivation beside the resolver — rather than in the transport —
+ * is what stops the client and the gateway config from disagreeing about a name.
+ *
+ * @param route The resolved leg.
+ * @param chain The chain it belongs to.
+ * @returns The gateway `model_name`.
+ */
+export declare function gatewayModelNameFor(route: ResolvedRoute, chain: ResolvedChain): string;
+//# sourceMappingURL=route-table.d.ts.map

package/dist/types/llm/route-table.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"route-table.d.ts","sourceRoot":"","sources":["../../../src/llm/route-table.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,KAAK,EACV,QAAQ,EACR,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,aAAa,EACb,aAAa,EACd,MAAM,SAAS,CAAC;AAKjB,iEAAiE;AACjE,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,EAAE,aAAoD,CAAC;AAE9E;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,QAAQ,EAAE,CAExC;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,kBAAkB,CAMnE;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAQvD;AAED,2EAA2E;AAC3E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,oCAAoC;IACpC,SAAgB,KAAK,EAAE,MAAM,CAAC;IAE9B,+DAA+D;IAC/D,SAAgB,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAEzC;;;OAGG;gBACgB,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE;CAS3D;AAED,oFAAoF;AACpF,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,0CAA0C;IAC1C,SAAgB,KAAK,EAAE,MAAM,CAAC;IAE9B,yDAAyD;IACzD,SAAgB,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAE9C;;;OAGG;gBACgB,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,MAAM,EAAE;CAQhE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,kBAAkB,GAAG,QAAQ,EAAE,CAIxE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,EACf,QAAQ,EAAE,OAAO,EACjB,IAAI,EAAE,MAAM,GACX,MAAM,CAER;AAED,kDAAkD;AAClD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C,QAAQ,CAAC,UAAU,EAAE,SAAS,cAAc,EAAE,CAAC;CAChD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,EACf,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GAC/D,aAAa,CA8Df;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,SAAS,CAElF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,aAAa,EACpB,KAAK,EAAE,aAAa,GACnB,MAAM,CAKR"}

package/dist/types/llm/schema-retry.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Bounded validate-and-retry for structured output.
+ *
+ * A model asked for a schema-shaped answer sometimes returns something close
+ * but wrong. Feeding the validator's own complaint back once fixes most of
+ * those, because the model can see precisely what it got wrong. A second retry
+ * almost never helps: if the model is still wrong after being told exactly what
+ * was wrong, it is persistently wrong for this prompt, and further attempts
+ * spend budget and latency to arrive at the same place.
+ *
+ * The retry lives ahead of the fallback chain rather than inside it. A payload
+ * that fails validation is evidence about the PROMPT, not about the provider's
+ * health, so it must not open a circuit breaker or advance to the next leg —
+ * the next leg would receive the same prompt and be no likelier to satisfy it.
+ *
+ * Exhaustion throws. Returning a partial or defaulted object would hand the
+ * caller a well-typed value that no model ever produced, and the resulting
+ * decision would be made on invented data with nothing to show it.
+ *
+ * @module llm/schema-retry
+ */
+import type { LlmTransportResponse, LlmUsageRecord, LlmValidationOutcome } from "./types";
+/** One validated attempt's result. */
+export interface ValidatedOutcome<T> {
+    readonly value: T;
+    readonly attempts: 1 | 2;
+    readonly response: LlmTransportResponse<unknown>;
+    readonly totalUsage: LlmUsageRecord;
+}
+/**
+ * Thrown when both attempts failed validation.
+ *
+ * Carries both rejection reasons, because the pair is what distinguishes a
+ * flaky answer from a prompt the model cannot satisfy: two different complaints
+ * suggest instability, while the same complaint twice points at the prompt or
+ * the schema.
+ */
+export declare class SchemaRetryExhaustedError extends Error {
+    /** Why the first attempt was rejected. */
+    readonly firstReason: string;
+    /** Why the retry was rejected. */
+    readonly secondReason: string;
+    /** Usage spent across both attempts, so the spend is still accounted for. */
+    readonly totalUsage: LlmUsageRecord;
+    /**
+     * @param firstReason Validator's complaint about attempt one.
+     * @param secondReason Validator's complaint about attempt two.
+     * @param totalUsage Usage across both attempts.
+     */
+    constructor(firstReason: string, secondReason: string, totalUsage: LlmUsageRecord);
+}
+/**
+ * Build the retry prompt.
+ *
+ * The rejected payload is echoed back alongside the complaint, because a model
+ * asked to "fix the error" without seeing what it produced will usually
+ * regenerate from scratch and reproduce the same mistake.
+ *
+ * @param originalPrompt The prompt that produced the invalid payload.
+ * @param rejected The payload that failed.
+ * @param reason The validator's complaint.
+ * @returns The retry prompt.
+ */
+export declare function buildRetryPrompt(originalPrompt: string, rejected: unknown, reason: string): string;
+/**
+ * Run a call with one validator-feedback retry.
+ *
+ * @param options Retry options.
+ * @param options.prompt The original prompt.
+ * @param options.validate Validator applied to each attempt's payload.
+ * @param options.call Executes one attempt with the given prompt.
+ * @returns The validated value with combined usage.
+ * @throws {SchemaRetryExhaustedError} When both attempts fail validation.
+ */
+export declare function callWithValidation<T>(options: {
+    readonly prompt: string;
+    readonly validate: (raw: unknown) => LlmValidationOutcome<T>;
+    readonly call: (prompt: string) => Promise<LlmTransportResponse<unknown>>;
+}): Promise<ValidatedOutcome<T>>;
+//# sourceMappingURL=schema-retry.d.ts.map

package/dist/types/llm/schema-retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-retry.d.ts","sourceRoot":"","sources":["../../../src/llm/schema-retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,cAAc,EACd,oBAAoB,EACrB,MAAM,SAAS,CAAC;AAQjB,sCAAsC;AACtC,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC,OAAO,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,0CAA0C;IAC1C,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC,kCAAkC;IAClC,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC,6EAA6E;IAC7E,SAAgB,UAAU,EAAE,cAAc,CAAC;IAE3C;;;;OAIG;gBAED,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,cAAc;CAY7B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,cAAc,EAAE,MAAM,EACtB,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAiBR;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE;IACnD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,oBAAoB,CAAC,CAAC,CAAC,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;CAC3E,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAmC/B"}

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

@@ -0,0 +1,93 @@
+/**
+ * Streaming normalisation across provider wire formats.
+ *
+ * A caller that streams wants one thing — text as it arrives — but the wire
+ * formats disagree about how to say it. OpenAI-compatible providers emit
+ * server-sent events whose payload nests the increment under
+ * `choices[0].delta.content` and end with a literal `[DONE]` sentinel;
+ * Anthropic emits typed events where the increment is `delta.text` and the end
+ * is an explicit `message_stop`. A consumer written against one shape breaks on
+ * the other, which would make a fallback across providers fail precisely when
+ * the fallback was needed.
+ *
+ * The one behaviour that matters more than the format is how a stream ENDS. A
+ * stream cut short mid-answer looks exactly like a short answer: the consumer
+ * has already received and probably already acted on the text. So a stream
+ * that stops without its terminal event raises rather than returning what it
+ * had — a truncated answer accepted as complete is a wrong answer that nothing
+ * reports.
+ *
+ * @module llm/streaming
+ */
+/** One normalised chunk of a stream. */
+export interface StreamChunk {
+    /** Text produced since the previous chunk. Never null; an empty increment is skipped. */
+    readonly delta: string;
+    /** Cumulative text so far, so a consumer never has to accumulate it itself. */
+    readonly text: string;
+}
+/**
+ * Thrown when a stream ends without its terminal event.
+ *
+ * A distinct type because the caller's correct response differs from a normal
+ * failure: the partial text exists and may be worth logging for diagnosis, but
+ * it must never be treated as the answer.
+ */
+export declare class StreamTruncatedError extends Error {
+    /** Text received before the stream stopped. Present for diagnosis only. */
+    readonly partialText: string;
+    /**
+     * @param partialText What had arrived when the stream stopped.
+     * @param reason Why it stopped, when known.
+     */
+    constructor(partialText: string, reason: string);
+}
+/** Thrown when a provider reports an error inside an already-open stream. */
+export declare class StreamProviderError extends Error {
+    /** Text received before the error. */
+    readonly partialText: string;
+    /**
+     * @param partialText What had arrived when the error appeared.
+     * @param detail The provider's message.
+     */
+    constructor(partialText: string, detail: string);
+}
+/**
+ * Normalise an OpenAI-compatible SSE stream.
+ *
+ * @param source The response body stream.
+ * @returns Normalised chunks.
+ * @throws {StreamTruncatedError} When the stream ends without `[DONE]`.
+ * @throws {StreamProviderError} When an error event appears mid-stream.
+ */
+export declare function normaliseOpenAiStream(source: AsyncIterable<Uint8Array>): AsyncGenerator<StreamChunk>;
+/**
+ * Normalise an Anthropic event stream.
+ *
+ * @param source The response body stream.
+ * @returns Normalised chunks.
+ * @throws {StreamTruncatedError} When the stream ends without `message_stop`.
+ * @throws {StreamProviderError} When an error event appears mid-stream.
+ */
+export declare function normaliseAnthropicStream(source: AsyncIterable<Uint8Array>): AsyncGenerator<StreamChunk>;
+/**
+ * Normalise a stream according to the wire format its provider speaks.
+ *
+ * Selecting on the route's declared API style rather than sniffing the payload
+ * keeps the decision with the route table, which is the thing that actually
+ * knows which provider is answering.
+ *
+ * @param apiStyle The provider's wire format.
+ * @param source The response body stream.
+ * @returns Normalised chunks, identical in shape across providers.
+ */
+export declare function normaliseStream(apiStyle: "openai-compatible" | "anthropic", source: AsyncIterable<Uint8Array>): AsyncGenerator<StreamChunk>;
+/**
+ * Drain a normalised stream into its complete text.
+ *
+ * @param stream A normalised stream.
+ * @returns The full text.
+ * @throws Whatever the stream raises; a truncated stream never resolves to text.
+ */
+export declare function collectStream(stream: AsyncIterable<StreamChunk>): Promise<string>;
+//# sourceMappingURL=streaming.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../../../src/llm/streaming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAiBH,wCAAwC;AACxC,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,2EAA2E;IAC3E,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;OAGG;gBACgB,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAQvD;AAED,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,sCAAsC;IACtC,SAAgB,WAAW,EAAE,MAAM,CAAC;IAEpC;;;OAGG;gBACgB,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAKvD;AAgCD;;;;;;;GAOG;AACH,wBAAuB,qBAAqB,CAC1C,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,cAAc,CAAC,WAAW,CAAC,CA0C7B;AAED;;;;;;;GAOG;AACH,wBAAuB,wBAAwB,CAC7C,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,cAAc,CAAC,WAAW,CAAC,CA2C7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,mBAAmB,GAAG,WAAW,EAC3C,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,GAChC,cAAc,CAAC,WAAW,CAAC,CAI7B;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,GACjC,OAAO,CAAC,MAAM,CAAC,CAMjB"}

package/dist/types/llm/transports/direct.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Degraded direct transport: the path used when the gateway itself is gone.
+ *
+ * Routing every call through one proxy concentrates a great deal of value — one
+ * place to swap a model, one place to bound spend, one place to see cost. It
+ * also concentrates risk: without this path, a gateway outage would take every
+ * LLM call in the system down at once, which is a worse failure than any of the
+ * provider outages the gateway exists to survive.
+ *
+ * Two constraints keep this a safety net rather than a second routing policy.
+ * It serves CLOSED-tier legs only, so the degraded path can never be the thing
+ * that silently promotes an open-weight model past its evaluation gates. And it
+ * resolves the model from the same route table the gateway is rendered from, so
+ * degraded traffic reaches the same model the gateway would have chosen.
+ *
+ * The provider SDK is reached through an injected caller, resolved lazily. A
+ * static import would make `@adaptic/utils` load a provider SDK for every
+ * consumer, including those that never make an LLM call, and would harden a
+ * package cycle that is currently only a declaration.
+ *
+ * @module llm/transports/direct
+ */
+import type { LlmTransport } from "../types";
+/** Usage as the incumbent client reports it; every field is optional there. */
+export interface DirectCallerUsage {
+    readonly prompt_tokens?: number;
+    readonly completion_tokens?: number;
+    readonly reasoning_tokens?: number;
+    readonly cached_tokens?: number;
+    readonly provider?: string;
+    readonly model?: string;
+    readonly cost?: number;
+}
+/**
+ * The provider-calling function this transport delegates to.
+ *
+ * Shaped to match the incumbent `lumic.llm.call` signature so the engine can
+ * register its existing client with no adapter, and so the degraded path
+ * inherits behaviour that is already exercised in production rather than a
+ * second implementation that is only exercised during an outage.
+ */
+export type DirectCaller = <T>(content: string | readonly unknown[], responseFormat: unknown, options: Record<string, unknown>) => Promise<{
+    response: T;
+    usage?: DirectCallerUsage;
+    tool_calls?: unknown;
+}>;
+/** Configuration for the direct transport. */
+export interface DirectTransportConfig {
+    /**
+     * Resolves the provider-calling function.
+     *
+     * Async and called per use so a consumer that never degrades never loads a
+     * provider SDK, and so a consumer that cannot load one fails at the moment it
+     * would have degraded rather than at import.
+     */
+    readonly resolveCaller: () => Promise<DirectCaller>;
+}
+/**
+ * Thrown when the degraded path is asked to serve a leg it must not serve.
+ *
+ * Refusing loudly rather than serving the leg anyway is the point: the whole
+ * value of restricting this path is lost if it quietly widens under pressure,
+ * and pressure is exactly when it runs.
+ */
+export declare class DirectTransportRefusedError extends Error {
+    /**
+     * @param routeKey The leg that was refused.
+     * @param reason Why it cannot be served directly.
+     */
+    constructor(routeKey: string, reason: string);
+}
+/**
+ * Build the degraded direct transport.
+ *
+ * @param config Transport configuration.
+ * @returns A transport that reaches a closed-tier provider without the gateway.
+ */
+export declare function createDirectTransport(config: DirectTransportConfig): LlmTransport;
+/**
+ * The default caller: the incumbent client in `@adaptic/lumic-utils`.
+ *
+ * Resolved with a dynamic import so this module has no load-time dependency on
+ * that package. When it cannot be loaded the failure names the degraded path
+ * explicitly, because "cannot find module" during an outage is otherwise a
+ * confusing second mystery on top of the first — and a consumer that does not
+ * ship that package is expected to register its own transport rather than to
+ * discover this at the moment the gateway fails.
+ *
+ * @returns The provider-calling function.
+ */
+export declare function resolveDefaultDirectCaller(): Promise<DirectCaller>;
+//# sourceMappingURL=direct.d.ts.map

package/dist/types/llm/transports/direct.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"direct.d.ts","sourceRoot":"","sources":["../../../../src/llm/transports/direct.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,YAAY,EAIb,MAAM,UAAU,CAAC;AAElB,+EAA+E;AAC/E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,EAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,OAAO,EAAE,EACpC,cAAc,EAAE,OAAO,EACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC7B,OAAO,CAAC;IACX,QAAQ,EAAE,CAAC,CAAC;IACZ,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,CAAC,CAAC;AAEH,8CAA8C;AAC9C,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,CAAC;CACrD;AAED;;;;;;GAMG;AACH,qBAAa,2BAA4B,SAAQ,KAAK;IACpD;;;OAGG;gBACgB,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAOpD;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,qBAAqB,GAC5B,YAAY,CAsCd;AA0CD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,IAAI,OAAO,CAAC,YAAY,CAAC,CAmBxE"}

package/dist/types/llm/transports/gateway.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Gateway transport: the normal path for every LLM call.
+ *
+ * The client sends an alias to the LiteLLM proxy and the proxy resolves it. The
+ * vendor model string therefore exists only in the gateway's configuration and
+ * never in application code (PD-5), which is what makes a model swap a config
+ * change rather than a deploy.
+ *
+ * The client still walks its own chain on top of the gateway's, and the
+ * duplication is deliberate. The gateway's fallbacks cover a provider being
+ * down; the client's cover the gateway being down. Only one of those two can
+ * cover the other, so the outer chain is the one that must exist.
+ *
+ * The gateway key is read from the environment by NAME at call time and never
+ * stored, logged, or included in an error (PD-2). Reading it per call rather
+ * than caching it at import means a rotation takes effect without a restart.
+ *
+ * @module llm/transports/gateway
+ */
+import type { LlmTransport, LlmTransportRequest } from "../types";
+/** Configuration for the gateway transport. */
+export interface GatewayTransportConfig {
+    /** Base URL of the proxy, e.g. `https://llm-gateway.internal`. */
+    readonly baseUrl: string;
+    /** Env-var NAME holding the gateway key. Never the key itself. */
+    readonly apiKeyEnv: string;
+    /** Injected for testing; defaults to the global fetch. */
+    readonly fetchImpl?: typeof fetch;
+    /**
+     * Resolves the gateway model name for a leg.
+     *
+     * Injected because the naming convention belongs to the route table, and a
+     * transport that reinvented it would be a second place for the client and the
+     * gateway config to disagree about what a leg is called.
+     */
+    readonly modelNameFor: (request: LlmTransportRequest) => string;
+}
+/**
+ * Thrown when the gateway itself is unreachable, as opposed to a provider
+ * behind it failing.
+ *
+ * The distinction is what licenses the degraded direct path: a 502 from a
+ * provider means try the next leg, while a connection refused from the proxy
+ * means the whole gateway is gone and the chain cannot be walked through it at
+ * all.
+ */
+export declare class GatewayUnreachableError extends Error {
+    /**
+     * @param baseUrl The gateway that could not be reached.
+     * @param cause The underlying transport error.
+     */
+    constructor(baseUrl: string, cause: unknown);
+}
+/** Thrown when the gateway answered, but with a failure. */
+export declare class GatewayResponseError extends Error {
+    /** The HTTP status. */
+    readonly status: number;
+    /** Whether advancing to the next leg could plausibly help. */
+    readonly retryable: boolean;
+    /**
+     * @param status The HTTP status.
+     * @param body A bounded excerpt of the response body.
+     */
+    constructor(status: number, body: string);
+}
+/**
+ * Build the gateway transport.
+ *
+ * @param config Transport configuration.
+ * @returns A transport that executes one leg through the proxy.
+ */
+export declare function createGatewayTransport(config: GatewayTransportConfig): LlmTransport;
+//# sourceMappingURL=gateway.d.ts.map

package/dist/types/llm/transports/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../../src/llm/transports/gateway.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,YAAY,EACZ,mBAAmB,EAGpB,MAAM,UAAU,CAAC;AAQlB,+CAA+C;AAC/C,MAAM,WAAW,sBAAsB;IACrC,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,kEAAkE;IAClE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,mBAAmB,KAAK,MAAM,CAAC;CACjE;AAED;;;;;;;;GAQG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAChD;;;OAGG;gBACgB,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAMnD;AAED,4DAA4D;AAC5D,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,uBAAuB;IACvB,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,8DAA8D;IAC9D,SAAgB,SAAS,EAAE,OAAO,CAAC;IAEnC;;;OAGG;gBACgB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAMhD;AAwDD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,YAAY,CA0Dd"}