@mupt-ai/dari-router 0.1.0 → 0.2.1

package/examples/create_router.ts

@@ -0,0 +1,114 @@
+// A complete router with a custom policy and a local executor. Both protocol
+// examples run in-process, so this file needs no API key or network access.
+//
+// Run with: bun run example
+
+import {
+  createRouter,
+  type RouterExecutor,
+  type RoutingPolicy,
+} from "../src/index.js";
+
+const FAST = "demo/fast";
+const STRONG = "demo/strong";
+
+const policy: RoutingPolicy = ({ request, candidates }) => {
+  const promptLength = request.items.reduce((length, item) =>
+    item.type === "message"
+      ? length + item.content.reduce(
+          (total, part) => total + (part.type === "text" ? part.text.length : 0),
+          0,
+        )
+      : length,
+  0);
+  const preferred = promptLength > 80 ? STRONG : FAST;
+  const model = candidates.find((candidate) => candidate.id === preferred)
+    ?? candidates[0]!;
+  return {
+    model: model.id,
+    reason: promptLength > 80
+      ? "The long request uses the stronger model."
+      : "The short request uses the fast model.",
+  };
+};
+
+const localExecutor: RouterExecutor = {
+  execute({ request, model, decision }) {
+    const text = `${model.id} handled ${request.protocol}: ${decision.reason}`;
+    if (!request.stream) {
+      return {
+        type: "complete",
+        output: {
+          content: [{ type: "text", text }],
+          finishReason: "stop",
+          usage: { inputTokens: 12, outputTokens: 8 },
+        },
+      };
+    }
+    return {
+      type: "stream",
+      events: {
+        async *[Symbol.asyncIterator]() {
+          yield { type: "text_delta", index: 0, delta: text } as const;
+          yield {
+            type: "finish",
+            finishReason: "stop",
+            usage: { inputTokens: 12, outputTokens: 8 },
+          } as const;
+        },
+      },
+    };
+  },
+};
+
+const router = createRouter({
+  models: [
+    {
+      id: FAST,
+      executor: "local",
+      reasoningEfforts: ["off"],
+      capabilities: { streaming: true },
+    },
+    {
+      id: STRONG,
+      executor: "local",
+      reasoningEfforts: ["off", "high"],
+      capabilities: {
+        imageInput: true,
+        toolUse: true,
+        structuredOutput: true,
+        streaming: true,
+      },
+    },
+  ],
+  policy,
+  executors: { local: localExecutor },
+});
+
+const openAIResponse = await router.fetch(new Request(
+  "http://router.local/v1/chat/completions",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "my-router",
+      messages: [{ role: "user", content: "Say hello." }],
+    }),
+  },
+));
+console.log("OpenAI Chat Completions:\n", await openAIResponse.json());
+
+const anthropicResponse = await router.fetch(new Request(
+  "http://router.local/v1/messages",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "my-router",
+      max_tokens: 128,
+      messages: [{ role: "user", content: "Stream a short hello." }],
+      stream: true,
+    }),
+  },
+));
+console.log("\nAnthropic Messages stream:\n", await anthropicResponse.text());

package/examples/dari_policy.ts

@@ -0,0 +1,86 @@
+// The framework's optional Dari policy runs the deterministic routing pipeline
+// with an injected selector. This example uses a scripted selector and local
+// executor, so it needs no API key or network access.
+//
+// Run with: bun run example:dari-policy
+
+import { createRouter } from "../src/index.js";
+import {
+  createDariRoutingPolicy,
+  type SelectorInput,
+} from "../src/policy-engine.js";
+
+const FAST = "demo/fast";
+const STRONG = "demo/strong";
+
+const policy = createDariRoutingPolicy({
+  selector: async (request) => {
+    const input = JSON.parse(
+      String(request.messages?.[1]?.content),
+    ) as SelectorInput;
+    const selected = input.candidate_pairs.find(
+      (candidate) => candidate.model === STRONG && candidate.thinking_level === "high",
+    ) ?? input.candidate_pairs[0]!;
+    return JSON.stringify({
+      selected_model: selected.model,
+      reasoning_effort: selected.thinking_level,
+      reason: "The scripted selector chose the stronger candidate.",
+    });
+  },
+  selectorModel: "demo/selector",
+  selectorContextWindowChars: 100_000,
+  pricing: (model) => model === FAST
+    ? { input: 0.2, output: 0.8, cacheRead: 0.05, cacheWrite: 0.2 }
+    : { input: 1, output: 4, cacheRead: 0.1, cacheWrite: 1 },
+  averageOutputTokensByModel: {
+    [FAST]: { off: 300 },
+    [STRONG]: { off: 800, high: 1_600 },
+  },
+});
+
+const router = createRouter({
+  models: [
+    {
+      id: FAST,
+      executor: "local",
+      api: "openai-completions",
+      reasoningEfforts: ["off"],
+    },
+    {
+      id: STRONG,
+      executor: "local",
+      api: "openai-completions",
+      reasoningEfforts: ["off", "high"],
+      defaultReasoningEffort: "high",
+    },
+  ],
+  policy,
+  executors: {
+    local: {
+      execute: ({ model, decision }) => ({
+        type: "complete",
+        output: {
+          content: [{
+            type: "text",
+            text: `${model.id}/${decision.reasoningEffort}: ${decision.reason}`,
+          }],
+          finishReason: "stop",
+        },
+      }),
+    },
+  },
+});
+
+const response = await router.fetch(new Request(
+  "http://router.local/v1/chat/completions",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "my-router",
+      messages: [{ role: "user", content: "Plan a database migration." }],
+    }),
+  },
+));
+
+console.log(await response.json());

package/examples/lease_stores.ts

@@ -0,0 +1,159 @@
+// Shared lease stores for ephemeral or replicated deployments: redis- and
+// postgres-backed LeaseStore implementations against minimal structural client
+// interfaces. The demo runs on in-file fakes (no external services) to show
+// leases surviving a router "restart".
+//
+// Run with: bun run example:lease-stores
+
+import {
+  createRouter,
+  type LeaseStore,
+  type RouterExecutor,
+  type RouterLease,
+  type RoutingPolicy,
+} from "../src/index.js";
+
+// --- Redis-backed store -----------------------------------------------------
+// Expiry is native (PX), so pruneExpired is a no-op.
+
+type RedisLike = {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, options: { PX: number }): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+};
+
+export function redisLeaseStore(redis: RedisLike, keyPrefix = "router-lease:"): LeaseStore {
+  return {
+    async get(cacheKey) {
+      const raw = await redis.get(`${keyPrefix}${cacheKey}`);
+      if (raw === null) return undefined;
+      return JSON.parse(raw) as RouterLease;
+    },
+    async set(cacheKey, lease) {
+      const ttlMs = lease.expiresAt - Date.now();
+      if (ttlMs <= 0) return;
+      await redis.set(`${keyPrefix}${cacheKey}`, JSON.stringify(lease), { PX: ttlMs });
+    },
+    async delete(cacheKey) {
+      await redis.del(`${keyPrefix}${cacheKey}`);
+    },
+    pruneExpired() {},
+  };
+}
+
+// --- Postgres-backed store --------------------------------------------------
+// Table:
+//   create table router_leases (
+//     cache_key text primary key,
+//     model text not null,
+//     reasoning_effort text not null,
+//     turns_remaining int not null,
+//     expires_at bigint not null
+//   );
+//
+// The router re-checks expiresAt itself before honoring a lease, so a lazy
+// pruneExpired (or a cron) is safe. If concurrent same-cacheKey requests
+// matter at your scale, do the turn decrement in SQL behind this interface.
+
+type SqlLike = {
+  query(text: string, params: unknown[]): Promise<{ rows: Record<string, unknown>[] }>;
+};
+
+export function postgresLeaseStore(sql: SqlLike): LeaseStore {
+  return {
+    async get(cacheKey) {
+      const { rows } = await sql.query(
+        "select model, reasoning_effort, turns_remaining, expires_at from router_leases where cache_key = $1",
+        [cacheKey],
+      );
+      const row = rows[0];
+      if (row === undefined) return undefined;
+      return {
+        model: String(row.model),
+        reasoningEffort: row.reasoning_effort as RouterLease["reasoningEffort"],
+        turnsRemaining: Number(row.turns_remaining),
+        expiresAt: Number(row.expires_at),
+      };
+    },
+    async set(cacheKey, lease) {
+      await sql.query(
+        `insert into router_leases (cache_key, model, reasoning_effort, turns_remaining, expires_at)
+         values ($1, $2, $3, $4, $5)
+         on conflict (cache_key) do update set
+           model = excluded.model,
+           reasoning_effort = excluded.reasoning_effort,
+           turns_remaining = excluded.turns_remaining,
+           expires_at = excluded.expires_at`,
+        [cacheKey, lease.model, lease.reasoningEffort, lease.turnsRemaining, lease.expiresAt],
+      );
+    },
+    async delete(cacheKey) {
+      await sql.query("delete from router_leases where cache_key = $1", [cacheKey]);
+    },
+    async pruneExpired(nowMs) {
+      await sql.query("delete from router_leases where expires_at <= $1", [nowMs]);
+    },
+  };
+}
+
+// --- Demo: leases survive a router restart ----------------------------------
+
+function fakeRedis(): RedisLike {
+  const data = new Map<string, { value: string; expiresAt: number }>();
+  return {
+    async get(key) {
+      const entry = data.get(key);
+      if (entry === undefined || entry.expiresAt <= Date.now()) return null;
+      return entry.value;
+    },
+    async set(key, value, options) {
+      data.set(key, { value, expiresAt: Date.now() + options.PX });
+    },
+    async del(key) {
+      data.delete(key);
+    },
+  };
+}
+
+const policy: RoutingPolicy = ({ candidates }) => ({
+  model: candidates[0]!.id,
+  reason: "Fresh selection by the policy.",
+  leaseTurnsRemaining: 4,
+});
+
+const executor: RouterExecutor = {
+  execute: ({ decision }) => ({
+    type: "complete",
+    output: {
+      content: [{ type: "text", text: decision.reason }],
+      finishReason: "stop",
+      usage: { inputTokens: 4, outputTokens: 4 },
+    },
+  }),
+};
+
+const models = [{ id: "demo/model", executor: "demo", reasoningEfforts: ["off" as const] }];
+const sharedStore = redisLeaseStore(fakeRedis());
+const routerOptions = { models, policy, executors: { demo: executor }, leaseStore: sharedStore };
+
+const ask = (router: { fetch: (request: Request) => Promise<Response> }) =>
+  router.fetch(
+    new Request("https://example.test/v1/chat/completions", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        model: "dari/routing",
+        prompt_cache_key: "conversation-1",
+        messages: [{ role: "user", content: "hello" }],
+      }),
+    }),
+  );
+
+const first = createRouter(routerOptions);
+const turn1 = await (await ask(first)).json() as { dari_routing: { reason: string } };
+console.log("turn 1 (fresh process): ", turn1.dari_routing.reason);
+
+// "Restart": a brand-new router instance sharing only the external store.
+const second = createRouter(routerOptions);
+const turn2 = await (await ask(second)).json() as { dari_routing: { reason: string } };
+console.log("turn 2 (new process):   ", turn2.dari_routing.reason);

package/examples/managed/README.md

@@ -0,0 +1,50 @@
+# Managed Router Examples
+
+Runnable `router.yml` manifests for Dari's managed router path. TypeScript framework examples remain in the parent [`examples/`](../) directory.
+
+## Prerequisites
+
+Install the [Dari CLI](https://github.com/mupt-ai/dari-cli), sign in, and inspect the current model catalog:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/mupt-ai/dari-cli/main/install.sh | bash
+dari auth login
+dari router models
+```
+
+Your organization needs access to the providers and models used by an example. For BYOK examples, export the provider key named in that example's README.
+
+## Examples
+
+- [`slm-router/`](slm-router) — automatic selection with managed provider credentials.
+- [`byok-router/`](byok-router) — automatic selection with a provider key from your environment.
+- [`custom-rules-router/`](custom-rules-router) — natural-language rules with explicit model and reasoning-level constraints.
+- [`eval-router/`](eval-router) — automatic selection informed by an organization eval scorecard.
+
+## Create And Call A Router
+
+From an example directory:
+
+```bash
+cd examples/managed/slm-router
+dari router create ./router.yml
+dari router get <router_id>
+```
+
+Create a routing key and call the endpoint returned by `dari router get`:
+
+```bash
+dari api-keys create --name example-client --type routing
+export DARI_ROUTING_API_KEY="dari_..."
+
+curl https://routing.dari.dev/rtr_.../chat/completions \
+  -H "Authorization: Bearer $DARI_ROUTING_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"dari/routing","messages":[{"role":"user","content":"Explain prompt caching."}]}'
+```
+
+Run `dari router models` before editing a manifest. Model IDs and reasoning levels must match the current catalog.
+
+## Adding An Example
+
+Each example is a self-contained directory containing a `README.md` and `router.yml`. Keep one managed-router concept per example. Use `provider_key_envs` for BYOK examples, never commit provider credentials or organization-specific eval IDs, and validate changes against a test organization with `dari router create <example>/router.yml`.

package/examples/managed/byok-router/README.md

@@ -0,0 +1,13 @@
+# BYOK Router
+
+This managed router uses a Dari-managed OpenAI key and your own Fireworks key. The manifest reads the Fireworks credential from `FIREWORKS_API_KEY`; no key is stored in YAML.
+
+## Create
+
+```bash
+export FIREWORKS_API_KEY=fw_...
+dari auth login
+dari router create ./router.yml
+```
+
+The CLI sends the key only while creating or replacing the router configuration. Run `dari router models` first to confirm the selected models and provider support.

package/examples/managed/byok-router/router.yml

@@ -0,0 +1,13 @@
+name: Example BYOK Router
+enabled_models:
+  - openai/gpt-5.6-sol
+  - zai-org/GLM-5.2
+model_providers:
+  openai/gpt-5.6-sol: openai
+  zai-org/GLM-5.2: fireworks
+provider_key_sources:
+  openai: managed
+  fireworks: user
+provider_key_envs:
+  fireworks: FIREWORKS_API_KEY
+routing_strategy: slm

package/examples/managed/custom-rules-router/README.md

@@ -0,0 +1,12 @@
+# Custom Rules Router
+
+A managed **Describe Your Router** configuration. Dari's selector applies the natural-language `when` rules to each request, then uses the configured default when no rule matches.
+
+## Create
+
+```bash
+dari auth login
+dari router create ./router.yml
+```
+
+The manifest explicitly restricts the reasoning levels available for each model. `null` or an omitted `thinking_level` means the selector can choose an enabled level automatically; this example pins each rule for clarity.

package/examples/managed/custom-rules-router/router.yml

@@ -0,0 +1,24 @@
+name: Example Custom Rules Router
+enabled_models:
+  - openai/gpt-5.6-sol
+  - deepseek-ai/DeepSeek-V4-Flash-0731
+model_providers:
+  openai/gpt-5.6-sol: openai
+  deepseek-ai/DeepSeek-V4-Flash-0731: fireworks
+model_thinking_levels:
+  openai/gpt-5.6-sol: [low, medium, high]
+  deepseek-ai/DeepSeek-V4-Flash-0731: [off]
+provider_key_sources:
+  openai: managed
+  fireworks: managed
+routing_strategy: custom
+custom_config:
+  rules:
+    - when: planning, architecture, or difficult debugging
+      use: openai/gpt-5.6-sol
+      thinking_level: high
+    - when: short questions and straightforward implementation
+      use: deepseek-ai/DeepSeek-V4-Flash-0731
+      thinking_level: off
+  default: deepseek-ai/DeepSeek-V4-Flash-0731
+  default_thinking_level: off

package/examples/managed/eval-router/README.md

@@ -0,0 +1,18 @@
+# Eval Router
+
+An automatic managed router that imports an eval scorecard into its selection context.
+
+The eval ID is organization-specific, so replace `evl_your_scorecard` in `router.yml` with an ID returned by:
+
+```bash
+dari auth login
+dari eval list
+```
+
+Then create the router:
+
+```bash
+dari router create ./router.yml
+```
+
+The scorecard must contain scores for the enabled model and reasoning-level pairs you want the selector to consider. Keep organization-specific IDs and scores out of public example files.

package/examples/managed/eval-router/router.yml

@@ -0,0 +1,11 @@
+# Replace evl_your_scorecard with an eval ID from `dari eval list` before creating.
+name: Example Eval Router
+enabled_models:
+  - openai/gpt-5.6-sol
+  - anthropic/claude-sonnet-5
+provider_key_sources:
+  openai: managed
+  anthropic: managed
+routing_strategy: slm
+eval_ids:
+  - evl_your_scorecard

package/examples/managed/slm-router/README.md

@@ -0,0 +1,12 @@
+# SLM Router
+
+The smallest managed-router example. Dari's selector automatically chooses between the enabled models, using Dari-managed provider keys.
+
+## Create
+
+```bash
+dari auth login
+dari router create ./router.yml
+```
+
+Your organization must have managed access to the OpenAI and Anthropic providers. Run `dari router models` to confirm the model IDs are available before creating the router.

package/examples/managed/slm-router/router.yml

@@ -0,0 +1,8 @@
+name: Example SLM Router
+enabled_models:
+  - openai/gpt-5.6-sol
+  - anthropic/claude-sonnet-5
+provider_key_sources:
+  openai: managed
+  anthropic: managed
+routing_strategy: slm

package/examples/pi_runtime.ts

@@ -0,0 +1,55 @@
+// A real end-to-end router using the built-in Pi AI runtime.
+//
+// Run with:
+//   OPENAI_API_KEY=... bun run example:pi
+
+import {
+  createPiRuntime,
+  createRouter,
+  type RoutingPolicy,
+} from "../src/index.js";
+
+const apiKey = process.env.OPENAI_API_KEY;
+if (!apiKey) throw new Error("OPENAI_API_KEY is required.");
+
+const pi = await createPiRuntime({ apiKey });
+const models = [
+  pi.model("openai/gpt-5.4-mini"),
+  pi.model("openai/gpt-5.4"),
+];
+const policy: RoutingPolicy = ({ request, candidates }) => {
+  const promptLength = request.items.reduce((length, item) =>
+    item.type === "message"
+      ? length + item.content.reduce(
+          (total, part) => total + (part.type === "text" ? part.text.length : 0),
+          0,
+        )
+      : length,
+  0);
+  const preferred = promptLength > 500
+    ? "openai/gpt-5.4"
+    : "openai/gpt-5.4-mini";
+  return {
+    model: candidates.find((candidate) => candidate.id === preferred)?.id
+      ?? candidates[0]!.id,
+    reason: promptLength > 500
+      ? "Use the stronger model for the longer prompt."
+      : "Use the smaller model for the short prompt.",
+  };
+};
+const router = createRouter({ models, policy, executor: pi });
+
+const response = await router.fetch(new Request(
+  "http://router.local/v1/chat/completions",
+  {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      model: "my-router",
+      messages: [{ role: "user", content: "Explain LLM routing in one sentence." }],
+    }),
+  },
+));
+
+if (!response.ok) throw new Error(await response.text());
+console.log(await response.json());

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@mupt-ai/dari-router",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "End-to-end TypeScript framework for routing across LLMs with built-in Pi AI execution and pluggable policies and executors.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mupt-ai/dari-router-core.git"
+    "url": "git+https://github.com/mupt-ai/dari-router.git"
   },
   "homepage": "https://docs.dari.dev/framework/overview",
   "bugs": {
-    "url": "https://github.com/mupt-ai/dari-router-core/issues"
+    "url": "https://github.com/mupt-ai/dari-router/issues"
   },
   "keywords": [
     "llm",
@@ -34,17 +34,30 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./policy-engine": {
+      "types": "./dist/policy-engine.d.ts",
+      "default": "./dist/policy-engine.js"
+    },
+    "./eval-score-imputation": {
+      "types": "./dist/eval_score_imputation.d.ts",
+      "default": "./dist/eval_score_imputation.js"
+    },
+    "./protocols": {
+      "types": "./dist/protocols.d.ts",
+      "default": "./dist/protocols.js"
     }
   },
   "files": [
     "dist",
-    "src",
+    "examples",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "bun run typecheck && bun test && bun run build",
+    "test:package": "bash scripts/test-package.sh",
+    "prepublishOnly": "bun run typecheck && bun test && bun run test:package",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
     "example": "bun run examples/create_router.ts",
@@ -53,10 +66,16 @@
     "example:decision-pipeline": "bun run examples/basic_route.ts",
     "example:lease-stores": "bun run examples/lease_stores.ts"
   },
-  "dependencies": {
-    "@mupt-ai/pi-ai": "0.80.6-mupt.2"
+  "peerDependencies": {
+    "@mupt-ai/pi-ai": ">=0.80.6-mupt.2 <0.81.0"
+  },
+  "peerDependenciesMeta": {
+    "@mupt-ai/pi-ai": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@mupt-ai/pi-ai": "0.80.6-mupt.2",
     "@types/bun": "^1.3.4",
     "@types/node": "^24.10.2",
     "typescript": "^5.6.3"