@starci/ai-router 0.2.1 → 0.3.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,167 @@
1
+ import { addToRow } from "./keys.js";
2
+ /**
3
+ * The schema of the durable key store. It is plain SQL (SQLite here; the same tables carry over to Postgres with
4
+ * `BIGINT` times, `DOUBLE PRECISION` cost and `JSONB` lists), so an adapter for another database starts from it.
5
+ */
6
+ export const KEY_STORE_SCHEMA = `
7
+ CREATE TABLE IF NOT EXISTS ai_router_keys (
8
+ id TEXT PRIMARY KEY,
9
+ hash TEXT NOT NULL UNIQUE,
10
+ label TEXT NOT NULL,
11
+ owner TEXT,
12
+ hint TEXT NOT NULL,
13
+ profiles TEXT NOT NULL,
14
+ models TEXT NOT NULL,
15
+ allow_fallback INTEGER NOT NULL,
16
+ quota TEXT NOT NULL,
17
+ enabled INTEGER NOT NULL,
18
+ created_at INTEGER NOT NULL,
19
+ rotated_at INTEGER,
20
+ revoked_at INTEGER
21
+ );
22
+ CREATE TABLE IF NOT EXISTS ai_router_key_rate (
23
+ key_id TEXT PRIMARY KEY,
24
+ minute INTEGER NOT NULL,
25
+ count INTEGER NOT NULL
26
+ );
27
+ CREATE TABLE IF NOT EXISTS ai_router_key_usage (
28
+ key_id TEXT NOT NULL,
29
+ day TEXT NOT NULL,
30
+ requests INTEGER NOT NULL,
31
+ succeeded INTEGER NOT NULL,
32
+ failed INTEGER NOT NULL,
33
+ prompt_tokens INTEGER NOT NULL,
34
+ completion_tokens INTEGER NOT NULL,
35
+ cost REAL NOT NULL,
36
+ latency_ms INTEGER NOT NULL,
37
+ outcomes TEXT NOT NULL,
38
+ PRIMARY KEY (key_id, day)
39
+ );
40
+ `;
41
+ function text(row, column) {
42
+ const value = row[column];
43
+ if (typeof value !== "string")
44
+ throw new Error(`column ${column} is not text`);
45
+ return value;
46
+ }
47
+ function number(row, column) {
48
+ const value = row[column];
49
+ if (typeof value === "bigint")
50
+ return Number(value);
51
+ if (typeof value !== "number")
52
+ throw new Error(`column ${column} is not a number`);
53
+ return value;
54
+ }
55
+ function optionalNumber(row, column) {
56
+ return row[column] === null ? null : number(row, column);
57
+ }
58
+ function parsed(row, column) {
59
+ return JSON.parse(text(row, column));
60
+ }
61
+ function toKey(row) {
62
+ return {
63
+ id: text(row, "id"),
64
+ hash: text(row, "hash"),
65
+ label: text(row, "label"),
66
+ owner: row.owner === null ? null : text(row, "owner"),
67
+ hint: text(row, "hint"),
68
+ profiles: parsed(row, "profiles"),
69
+ models: parsed(row, "models"),
70
+ allowFallback: number(row, "allow_fallback") === 1,
71
+ quota: parsed(row, "quota"),
72
+ enabled: number(row, "enabled") === 1,
73
+ createdAt: number(row, "created_at"),
74
+ rotatedAt: optionalNumber(row, "rotated_at"),
75
+ revokedAt: optionalNumber(row, "revoked_at"),
76
+ };
77
+ }
78
+ function toUsage(row) {
79
+ return {
80
+ keyId: text(row, "key_id"),
81
+ day: text(row, "day"),
82
+ requests: number(row, "requests"),
83
+ succeeded: number(row, "succeeded"),
84
+ failed: number(row, "failed"),
85
+ promptTokens: number(row, "prompt_tokens"),
86
+ completionTokens: number(row, "completion_tokens"),
87
+ cost: number(row, "cost"),
88
+ latencyMs: number(row, "latency_ms"),
89
+ outcomes: parsed(row, "outcomes"),
90
+ };
91
+ }
92
+ /** The durable key store over one SQLite file (`node:sqlite`, Node 22.13 or newer); several processes may share the file. */
93
+ class SqliteKeyStore {
94
+ #db;
95
+ constructor(db) {
96
+ this.#db = db;
97
+ }
98
+ #transaction(work) {
99
+ this.#db.exec("BEGIN IMMEDIATE");
100
+ try {
101
+ const out = work();
102
+ this.#db.exec("COMMIT");
103
+ return out;
104
+ }
105
+ catch (error) {
106
+ this.#db.exec("ROLLBACK");
107
+ throw error;
108
+ }
109
+ }
110
+ put(key) {
111
+ this.#db
112
+ .prepare(`INSERT INTO ai_router_keys (id, hash, label, owner, hint, profiles, models, allow_fallback, quota, enabled, created_at, rotated_at, revoked_at)
113
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
114
+ ON CONFLICT (id) DO UPDATE SET hash = excluded.hash, owner = excluded.owner, hint = excluded.hint, profiles = excluded.profiles,
115
+ models = excluded.models, allow_fallback = excluded.allow_fallback, quota = excluded.quota, enabled = excluded.enabled,
116
+ rotated_at = excluded.rotated_at, revoked_at = excluded.revoked_at`)
117
+ .run(key.id, key.hash, key.label, key.owner, key.hint, JSON.stringify(key.profiles), JSON.stringify(key.models), key.allowFallback ? 1 : 0, JSON.stringify(key.quota), key.enabled ? 1 : 0, key.createdAt, key.rotatedAt, key.revokedAt);
118
+ }
119
+ get(id) {
120
+ const row = this.#db.prepare("SELECT * FROM ai_router_keys WHERE id = ?").get(id);
121
+ return row === undefined ? undefined : toKey(row);
122
+ }
123
+ byHash(hash) {
124
+ const row = this.#db.prepare("SELECT * FROM ai_router_keys WHERE hash = ?").get(hash);
125
+ return row === undefined ? undefined : toKey(row);
126
+ }
127
+ list() {
128
+ return this.#db.prepare("SELECT * FROM ai_router_keys ORDER BY created_at, id").all().map(toKey);
129
+ }
130
+ hit(id, minute) {
131
+ const row = this.#db
132
+ .prepare(`INSERT INTO ai_router_key_rate (key_id, minute, count) VALUES (?, ?, 1)
133
+ ON CONFLICT (key_id) DO UPDATE SET count = CASE WHEN minute = excluded.minute THEN count + 1 ELSE 1 END, minute = excluded.minute
134
+ RETURNING count`)
135
+ .get(id, minute);
136
+ return row === undefined ? 1 : number(row, "count");
137
+ }
138
+ record(id, day, delta) {
139
+ this.#transaction(() => {
140
+ const held = this.#db.prepare("SELECT * FROM ai_router_key_usage WHERE key_id = ? AND day = ?").get(id, day);
141
+ const row = addToRow(held === undefined ? undefined : toUsage(held), id, day, delta);
142
+ this.#db
143
+ .prepare(`INSERT INTO ai_router_key_usage (key_id, day, requests, succeeded, failed, prompt_tokens, completion_tokens, cost, latency_ms, outcomes)
144
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
145
+ ON CONFLICT (key_id, day) DO UPDATE SET requests = excluded.requests, succeeded = excluded.succeeded, failed = excluded.failed,
146
+ prompt_tokens = excluded.prompt_tokens, completion_tokens = excluded.completion_tokens, cost = excluded.cost,
147
+ latency_ms = excluded.latency_ms, outcomes = excluded.outcomes`)
148
+ .run(id, day, row.requests, row.succeeded, row.failed, row.promptTokens, row.completionTokens, row.cost, row.latencyMs, JSON.stringify(row.outcomes));
149
+ });
150
+ }
151
+ usage(id, from, to) {
152
+ return this.#db.prepare("SELECT * FROM ai_router_key_usage WHERE key_id = ? AND day >= ? AND day <= ? ORDER BY day").all(id, from, to).map(toUsage);
153
+ }
154
+ close() {
155
+ this.#db.close();
156
+ }
157
+ }
158
+ /** Opens (and creates) the durable key store at a SQLite file path; `:memory:` gives a throwaway database. */
159
+ export async function openSqliteKeyStore(path) {
160
+ const { DatabaseSync } = await import("node:sqlite");
161
+ const db = new DatabaseSync(path);
162
+ db.exec("PRAGMA busy_timeout = 5000");
163
+ if (path !== ":memory:")
164
+ db.exec("PRAGMA journal_mode = WAL");
165
+ db.exec(KEY_STORE_SCHEMA);
166
+ return new SqliteKeyStore(db);
167
+ }
package/dist/index.d.ts CHANGED
@@ -3,7 +3,7 @@ export type { AiRouterModuleExtras, AiRouterRegisterAsyncOptions, AiRouterRegist
3
3
  export type { AiRouterHandlers, AiRouterModuleOptions } from "./ai-router.options.js";
4
4
  export { AiRouterService } from "./ai-router.service.js";
5
5
  export { AI_ROUTER, getAiRouterServiceToken, getAiRouterToken, InjectAiRouter, InjectAiRouterService } from "./ai-router.tokens.js";
6
- export { AiRouterError } from "./errors.js";
7
- export type { AttemptFailure } from "./errors.js";
8
- export type { HealthRecord, StateStore } from "./store.js";
9
- export type * from "./types.js";
6
+ export { AI_ROUTER_GATEWAY, AiRouterGatewayModule, getAiRouterGatewayToken, InjectAiRouterGateway } from "./ai-router-gateway.module.js";
7
+ export type { AiRouterGatewayModuleExtras, AiRouterGatewayModuleOptions, AiRouterGatewayRegisterAsyncOptions, AiRouterGatewayRegisterOptions } from "./ai-router-gateway.module-definition.js";
8
+ export type { AiRouterGatewayListen } from "./ai-router-gateway.listen.js";
9
+ export * from "./gateway/index.js";
package/dist/index.js CHANGED
@@ -1,4 +1,5 @@
1
1
  export { AiRouterModule } from "./ai-router.module.js";
2
2
  export { AiRouterService } from "./ai-router.service.js";
3
3
  export { AI_ROUTER, getAiRouterServiceToken, getAiRouterToken, InjectAiRouter, InjectAiRouterService } from "./ai-router.tokens.js";
4
- export { AiRouterError } from "./errors.js";
4
+ export { AI_ROUTER_GATEWAY, AiRouterGatewayModule, getAiRouterGatewayToken, InjectAiRouterGateway } from "./ai-router-gateway.module.js";
5
+ export * from "./gateway/index.js";
package/dist/router.js CHANGED
@@ -1,4 +1,4 @@
1
- import { resolvePolicy, resolveSettings, validateConfig } from "./config.js";
1
+ import { buildCatalog, resolvePolicy, resolveSettings, validateConfig } from "./config.js";
2
2
  import { AiRouterError, classifyProviderError, classifyStatus, isRetryable, scrub } from "./errors.js";
3
3
  import { Emitter } from "./events.js";
4
4
  import { readRateLimit } from "./headers.js";
@@ -220,6 +220,7 @@ export function createRouter(config) {
220
220
  const state = new PoolState(config.providers, settings, config.store ?? new MemoryStateStore(), emitter);
221
221
  const fetchImpl = config.fetch ?? ((input, init) => fetch(input, init));
222
222
  const random = config.random ?? Math.random;
223
+ const catalog = buildCatalog(config);
223
224
  // The policy is resolved at once, so a bad profile or model throws from the call itself; the clock starts at start().
224
225
  function prepare(operation, model, options, need) {
225
226
  const policy = resolvePolicy(config, options, model);
@@ -580,6 +581,7 @@ export function createRouter(config) {
580
581
  }));
581
582
  return { ...value, routing };
582
583
  },
584
+ catalog: () => catalog,
583
585
  health: () => state.health(),
584
586
  stats: () => state.stats(),
585
587
  on: (event, handler) => emitter.on(event, handler),
package/dist/types.d.ts CHANGED
@@ -423,5 +423,33 @@ export interface AiRouter<Profiles extends string = string> {
423
423
  on<E extends keyof RouterEvents>(event: E, handler: (payload: RouterEvents[E]) => void): () => void;
424
424
  /** Closes breakers, re-enables keys and clears headroom for the target (everything by default). */
425
425
  reset(target?: ResetTarget): Promise<void>;
426
+ /** Lists the pool's profiles and models by name, with no key: what a caller may ask for. */
427
+ catalog(): RouterCatalog;
428
+ }
429
+ /** One model of the pool as the catalog lists it: one entry per configured id, merged across the providers serving it. */
430
+ export interface CatalogModel {
431
+ readonly id: string;
432
+ readonly aliases: readonly string[];
433
+ readonly providers: readonly string[];
434
+ readonly capabilities: readonly Capability[];
435
+ readonly contextWindow?: number;
436
+ readonly cost?: ModelCost;
437
+ }
438
+ /** One named profile as the catalog lists it. */
439
+ export interface CatalogProfile {
440
+ readonly name: string;
441
+ /** The profile's preferred model, else the defaults'; absent when neither names one. */
442
+ readonly model?: string;
443
+ /** The fallbacks the profile tries (its own, else the defaults'); empty when fallback is off. */
444
+ readonly fallbacks: readonly string[];
445
+ }
446
+ /** The names a caller may route by: the defaults' fallbacks, every profile and every model. */
447
+ export interface RouterCatalog {
448
+ readonly defaults: {
449
+ readonly model?: string;
450
+ readonly fallbacks: readonly string[];
451
+ };
452
+ readonly profiles: readonly CatalogProfile[];
453
+ readonly models: readonly CatalogModel[];
426
454
  }
427
455
  export {};
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@starci/ai-router",
3
- "version": "0.2.1",
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.",
3
+ "version": "0.3.0",
4
+ "description": "A router for OpenAI-compatible calls across a pool of keys, models and providers: an OpenAI-compatible gateway with virtual keys, quotas and usage (the ai-router bin), a NestJS module (AiRouterModule, AiRouterService, AiRouterGatewayModule), and createRouter for plain Node, with health-aware selection, circuit breakers, rate-limit awareness, failover, model fallback and redacted telemetry.",
5
5
  "keywords": [
6
6
  "ai",
7
7
  "llm",
@@ -14,7 +14,11 @@
14
14
  "circuit-breaker",
15
15
  "rate-limit",
16
16
  "streaming",
17
- "nestjs"
17
+ "nestjs",
18
+ "gateway",
19
+ "proxy",
20
+ "virtual-keys",
21
+ "langchain"
18
22
  ],
19
23
  "license": "MIT",
20
24
  "author": "starci183",
@@ -36,6 +40,14 @@
36
40
  "types": "./dist/index.d.ts",
37
41
  "default": "./dist/index.js"
38
42
  },
43
+ "./gateway": {
44
+ "types": "./dist/gateway/index.d.ts",
45
+ "default": "./dist/gateway/index.js"
46
+ },
47
+ "./cli": {
48
+ "types": "./dist/gateway/cli.d.ts",
49
+ "default": "./dist/gateway/cli.js"
50
+ },
39
51
  "./testing": {
40
52
  "types": "./dist/testing.d.ts",
41
53
  "default": "./dist/testing.js"
@@ -79,5 +91,19 @@
79
91
  "rxjs": "7.8.2",
80
92
  "typescript": "5.9.3",
81
93
  "typescript-eslint": "8.72.0"
94
+ },
95
+ "dependencies": {
96
+ "yaml": "^2.9.1"
97
+ },
98
+ "peerDependenciesMeta": {
99
+ "@nestjs/common": {
100
+ "optional": "true"
101
+ },
102
+ "@nestjs/core": {
103
+ "optional": "true"
104
+ },
105
+ "reflect-metadata": {
106
+ "optional": "true"
107
+ }
82
108
  }
83
109
  }