@starci/ai-router 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,56 @@
1
+ import type { MaybePromise } .js";
2
+ /**
3
+ * The shared health of one key, one provider or one key and model ("lane"). Every field is a JSON number, string or
4
+ * null, so an adapter can store it anywhere. Times are epoch milliseconds; 0 means "not set".
5
+ */
6
+ export interface HealthRecord {
7
+ /** `open` past `openUntil` is reported as half-open and admits one probe. */
8
+ readonly breaker: "closed" | "open";
9
+ /** Consecutive transient failures since the last success. */
10
+ readonly failures: number;
11
+ readonly openUntil: number;
12
+ /** The cooldown the breaker last opened with; the next failed probe doubles it. */
13
+ readonly cooldownMs: number;
14
+ /** A disabled key is no candidate until then; `Number.MAX_SAFE_INTEGER` means until `reset()`. */
15
+ readonly disabledUntil: number;
16
+ readonly disabledReason: "auth" | "missing" | null;
17
+ /** The lane's last reported remaining requests, or null when the provider never said. */
18
+ readonly remainingRequests: number | null;
19
+ readonly requestsResetAt: number;
20
+ readonly remainingTokens: number | null;
21
+ readonly tokensResetAt: number;
22
+ /** A 429 keeps the lane out until then. */
23
+ readonly cooldownUntil: number;
24
+ }
25
+ /**
26
+ * Where breaker, disabled-key and headroom state lives. The in-memory store is the default; an adapter over Redis, a
27
+ * database or any shared map lets several processes see each other's breakers. Methods may be synchronous or async.
28
+ */
29
+ export interface StateStore {
30
+ get(key: string): MaybePromise<HealthRecord | undefined>;
31
+ set(key: string, record: HealthRecord): MaybePromise<void>;
32
+ delete(key: string): MaybePromise<void>;
33
+ /** Every key that starts with the prefix; `reset()` uses it. */
34
+ keys(prefix: string): MaybePromise<readonly string[]>;
35
+ /** Takes the lease if it is free or expired and returns true; returns false while another holder has it. Must be atomic. */
36
+ lease(key: string, ttlMs: number): MaybePromise<boolean>;
37
+ release(key: string): MaybePromise<void>;
38
+ }
39
+ /** A record with nothing known: a closed breaker, an enabled key, unknown headroom. */
40
+ export declare const EMPTY_RECORD: HealthRecord;
41
+ /** The default store: one process's memory. */
42
+ export declare class MemoryStateStore implements StateStore {
43
+ #private;
44
+ /** Reads a record. */
45
+ get(key: string): HealthRecord | undefined;
46
+ /** Writes a record. */
47
+ set(key: string, record: HealthRecord): void;
48
+ /** Removes a record. */
49
+ delete(key: string): void;
50
+ /** Lists the record keys under a prefix. */
51
+ keys(prefix: string): readonly string[];
52
+ /** Takes a lease when free or expired. */
53
+ lease(key: string, ttlMs: number): boolean;
54
+ /** Frees a lease. */
55
+ release(key: string): void;
56
+ }
package/dist/store.js ADDED
@@ -0,0 +1,48 @@
1
+ /** A record with nothing known: a closed breaker, an enabled key, unknown headroom. */
2
+ export const EMPTY_RECORD = Object.freeze({
3
+ breaker: "closed",
4
+ failures: 0,
5
+ openUntil: 0,
6
+ cooldownMs: 0,
7
+ disabledUntil: 0,
8
+ disabledReason: null,
9
+ remainingRequests: null,
10
+ requestsResetAt: 0,
11
+ remainingTokens: null,
12
+ tokensResetAt: 0,
13
+ cooldownUntil: 0,
14
+ });
15
+ /** The default store: one process's memory. */
16
+ export class MemoryStateStore {
17
+ #records = new Map();
18
+ #leases = new Map();
19
+ /** Reads a record. */
20
+ get(key) {
21
+ return this.#records.get(key);
22
+ }
23
+ /** Writes a record. */
24
+ set(key, record) {
25
+ this.#records.set(key, record);
26
+ }
27
+ /** Removes a record. */
28
+ delete(key) {
29
+ this.#records.delete(key);
30
+ }
31
+ /** Lists the record keys under a prefix. */
32
+ keys(prefix) {
33
+ return [...this.#records.keys()].filter((key) => key.startsWith(prefix));
34
+ }
35
+ /** Takes a lease when free or expired. */
36
+ lease(key, ttlMs) {
37
+ const now = Date.now();
38
+ const held = this.#leases.get(key);
39
+ if (held !== undefined && held > now)
40
+ return false;
41
+ this.#leases.set(key, now + ttlMs);
42
+ return true;
43
+ }
44
+ /** Frees a lease. */
45
+ release(key) {
46
+ this.#leases.delete(key);
47
+ }
48
+ }
@@ -0,0 +1,4 @@
1
+ export { AiRouterTestingModule } .js";
2
+ export type { AiRouterTestingOptions } .js";
3
+ export { createFakeProvider } .js";
4
+ export type { FakeCall, FakeMatch, FakeProvider, FakeReply, FakeStream } .js";
@@ -0,0 +1,2 @@
1
+ export { AiRouterTestingModule } from "./ai-router-testing.module.js";
2
+ export { createFakeProvider } from "./fake.js";
@@ -0,0 +1,427 @@
1
+ import type { StateStore } .js";
2
+ /** A value or a promise of it: store adapters and key resolvers may answer either way. */
3
+ export type MaybePromise<T> = T | Promise<T>;
4
+ /** What a model can do; a request needs every capability its shape implies. */
5
+ export type Capability = "chat" | "streaming" | "tools" | "json" | "embeddings" | "vision";
6
+ /** The price of a model per one million tokens, in whatever currency the pool uses. */
7
+ export interface ModelCost {
8
+ readonly input: number;
9
+ readonly output: number;
10
+ }
11
+ /** One model a provider serves. `id` is the name sent to the provider; `aliases` are names a caller may use instead. */
12
+ export interface ModelConfig {
13
+ readonly id: string;
14
+ readonly aliases?: readonly string[];
15
+ readonly contextWindow?: number;
16
+ readonly cost?: ModelCost;
17
+ /** Omitted means every chat capability (chat, streaming, tools, json) and no embeddings. */
18
+ readonly capabilities?: readonly Capability[];
19
+ readonly weight?: number;
20
+ }
21
+ /** Returns the secret of a key at the moment of an attempt; an empty or missing answer disables the key. */
22
+ export type KeyResolver = () => MaybePromise<string | undefined>;
23
+ interface KeyCommon {
24
+ /** The name of the key in telemetry, health and errors; the secret itself is never exposed. */
25
+ readonly alias: string;
26
+ readonly weight?: number;
27
+ /** The most requests this key carries at once in this process. */
28
+ readonly maxConcurrency?: number;
29
+ }
30
+ /** A key read from an environment variable at each attempt. */
31
+ export interface EnvKeyConfig extends KeyCommon {
32
+ readonly env: string;
33
+ }
34
+ /** A key returned by a resolver function at each attempt (a vault, a rotation, a test value). */
35
+ export interface ResolverKeyConfig extends KeyCommon {
36
+ readonly resolve: KeyResolver;
37
+ }
38
+ /** One API key of a provider, given by reference: an environment variable name or a resolver. */
39
+ export type KeyConfig = EnvKeyConfig | ResolverKeyConfig;
40
+ /** One OpenAI-compatible endpoint with its keys and models. */
41
+ export interface ProviderConfig {
42
+ readonly id: string;
43
+ /** The base URL the OpenAI paths hang from, such as `https://api.openai.com/v1`. */
44
+ readonly baseUrl: string;
45
+ readonly headers?: Readonly<Record<string, string>>;
46
+ readonly weight?: number;
47
+ /** The most requests this provider carries at once in this process, across its keys. */
48
+ readonly maxConcurrency?: number;
49
+ readonly keys: readonly KeyConfig[];
50
+ readonly models: readonly ModelConfig[];
51
+ }
52
+ /** How one call picks and falls back between models. */
53
+ export interface ModelPolicy {
54
+ /** The preferred model (id or alias); the request's own `model` is used when this is absent. */
55
+ readonly model?: string;
56
+ /** Models tried, in order, once the preferred model has no usable candidate. */
57
+ readonly fallbacks?: readonly string[];
58
+ /** False pins the call to the preferred model; the fallbacks are ignored. Default true. */
59
+ readonly allowFallback?: boolean;
60
+ /** The most attempts across keys, providers and models. Default 4. */
61
+ readonly maxAttempts?: number;
62
+ /** The limit of one attempt in milliseconds (for a stream: until the first token, then between chunks). Default 60000. */
63
+ readonly timeoutMs?: number;
64
+ /** The limit of the whole call in milliseconds, waits and retries included. Default 120000. */
65
+ readonly deadlineMs?: number;
66
+ /** A model whose estimated worst-case cost for this request exceeds `maxCost` is not a candidate. */
67
+ readonly budget?: {
68
+ readonly maxCost?: number;
69
+ };
70
+ /** Restricts the call to these provider ids. */
71
+ readonly providers?: readonly string[];
72
+ /** Capabilities required beyond those the request shape implies. */
73
+ readonly require?: readonly Capability[];
74
+ }
75
+ /** The thresholds of a circuit breaker. */
76
+ export interface BreakerConfig {
77
+ /** Consecutive failures that open the breaker. */
78
+ readonly failureThreshold?: number;
79
+ /** The first cooldown of an open breaker; it doubles on each failed probe. */
80
+ readonly cooldownMs?: number;
81
+ /** The cooldown never grows past this. */
82
+ readonly maxCooldownMs?: number;
83
+ }
84
+ /** The retry and breaker behaviour of the pool. */
85
+ export interface ResilienceConfig {
86
+ /** The breaker of each key. Defaults: 3 failures, 15000 ms, 300000 ms. */
87
+ readonly keyBreaker?: BreakerConfig;
88
+ /** The breaker of each provider, fed by every key's transient failures. Defaults: 8 failures, 30000 ms, 300000 ms. */
89
+ readonly providerBreaker?: BreakerConfig;
90
+ /** Jittered exponential backoff between attempts after a transient failure. Defaults: 100 ms, factor 2, 5000 ms. */
91
+ readonly backoff?: {
92
+ readonly baseMs?: number;
93
+ readonly factor?: number;
94
+ readonly maxMs?: number;
95
+ };
96
+ /** How long a key that answered 401/403 stays disabled; null keeps it disabled until `reset()`. Default null. */
97
+ readonly authDisableMs?: number | null;
98
+ /** The cooldown of a key and model after a 429 without a retry-after header. Default 10000. */
99
+ readonly rateLimitCooldownMs?: number;
100
+ }
101
+ /** How candidates of equal health are ranked. */
102
+ export interface SelectionConfig {
103
+ /**
104
+ * A candidate whose latency EWMA exceeds `best * latencyTolerance + latencySlackMs` drops out of the tie.
105
+ * Defaults 1.5 and 50 ms; the slack keeps millisecond jitter from deciding between equally fast keys. A lane is ranked
106
+ * by latency once it has three samples, and one left out drifts toward the best EWMA until it is tried again.
107
+ */
108
+ readonly latencyTolerance?: number;
109
+ readonly latencySlackMs?: number;
110
+ /** The weight of the newest latency sample in the EWMA. Default 0.3. */
111
+ readonly ewmaAlpha?: number;
112
+ /** A key and model with this many remaining requests or fewer is used only when nothing healthier is. Default 1. */
113
+ readonly lowHeadroom?: number;
114
+ }
115
+ /** The opt-in content of telemetry. */
116
+ export interface TelemetryConfig {
117
+ /** True adds the request body and the response to attempt events. Default false. */
118
+ readonly includeContent?: boolean;
119
+ }
120
+ /** A `fetch`-compatible function; the global `fetch` is the default. */
121
+ export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
122
+ /** The whole pool as data. `Profiles` names the policy profiles a call may select. */
123
+ export interface PoolConfig<Profiles extends string = string> {
124
+ readonly providers: readonly ProviderConfig[];
125
+ /** The policy every call starts from. */
126
+ readonly defaults?: ModelPolicy;
127
+ /** Named policies a call selects with `{ profile }`; they override `defaults`. */
128
+ readonly profiles?: Readonly<Record<Profiles, ModelPolicy>>;
129
+ readonly resilience?: ResilienceConfig;
130
+ readonly selection?: SelectionConfig;
131
+ readonly telemetry?: TelemetryConfig;
132
+ /** Where breaker and headroom state lives; in memory by default. Share one across processes with an adapter. */
133
+ readonly store?: StateStore;
134
+ /** The prefix of every store key, so several pools can share one store. Default `ai-router`. */
135
+ readonly storeNamespace?: string;
136
+ readonly fetch?: FetchLike;
137
+ /** The random source of jitter, in [0, 1). Default `Math.random`. */
138
+ readonly random?: () => number;
139
+ }
140
+ /** One part of a multi-part message content. */
141
+ export interface ContentPart {
142
+ readonly type: string;
143
+ readonly text?: string;
144
+ readonly [key: string]: unknown;
145
+ }
146
+ /** One tool call an assistant message carries. */
147
+ export interface ToolCall {
148
+ readonly id: string;
149
+ readonly type: "function";
150
+ readonly function: {
151
+ readonly name: string;
152
+ readonly arguments: string;
153
+ };
154
+ }
155
+ /** One message of a chat-completions request. */
156
+ export interface ChatMessage {
157
+ readonly role: "system" | "developer" | "user" | "assistant" | "tool";
158
+ readonly content: string | readonly ContentPart[] | null;
159
+ readonly name?: string;
160
+ readonly tool_calls?: readonly ToolCall[];
161
+ readonly tool_call_id?: string;
162
+ }
163
+ /** An OpenAI chat-completions request; unknown fields pass through to the provider. */
164
+ export interface ChatCompletionRequest {
165
+ /** The model (id or alias); a policy's `model` takes precedence. */
166
+ readonly model?: string;
167
+ readonly messages: readonly ChatMessage[];
168
+ readonly max_tokens?: number;
169
+ readonly max_completion_tokens?: number;
170
+ readonly temperature?: number;
171
+ readonly top_p?: number;
172
+ readonly stop?: string | readonly string[];
173
+ readonly seed?: number;
174
+ readonly user?: string;
175
+ readonly tools?: readonly unknown[];
176
+ readonly tool_choice?: unknown;
177
+ readonly response_format?: {
178
+ readonly type: string;
179
+ readonly [key: string]: unknown;
180
+ };
181
+ readonly stream_options?: {
182
+ readonly include_usage?: boolean;
183
+ };
184
+ readonly [key: string]: unknown;
185
+ }
186
+ /** Token counts a provider reports. */
187
+ export interface Usage {
188
+ readonly prompt_tokens: number;
189
+ readonly completion_tokens?: number;
190
+ readonly total_tokens: number;
191
+ }
192
+ /** Where a successful call went and what it cost. */
193
+ export interface RoutingInfo {
194
+ readonly requestId: string;
195
+ readonly provider: string;
196
+ readonly key: string;
197
+ /** The configured model id that answered. */
198
+ readonly model: string;
199
+ readonly attempts: number;
200
+ readonly latencyMs: number;
201
+ /** Computed from usage and the model's cost; absent when either is unknown. */
202
+ readonly cost?: number;
203
+ }
204
+ /** An OpenAI chat completion, with the routing that produced it. */
205
+ export interface ChatCompletion {
206
+ readonly id: string;
207
+ readonly object: "chat.completion";
208
+ readonly created: number;
209
+ readonly model: string;
210
+ readonly choices: readonly {
211
+ readonly index: number;
212
+ readonly message: {
213
+ readonly role: "assistant";
214
+ readonly content: string | null;
215
+ readonly tool_calls?: readonly ToolCall[];
216
+ readonly [key: string]: unknown;
217
+ };
218
+ readonly finish_reason: string | null;
219
+ }[];
220
+ readonly usage?: Usage;
221
+ readonly routing: RoutingInfo;
222
+ readonly [key: string]: unknown;
223
+ }
224
+ /** One tool-call fragment of a streamed delta. */
225
+ export interface ToolCallDelta {
226
+ readonly index: number;
227
+ readonly id?: string;
228
+ readonly type?: "function";
229
+ readonly function?: {
230
+ readonly name?: string;
231
+ readonly arguments?: string;
232
+ };
233
+ }
234
+ /** One OpenAI chat-completion chunk of a stream. */
235
+ export interface ChatCompletionChunk {
236
+ readonly id: string;
237
+ readonly object: "chat.completion.chunk";
238
+ readonly created: number;
239
+ readonly model: string;
240
+ readonly choices: readonly {
241
+ readonly index: number;
242
+ readonly delta: {
243
+ readonly role?: "assistant";
244
+ readonly content?: string | null;
245
+ readonly tool_calls?: readonly ToolCallDelta[];
246
+ readonly [key: string]: unknown;
247
+ };
248
+ readonly finish_reason: string | null;
249
+ }[];
250
+ readonly usage?: Usage | null;
251
+ readonly [key: string]: unknown;
252
+ }
253
+ /** A stream of chunks plus the id that names the call in telemetry. */
254
+ export interface ChatStream extends AsyncIterable<ChatCompletionChunk> {
255
+ readonly requestId: string;
256
+ }
257
+ /** An OpenAI embeddings request. */
258
+ export interface EmbeddingsRequest {
259
+ readonly model?: string;
260
+ readonly input: string | readonly string[];
261
+ readonly dimensions?: number;
262
+ readonly encoding_format?: "float" | "base64";
263
+ readonly user?: string;
264
+ readonly [key: string]: unknown;
265
+ }
266
+ /** An OpenAI embeddings response, with the routing that produced it. */
267
+ export interface EmbeddingsResponse {
268
+ readonly object: "list";
269
+ readonly data: readonly {
270
+ readonly object: "embedding";
271
+ readonly index: number;
272
+ readonly embedding: readonly number[] | string;
273
+ }[];
274
+ readonly model: string;
275
+ readonly usage?: Usage;
276
+ readonly routing: RoutingInfo;
277
+ }
278
+ /** The per-call options of `chat`, `stream` and `embeddings`. */
279
+ export interface CallOptions<Profiles extends string = string> {
280
+ readonly profile?: Profiles;
281
+ /** Overrides the profile and the defaults, field by field. */
282
+ readonly policy?: ModelPolicy;
283
+ readonly signal?: AbortSignal;
284
+ /** The id sent as `x-request-id` and `idempotency-key` on every attempt; generated when absent. */
285
+ readonly requestId?: string;
286
+ /** Extra headers for this call; they cannot replace `authorization`. */
287
+ readonly headers?: Readonly<Record<string, string>>;
288
+ }
289
+ /** Why an attempt or a call failed. */
290
+ export type ErrorClass = "rate_limit" | "auth" | "transient" | "timeout" | "network" | "stream" | "invalid_request" | "cancelled" | "deadline" | "no_candidate" | "config";
291
+ /** The operation a call performs. */
292
+ export type Operation = "chat" | "stream" | "embeddings";
293
+ /** The state of a breaker as health reports it; `half-open` is an open breaker past its cooldown. */
294
+ export type BreakerState = "closed" | "open" | "half-open";
295
+ /** Emitted once per attempt. Carries no prompt or response unless `telemetry.includeContent` is true. */
296
+ export interface AttemptEvent {
297
+ readonly type: "attempt";
298
+ readonly requestId: string;
299
+ readonly operation: Operation;
300
+ readonly attempt: number;
301
+ readonly provider: string;
302
+ readonly key: string;
303
+ readonly model: string;
304
+ readonly latencyMs: number;
305
+ readonly outcome: "success" | "failure";
306
+ readonly errorClass?: ErrorClass;
307
+ readonly status?: number;
308
+ readonly usage?: Usage;
309
+ readonly cost?: number;
310
+ readonly content?: {
311
+ readonly request: unknown;
312
+ readonly response?: unknown;
313
+ };
314
+ }
315
+ /** Emitted when a key's or a provider's breaker changes state. */
316
+ export interface BreakerEvent {
317
+ readonly type: "breaker";
318
+ readonly scope: "key" | "provider";
319
+ readonly provider: string;
320
+ readonly key?: string;
321
+ readonly from: BreakerState;
322
+ readonly to: BreakerState;
323
+ }
324
+ /** Emitted when a key is disabled: it answered 401/403, or its resolver returned no secret. */
325
+ export interface KeyDisabledEvent {
326
+ readonly type: "key-disabled";
327
+ readonly provider: string;
328
+ readonly key: string;
329
+ readonly reason: "auth" | "missing";
330
+ /** Epoch milliseconds the key returns, or null until `reset()`. */
331
+ readonly until: number | null;
332
+ }
333
+ /** Emitted once per call when it settles. */
334
+ export interface RequestEvent {
335
+ readonly type: "request";
336
+ readonly requestId: string;
337
+ readonly operation: Operation;
338
+ readonly outcome: "success" | "failure";
339
+ readonly attempts: number;
340
+ readonly latencyMs: number;
341
+ readonly provider?: string;
342
+ readonly key?: string;
343
+ readonly model?: string;
344
+ readonly errorClass?: ErrorClass;
345
+ }
346
+ /** Every event the router emits, by name. */
347
+ export interface RouterEvents {
348
+ readonly attempt: AttemptEvent;
349
+ readonly breaker: BreakerEvent;
350
+ readonly "key-disabled": KeyDisabledEvent;
351
+ readonly request: RequestEvent;
352
+ }
353
+ /** The health of one key and model. */
354
+ export interface LaneHealth {
355
+ readonly model: string;
356
+ readonly remainingRequests: number | null;
357
+ readonly remainingTokens: number | null;
358
+ /** Epoch milliseconds until which a 429 keeps this lane out; 0 when none. */
359
+ readonly cooldownUntil: number;
360
+ readonly latencyEwmaMs: number | null;
361
+ }
362
+ /** The health of one key. */
363
+ export interface KeyHealth {
364
+ readonly alias: string;
365
+ readonly breaker: BreakerState;
366
+ readonly failures: number;
367
+ readonly disabled: boolean;
368
+ readonly disabledReason: "auth" | "missing" | null;
369
+ readonly inflight: number;
370
+ readonly models: readonly LaneHealth[];
371
+ }
372
+ /** The health of one provider. */
373
+ export interface ProviderHealth {
374
+ readonly id: string;
375
+ readonly breaker: BreakerState;
376
+ readonly failures: number;
377
+ readonly inflight: number;
378
+ readonly keys: readonly KeyHealth[];
379
+ }
380
+ /** A snapshot of the pool's health. */
381
+ export interface HealthSnapshot {
382
+ readonly at: number;
383
+ readonly providers: readonly ProviderHealth[];
384
+ }
385
+ /** Counters of one provider, key and model in this process. */
386
+ export interface LaneStats {
387
+ readonly provider: string;
388
+ readonly key: string;
389
+ readonly model: string;
390
+ readonly attempts: number;
391
+ readonly successes: number;
392
+ readonly failures: Readonly<Partial<Record<ErrorClass, number>>>;
393
+ readonly promptTokens: number;
394
+ readonly completionTokens: number;
395
+ readonly cost: number;
396
+ }
397
+ /** Counters of this process since the router was created. */
398
+ export interface StatsSnapshot {
399
+ readonly requests: number;
400
+ readonly succeeded: number;
401
+ readonly failed: number;
402
+ readonly attempts: number;
403
+ readonly lanes: readonly LaneStats[];
404
+ }
405
+ /** What `reset()` clears: everything, one provider, or one key of a provider. */
406
+ export interface ResetTarget {
407
+ readonly provider?: string;
408
+ readonly key?: string;
409
+ }
410
+ /** The raw router behind `AiRouterService`, injected with `@InjectAiRouter()` (token `AI_ROUTER`). */
411
+ export interface AiRouter<Profiles extends string = string> {
412
+ /** Sends a chat-completions request through the pool. */
413
+ chat(request: ChatCompletionRequest, options?: CallOptions<Profiles>): Promise<ChatCompletion>;
414
+ /** Streams a chat completion as OpenAI chunks; fails over only before the first token. */
415
+ stream(request: ChatCompletionRequest, options?: CallOptions<Profiles>): ChatStream;
416
+ /** Sends an embeddings request through the pool. */
417
+ embeddings(request: EmbeddingsRequest, options?: CallOptions<Profiles>): Promise<EmbeddingsResponse>;
418
+ /** Reads every breaker, disabled key and headroom from the store. */
419
+ health(): Promise<HealthSnapshot>;
420
+ /** Returns this process's counters. */
421
+ stats(): StatsSnapshot;
422
+ /** Subscribes to an event; returns the unsubscribe function. */
423
+ on<E extends keyof RouterEvents>(event: E, handler: (payload: RouterEvents[E]) => void): () => void;
424
+ /** Closes breakers, re-enables keys and clears headroom for the target (everything by default). */
425
+ reset(target?: ResetTarget): Promise<void>;
426
+ }
427
+ export {};
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,83 @@
1
1
  {
2
2
  "name": "@starci/ai-router",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.0",
4
+ "description": "A NestJS module that routes OpenAI-compatible calls across a pool of keys, models and providers: AiRouterModule.register and an injectable AiRouterService for chat, stream and embeddings, with health-aware selection, circuit breakers, rate-limit awareness, retries onto another key, model fallback and redacted telemetry.",
5
+ "keywords": [
6
+ "ai",
7
+ "llm",
8
+ "openai",
9
+ "openai-compatible",
10
+ "router",
11
+ "load-balancer",
12
+ "api-keys",
13
+ "failover",
14
+ "circuit-breaker",
15
+ "rate-limit",
16
+ "streaming",
17
+ "nestjs"
18
+ ],
19
+ "license": "MIT",
20
+ "author": "starci183",
21
+ "homepage": "https://github.com/starci183/starci-harness/tree/main/packages/ai-router#readme",
22
+ "repository": {
23
+ "type": "git",
24
+ "url": "git+https://github.com/starci183/starci-harness.git",
25
+ "directory": "packages/ai-router"
26
+ },
27
+ "bugs": {
28
+ "url": "https://github.com/starci183/starci-harness/issues"
29
+ },
30
+ "private": false,
31
+ "type": "module",
32
+ "main": "./dist/index.js",
33
+ "types": "./dist/index.d.ts",
34
+ "exports": {
35
+ ".": {
36
+ "types": "./dist/index.d.ts",
37
+ "default": "./dist/index.js"
38
+ },
39
+ "./testing": {
40
+ "types": "./dist/testing.d.ts",
41
+ "default": "./dist/testing.js"
42
+ },
43
+ "./package.json": "./package.json"
44
+ },
45
+ "files": [
46
+ "dist",
47
+ "LICENSE",
48
+ "README.md",
49
+ "CHANGELOG.md"
50
+ ],
51
+ "sideEffects": false,
52
+ "engines": {
53
+ "node": ">=20"
54
+ },
55
+ "peerDependencies": {
56
+ "@nestjs/common": "^11.0.0 || ^12.0.0",
57
+ "@nestjs/core": "^11.0.0 || ^12.0.0",
58
+ "reflect-metadata": "^0.1.12 || ^0.2.0"
59
+ },
60
+ "publishConfig": {
61
+ "access": "public",
62
+ "provenance": true
63
+ },
64
+ "scripts": {
65
+ "build": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\" && tsc -p tsconfig.build.json && node -e \"const fs = require('node:fs'); for (const f of fs.readdirSync('dist', {recursive: true}).filter((n) => n.endsWith('.d.ts'))) fs.writeFileSync('dist/' + f, fs.readFileSync('dist/' + f, 'utf8').replace(/((?:from |import\\()\\\"\\.\\.?\\/[\\w./-]+)\\.ts\\\"/g, '$1.js\\\"'))\"",
66
+ "typecheck": "tsc -p tsconfig.json --noEmit",
67
+ "lint": "eslint .",
68
+ "test": "npm run typecheck && npm run lint && node --test --experimental-test-coverage --test-coverage-include=\"src/**/*.ts\" --test-coverage-lines=90 \"test/**/*.test.ts\"",
69
+ "prepublishOnly": "npm test && npm run build"
70
+ },
71
+ "devDependencies": {
72
+ "@eslint/js": "10.0.1",
73
+ "@nestjs/common": "12.1.3",
74
+ "@nestjs/core": "12.1.3",
75
+ "@nestjs/testing": "12.1.3",
76
+ "@types/node": "24.19.2",
77
+ "eslint": "10.13.0",
78
+ "reflect-metadata": "0.2.2",
79
+ "rxjs": "7.8.2",
80
+ "typescript": "5.9.3",
81
+ "typescript-eslint": "8.72.0"
82
+ }
83
+ }