# @x12i/ai-router-runtime

> Unified AI router runtime. Provider-agnostic entrypoint with OpenRouter protocol; OpenRouter plus local llama-cpp and transformersjs providers.

Latest version **1.2.0** (published 2026-07-10) · MIT license · 0 weekly downloads

## Install

```sh
npm install @x12i/ai-router-runtime
pnpm add @x12i/ai-router-runtime
yarn add @x12i/ai-router-runtime
bun add @x12i/ai-router-runtime
```

## Health

**Score 60/100 (C)** — status: active.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.0 |
| Published | 2026-07-10 |
| First published | 2026-07-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=20 |
| Dependencies | 1 |
| Unpacked size | 130.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | x12i |

## Links

- npm: https://www.npmjs.com/package/@x12i/ai-router-runtime
- npm.io page: https://npm.io/package/@x12i/ai-router-runtime

## Dependencies (1)

- [@x12i/openrouter-runtime](https://npm.io/package/@x12i/openrouter-runtime.md) ^1.1.0

## Recent versions

- 1.2.0 (latest) — 2026-07-10
- 1.1.0 — 2026-07-10
- 1.0.0 — 2026-07-10

## README

# @x12i/ai-router-runtime

Unified AI router runtime. **Import only from this package** — do not depend on `@x12i/openrouter-runtime` directly.

Call any configured provider through one protocol (the OpenRouter runtime request/response shape). Implemented providers today:

| Provider | `run()` | `executeStreamingChat()` | Function / server tools |
| --- | --- | --- | --- |
| `openrouter` | Yes | Yes | Yes |
| `llama-cpp` | Yes (text) | `PROVIDER_CAPABILITY_UNSUPPORTED` | Unsupported |
| `transformersjs` | Yes (text) | `PROVIDER_CAPABILITY_UNSUPPORTED` | Unsupported |

Other cloud provider ids (`openai`, `anthropic`, …) remain typed but throw `PROVIDER_NOT_IMPLEMENTED`.

## Install

```bash
npm install @x12i/ai-router-runtime
```

### Optional local engines

```bash
npm install node-llama-cpp              # provider: "llama-cpp"
npm install @huggingface/transformers  # provider: "transformersjs"
```

Missing optional deps throw a stable `AiRouterError` with code `MISSING_OPTIONAL_DEP`.

## Usage

```ts
import { createAiRouterRuntime } from "@x12i/ai-router-runtime";

const router = createAiRouterRuntime({
  provider: "openrouter",
  openrouter: {
    apiKey: process.env.OPENROUTER_API_KEY!,
    defaults: {
      serverTools: {
        datetime: { mode: "allowed", timezone: "Asia/Jerusalem" }
      }
    }
  }
});

const response = await router.run({
  model: "openai/gpt-5.2",
  messages: [{ role: "user", content: "What time is it?" }]
});

console.log(response.text);
```

### Local providers

```ts
const llama = createAiRouterRuntime({
  provider: "llama-cpp",
  llamaCpp: {
    modelPath: process.env.LLAMA_CPP_MODEL_PATH!, // or set env only
    contextSize: 4096,
    threads: 4
  }
});

await llama.run({ prompt: "Hello" });

const tf = createAiRouterRuntime({
  provider: "transformersjs",
  transformersjs: {
    modelId: process.env.TRANSFORMERS_JS_MODEL_ID!, // or set env only
    cacheDir: "/tmp/tf-cache"
  }
});

await tf.run({ prompt: "Hello" });
```

Env fallbacks: `LLAMA_CPP_MODEL_PATH`, `LLAMA_CPP_CONTEXT_SIZE`, `LLAMA_CPP_THREADS`, `TRANSFORMERS_JS_MODEL_ID`, `TRANSFORMERS_JS_CACHE_DIR`.

### Per-request provider

```ts
const router = createAiRouterRuntime({
  provider: "openrouter",
  openrouter: { apiKey: process.env.OPENROUTER_API_KEY! },
  llamaCpp: { modelPath: "/models/model.gguf" }
});

await router.run({ provider: "openrouter", prompt: "Hello" });
await router.run({ provider: "llama-cpp", prompt: "Hello" });

// Throws PROVIDER_NOT_IMPLEMENTED
await router.run({ provider: "openai", prompt: "Hello" });
```

## Public surface (import from this package)

### Values

| Export | Notes |
| --- | --- |
| `createAiRouterRuntime` | Consumer entrypoint (do **not** use `createOpenRouterRuntime`) |
| `AiRouterError` | Router-level errors |
| `OpenRouterHttpError` | Re-exported for `instanceof` |
| `RuntimeConfigError` | Re-exported for `instanceof` |
| `IMPLEMENTED_AI_PROVIDERS` / `isImplementedAiProvider` / `resolveProvider` | Provider helpers |

### Types (protocol)

`RuntimeRequest`, `RuntimeResponse`, `RuntimeMessage`, `RuntimeFunctionToolDefinition`, `RuntimeDefaults`, `RuntimeLogger`, `RuntimeStreamEvent`, `CompiledOpenRouterRequest`, `OpenRouterRuntimeOptions`

### Types (server tools / results)

`RuntimeServerToolsPolicy`, `WebSearchPolicy`, `WebFetchPolicy`, `DatetimePolicy`, `ImageGenerationPolicy`, `ApplyPatchPolicy`, `FusionPolicy`, `AdvisorPolicy`, `SubagentPolicy`, `ServerToolKey`, `ServerToolUsage`, `RuntimeCitation`, `RuntimeGeneratedImage`, `RuntimePatchProposal`, `RuntimeToolUsage`

### Router types

`AiRouterRuntime`, `AiRouterRuntimeOptions`, `AiRouterRequest`, `AiProviderId`, `LlamaCppProviderOptions`, `TransformersJsProviderOptions`

## Entrypoints

| Method | Purpose |
| --- | --- |
| `router.run(request)` | Non-streaming call |
| `router.executeStreamingChat(request)` | Streaming chat (OpenRouter only) |
| `router.compile(request)` | Compile OpenRouter wire payload without sending |

`run()` / `compile()` always produce non-streaming bodies (`stream: false`). Streaming is **only** through `executeStreamingChat()`.

## Logging

Pass `logger` on the router (or on `openrouter` options). Lifecycle events:

- `ai-router.request.started`
- `ai-router.request.succeeded` (provider, entrypoint, requestId, status)
- `ai-router.request.failed` (provider, entrypoint, requestId, errorCode, message)
- `ai-router.request.compiled` (debug)

OpenRouter package console logging still respects `OPENROUTER_RUNTIME_LOGS=true`.

---
_Source: https://npm.io/package/@x12i/ai-router-runtime · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._