@starci/ai-router 0.6.0 → 0.6.1

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,9 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.1 - 2026-11-13
4
+
5
+ - Changed: the README's examples use neutral profile, label and owner names. No code changes.
6
+
3
7
  ## 0.6.0 - 2026-11-08
4
8
 
5
9
  - Added: `AiRouterError`, `KeyAdminError` and `MountedKeyError` extend `DomainError` of `@starci/common` (a runtime dependency), so an app and its canon recognise them as coded errors. `AiRouterError.code` is `AI_ROUTER_<CLASS>` (`AI_ROUTER_ERROR_CODES`, `AiRouterErrorCode`, exported); the two key errors keep their code values. Class names, fields and messages are unchanged.
package/README.md CHANGED
@@ -138,7 +138,7 @@ providers:
138
138
  models: [{ id: openai/gpt-4o-mini, aliases: [fast] }]
139
139
  defaults: { fallbacks: [smart], deadlineMs: 60000 }
140
140
  profiles:
141
- lesson: { model: fast, fallbacks: [smart] }
141
+ chat: { model: fast, fallbacks: [smart] }
142
142
  grading: { model: smart, allowFallback: false, maxAttempts: 3 }
143
143
  ```
144
144
 
@@ -152,7 +152,7 @@ profiles:
152
152
  | `GET /health` | none; the admin token adds the pool's breakers and keys | `{ "status": "ok" }`, or `degraded` when no provider has a usable key |
153
153
  | `/admin/keys...` | admin token | the [admin API](#admin-api) |
154
154
 
155
- A request's `model` names a profile (`lesson`) or a pool model by id or alias (`gpt-4o-mini`, `fast`); a profile wins
155
+ A request's `model` names a profile (`chat`) or a pool model by id or alias (`gpt-4o-mini`, `fast`); a profile wins
156
156
  when a name is both. A profile call routes by the profile's policy; a direct model call falls back only to the pool
157
157
  defaults' fallbacks that the key may call itself. The answer is the provider's OpenAI body without the router's
158
158
  `routing`; the response carries `x-request-id`, and a unary one `x-ai-router-model` (the model that answered) and
@@ -216,7 +216,7 @@ AiRouterGatewayModule.registerAsync({
216
216
  keys: await openSqliteKeyStore("/data/keys.sqlite"),
217
217
  mountedKeys: [
218
218
  // The secret is sk-starci-<label>- and at least 32 letters, digits, "_" or "-": openssl rand -hex 24
219
- { label: "nivo_lite", secret: () => readFileSync("/run/secrets/nivo_lite_ai_key", "utf8").trim(), profiles: ["lesson"], owner: "nivo-lite", quota: { costPerMonth: 20 } },
219
+ { label: "app_one", secret: () => readFileSync("/run/secrets/app_one_ai_key", "utf8").trim(), profiles: ["chat"], owner: "app-one", quota: { costPerMonth: 20 } },
220
220
  ],
221
221
  listen: true,
222
222
  }),
@@ -254,7 +254,7 @@ Guarded by `Authorization: Bearer <admin token>` (403 `admin_disabled` when no t
254
254
 
255
255
  ```sh
256
256
  RUN="node node_modules/@starci/ai-router/dist/gateway/run.js"
257
- $RUN keys create --label lesson_app --profiles lesson --rpm 60 --cost-per-month 20 --config pool.yaml
257
+ $RUN keys create --label chat_app --profiles chat --rpm 60 --cost-per-month 20 --config pool.yaml
258
258
  $RUN keys list --config pool.yaml
259
259
  $RUN keys usage key_1a2b3c4d5e6f7a8b --from 2026-10-01 --config pool.yaml
260
260
  $RUN keys rotate key_1a2b3c4d5e6f7a8b --url http://gateway:8080 # admin token from AI_ROUTER_ADMIN_TOKEN
@@ -273,7 +273,7 @@ LangChain (JS):
273
273
  import { ChatOpenAI, OpenAIEmbeddings } from "@langchain/openai"
274
274
 
275
275
  const llm = new ChatOpenAI({
276
- model: "lesson", // a profile, or a pool model such as "gpt-4o-mini"
276
+ model: "chat", // a profile, or a pool model such as "gpt-4o-mini"
277
277
  apiKey: process.env.STARCI_AI_KEY, // sk-starci-...
278
278
  configuration: { baseURL: "http://127.0.0.1:3002/v1" },
279
279
  })
@@ -283,7 +283,7 @@ for await (const chunk of await llm.stream("Count to five.")) process.stdout.wri
283
283
  const embeddings = new OpenAIEmbeddings({ model: "text-embedding-3-small", apiKey: process.env.STARCI_AI_KEY, configuration: { baseURL: "http://127.0.0.1:3002/v1" } })
284
284
  ```
285
285
 
286
- LangChain (Python): `ChatOpenAI(model="lesson", api_key=..., base_url="http://127.0.0.1:3002/v1")`.
286
+ LangChain (Python): `ChatOpenAI(model="chat", api_key=..., base_url="http://127.0.0.1:3002/v1")`.
287
287
 
288
288
  The OpenAI SDK, or any compatible client:
289
289
 
@@ -291,12 +291,12 @@ The OpenAI SDK, or any compatible client:
291
291
  import OpenAI from "openai"
292
292
 
293
293
  const client = new OpenAI({ apiKey: process.env.STARCI_AI_KEY, baseURL: "http://127.0.0.1:3002/v1" })
294
- const completion = await client.chat.completions.create({ model: "lesson", messages: [{ role: "user", content: "hi" }] })
294
+ const completion = await client.chat.completions.create({ model: "chat", messages: [{ role: "user", content: "hi" }] })
295
295
  ```
296
296
 
297
297
  ```sh
298
298
  curl http://127.0.0.1:3002/v1/chat/completions -H "Authorization: Bearer $STARCI_AI_KEY" \
299
- -H "content-type: application/json" -d '{"model":"lesson","stream":true,"messages":[{"role":"user","content":"hi"}]}'
299
+ -H "content-type: application/json" -d '{"model":"chat","stream":true,"messages":[{"role":"user","content":"hi"}]}'
300
300
  ```
301
301
 
302
302
  ### Deploy
@@ -356,7 +356,7 @@ fails with an `AiRouterError` saying the port is unknown and `listen.port` is th
356
356
  (`127.0.0.1`) and is `0.0.0.0` only when you set it. With `serve`, `gateway.appPort` plus `gateway.portOffset`
357
357
  (default 1) does the same; it cannot be combined with `gateway.port`.
358
358
 
359
- A client of an API on 3001 uses `http://127.0.0.1:3002/v1` as its OpenAI base URL: LangChain (below), OpenClaw, or any
359
+ A client of an API on 3001 uses `http://127.0.0.1:3002/v1` as its OpenAI base URL: LangChain (below) or any
360
360
  OpenAI-compatible agent, with a virtual `sk-starci-...` key as its API key.
361
361
 
362
362
  ## Use it in a Nest app
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starci/ai-router",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "A router for OpenAI-compatible calls across many providers (Anthropic through a protocol adapter, OpenRouter, Qwen, DeepSeek, OpenAI, Gemini, Groq and any OpenAI-compatible endpoint), each with an array of keys, behind one virtual key: an OpenAI-compatible gateway with virtual keys, quotas and usage, a NestJS module (AiRouterModule, AiRouterService, AiRouterGatewayModule), and createRouter for plain Node, with health-aware selection, a persisted key blacklist for spent quotas and refused secrets, circuit breakers, rate-limit awareness, failover across providers and models by profile, pinned embeddings, config from env and redacted telemetry.",
5
5
  "keywords": [
6
6
  "ai",
@@ -118,6 +118,6 @@
118
118
  "optional": "true"
119
119
  }
120
120
  },
121
- "gitHead": "f464f759079854716389ba92feb7e4a1512a0ee3",
122
- "starciSource": "c57d560e0d60ee78ffc8bf782cdcf1ef71d18b919a1f08cc07ecbcb66abb7dee"
121
+ "gitHead": "5ba3e3393ad44562f0245d829949e70a2313af81",
122
+ "starciSource": "236cf93297937b0438f9af5156b9a4794d2d1c54c05b91331e0fd16db80cbae6"
123
123
  }