@aigne/open-router 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0](https://github.com/AIGNE-io/aigne-framework/compare/open-router-v0.0.1...open-router-v0.1.0) (2025-05-23)
+
+
+### Features
+
+* **models:** publish model adapters as standalone packages ([#126](https://github.com/AIGNE-io/aigne-framework/issues/126)) ([588b8ae](https://github.com/AIGNE-io/aigne-framework/commit/588b8aea6abcee5fa87def1358bf51f84021c6ef))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/openai bumped to 0.1.0
+  * devDependencies
+    * @aigne/core bumped to 1.16.0
+    * @aigne/test-utils bumped to 0.3.0

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,133 @@
+# @aigne/open-router
+
+[![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-framework?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-framework)
+[![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-framework?style=flat-square)](https://github.com/AIGNE-io/aigne-framework/issues)
+[![codecov](https://codecov.io/gh/AIGNE-io/aigne-framework/graph/badge.svg?token=DO07834RQL)](https://codecov.io/gh/AIGNE-io/aigne-framework)
+[![NPM Version](https://img.shields.io/npm/v/@aigne/open-router)](https://www.npmjs.com/package/@aigne/open-router)
+[![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/open-router)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
+
+**English** | [中文](README.zh.md)
+
+AIGNE OpenRouter SDK for accessing multiple AI models through a unified API within the [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework).
+
+## Introduction
+
+`@aigne/open-router` provides a seamless integration between the AIGNE Framework and OpenRouter's unified API for accessing a wide variety of AI models. This package enables developers to easily leverage models from multiple providers (including OpenAI, Anthropic, Google, and more) through a single consistent interface, allowing for flexible model selection and fallback options.
+
+## Features
+
+* **OpenRouter API Integration**: Direct connection to OpenRouter's API services
+* **Multi-Provider Access**: Access to models from OpenAI, Anthropic, Claude, Google, and many other providers
+* **Unified Interface**: Consistent interface for all models regardless of their origin
+* **Model Fallbacks**: Easily configure fallback options between different models
+* **Chat Completions**: Support for chat completions API with all available models
+* **Streaming Responses**: Support for streaming responses for more responsive applications
+* **Type-Safe**: Comprehensive TypeScript typings for all APIs and models
+* **Consistent Interface**: Compatible with the AIGNE Framework's model interface
+* **Error Handling**: Robust error handling and retry mechanisms
+* **Full Configuration**: Extensive configuration options for fine-tuning behavior
+
+## Installation
+
+### Using npm
+
+```bash
+npm install @aigne/open-router @aigne/core
+```
+
+### Using yarn
+
+```bash
+yarn add @aigne/open-router @aigne/core
+```
+
+### Using pnpm
+
+```bash
+pnpm add @aigne/open-router @aigne/core
+```
+
+## Basic Usage
+
+```typescript file="test/open-router-chat-model.test.ts" region="example-openrouter-chat-model"
+import { OpenRouterChatModel } from "@aigne/open-router";
+
+const model = new OpenRouterChatModel({
+  // Provide API key directly or use environment variable OPEN_ROUTER_API_KEY
+  apiKey: "your-api-key", // Optional if set in env variables
+  // Specify model (defaults to 'openai/gpt-4o')
+  model: "anthropic/claude-3-opus",
+  modelOptions: {
+    temperature: 0.7,
+  },
+});
+
+const result = await model.invoke({
+  messages: [{ role: "user", content: "Which model are you using?" }],
+});
+
+console.log(result);
+/* Output:
+  {
+    text: "I'm powered by OpenRouter, using the Claude 3 Opus model from Anthropic.",
+    model: "anthropic/claude-3-opus",
+    usage: {
+      inputTokens: 5,
+      outputTokens: 14
+    }
+  }
+  */
+```
+
+## Using Multiple Models with Fallbacks
+
+```typescript
+const modelWithFallbacks = new OpenRouterChatModel({
+  apiKey: "your-api-key",
+  model: "openai/gpt-4o",
+  fallbackModels: ["anthropic/claude-3-opus", "google/gemini-1.5-pro"], // Fallback order
+  modelOptions: {
+    temperature: 0.7,
+  },
+});
+
+// Will try gpt-4o first, then claude-3-opus if that fails, then gemini-1.5-pro
+const fallbackResult = await modelWithFallbacks.invoke({
+  messages: [{ role: "user", content: "Which model are you using?" }],
+});
+```
+
+## Streaming Responses
+
+```typescript file="test/open-router-chat-model.test.ts" region="example-openrouter-chat-model-streaming"
+import { OpenRouterChatModel } from "@aigne/open-router";
+
+const model = new OpenRouterChatModel({
+  apiKey: "your-api-key",
+  model: "anthropic/claude-3-opus",
+});
+
+const stream = await model.invoke(
+  {
+    messages: [{ role: "user", content: "Which model are you using?" }],
+  },
+  undefined,
+  { streaming: true },
+);
+
+let fullText = "";
+const json = {};
+
+for await (const chunk of stream) {
+  const text = chunk.delta.text?.text;
+  if (text) fullText += text;
+  if (chunk.delta.json) Object.assign(json, chunk.delta.json);
+}
+
+console.log(fullText); // Output: "I'm powered by OpenRouter, using the Claude 3 Opus model from Anthropic."
+console.log(json); // { model: "anthropic/claude-3-opus", usage: { inputTokens: 5, outputTokens: 14 } }
+```
+
+## License
+
+Elastic-2.0

package/README.zh.md

@@ -0,0 +1,133 @@
+# @aigne/open-router
+
+[![GitHub star chart](https://img.shields.io/github/stars/AIGNE-io/aigne-framework?style=flat-square)](https://star-history.com/#AIGNE-io/aigne-framework)
+[![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-framework?style=flat-square)](https://github.com/AIGNE-io/aigne-framework/issues)
+[![codecov](https://codecov.io/gh/AIGNE-io/aigne-framework/graph/badge.svg?token=DO07834RQL)](https://codecov.io/gh/AIGNE-io/aigne-framework)
+[![NPM Version](https://img.shields.io/npm/v/@aigne/open-router)](https://www.npmjs.com/package/@aigne/open-router)
+[![Elastic-2.0 licensed](https://img.shields.io/npm/l/@aigne/open-router)](https://github.com/AIGNE-io/aigne-framework/blob/main/LICENSE.md)
+
+[English](README.md) | **中文**
+
+AIGNE OpenRouter SDK，用于在 [AIGNE 框架](https://github.com/AIGNE-io/aigne-framework) 中通过统一 API 访问多种 AI 模型。
+
+## 简介
+
+`@aigne/open-router` 提供了 AIGNE 框架与 OpenRouter 统一 API 之间的无缝集成，用于访问各种 AI 模型。该包使开发者能够通过单一一致的接口轻松使用来自多个提供商（包括 OpenAI、Anthropic、Google 等）的模型，允许灵活的模型选择和备选方案。
+
+## 特性
+
+* **OpenRouter API 集成**：直接连接到 OpenRouter 的 API 服务
+* **多提供商访问**：可访问来自 OpenAI、Anthropic、Claude、Google 等多家提供商的模型
+* **统一接口**：为所有模型提供一致的接口，无论其来源
+* **模型备选**：轻松配置不同模型之间的备选选项
+* **聊天完成**：支持所有可用模型的聊天完成 API
+* **流式响应**：支持流式响应，提供更高响应性的应用程序体验
+* **类型安全**：为所有 API 和模型提供全面的 TypeScript 类型定义
+* **一致接口**：兼容 AIGNE 框架的模型接口
+* **错误处理**：健壮的错误处理和重试机制
+* **完整配置**：丰富的配置选项用于微调行为
+
+## 安装
+
+### 使用 npm
+
+```bash
+npm install @aigne/open-router @aigne/core
+```
+
+### 使用 yarn
+
+```bash
+yarn add @aigne/open-router @aigne/core
+```
+
+### 使用 pnpm
+
+```bash
+pnpm add @aigne/open-router @aigne/core
+```
+
+## 基本用法
+
+```typescript file="test/open-router-chat-model.test.ts" region="example-openrouter-chat-model"
+import { OpenRouterChatModel } from "@aigne/open-router";
+
+const model = new OpenRouterChatModel({
+  // Provide API key directly or use environment variable OPEN_ROUTER_API_KEY
+  apiKey: "your-api-key", // Optional if set in env variables
+  // Specify model (defaults to 'openai/gpt-4o')
+  model: "anthropic/claude-3-opus",
+  modelOptions: {
+    temperature: 0.7,
+  },
+});
+
+const result = await model.invoke({
+  messages: [{ role: "user", content: "Which model are you using?" }],
+});
+
+console.log(result);
+/* Output:
+  {
+    text: "I'm powered by OpenRouter, using the Claude 3 Opus model from Anthropic.",
+    model: "anthropic/claude-3-opus",
+    usage: {
+      inputTokens: 5,
+      outputTokens: 14
+    }
+  }
+  */
+```
+
+## 使用多模型备选
+
+```typescript
+const modelWithFallbacks = new OpenRouterChatModel({
+  apiKey: "your-api-key",
+  model: "openai/gpt-4o",
+  fallbackModels: ["anthropic/claude-3-opus", "google/gemini-1.5-pro"], // 备选顺序
+  modelOptions: {
+    temperature: 0.7,
+  },
+});
+
+// 将首先尝试 gpt-4o，如果失败则尝试 claude-3-opus，如果再失败则尝试 gemini-1.5-pro
+const fallbackResult = await modelWithFallbacks.invoke({
+  messages: [{ role: "user", content: "Which model are you using?" }],
+});
+```
+
+## 流式响应
+
+```typescript file="test/open-router-chat-model.test.ts" region="example-openrouter-chat-model-streaming"
+import { OpenRouterChatModel } from "@aigne/open-router";
+
+const model = new OpenRouterChatModel({
+  apiKey: "your-api-key",
+  model: "anthropic/claude-3-opus",
+});
+
+const stream = await model.invoke(
+  {
+    messages: [{ role: "user", content: "Which model are you using?" }],
+  },
+  undefined,
+  { streaming: true },
+);
+
+let fullText = "";
+const json = {};
+
+for await (const chunk of stream) {
+  const text = chunk.delta.text?.text;
+  if (text) fullText += text;
+  if (chunk.delta.json) Object.assign(json, chunk.delta.json);
+}
+
+console.log(fullText); // Output: "I'm powered by OpenRouter, using the Claude 3 Opus model from Anthropic."
+console.log(json); // { model: "anthropic/claude-3-opus", usage: { inputTokens: 5, outputTokens: 14 } }
+```
+
+## 许可证
+
+Elastic-2.0

package/lib/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from "./open-router-chat-model.js";

package/lib/cjs/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./open-router-chat-model.js"), exports);

package/lib/cjs/open-router-chat-model.d.ts

@@ -0,0 +1,22 @@
+import { OpenAIChatModel, type OpenAIChatModelOptions } from "@aigne/openai";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
+export declare class OpenRouterChatModel extends OpenAIChatModel {
+    constructor(options?: OpenAIChatModelOptions);
+    protected apiKeyEnvName: string;
+    protected supportsParallelToolCalls: boolean;
+}

package/lib/cjs/open-router-chat-model.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenRouterChatModel = void 0;
+const openai_1 = require("@aigne/openai");
+const OPEN_ROUTER_DEFAULT_CHAT_MODEL = "openai/gpt-4o";
+const OPEN_ROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
+class OpenRouterChatModel extends openai_1.OpenAIChatModel {
+    constructor(options) {
+        super({
+            ...options,
+            model: options?.model || OPEN_ROUTER_DEFAULT_CHAT_MODEL,
+            baseURL: options?.baseURL || OPEN_ROUTER_BASE_URL,
+        });
+    }
+    apiKeyEnvName = "OPEN_ROUTER_API_KEY";
+    supportsParallelToolCalls = false;
+}
+exports.OpenRouterChatModel = OpenRouterChatModel;

package/lib/cjs/package.json

@@ -0,0 +1 @@
+{"type": "commonjs"}

package/lib/dts/index.d.ts

@@ -0,0 +1 @@
+export * from "./open-router-chat-model.js";

package/lib/dts/open-router-chat-model.d.ts

@@ -0,0 +1,22 @@
+import { OpenAIChatModel, type OpenAIChatModelOptions } from "@aigne/openai";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
+export declare class OpenRouterChatModel extends OpenAIChatModel {
+    constructor(options?: OpenAIChatModelOptions);
+    protected apiKeyEnvName: string;
+    protected supportsParallelToolCalls: boolean;
+}

package/lib/esm/index.d.ts

@@ -0,0 +1 @@
+export * from "./open-router-chat-model.js";

package/lib/esm/index.js

@@ -0,0 +1 @@
+export * from "./open-router-chat-model.js";

package/lib/esm/open-router-chat-model.d.ts

@@ -0,0 +1,22 @@
+import { OpenAIChatModel, type OpenAIChatModelOptions } from "@aigne/openai";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
+export declare class OpenRouterChatModel extends OpenAIChatModel {
+    constructor(options?: OpenAIChatModelOptions);
+    protected apiKeyEnvName: string;
+    protected supportsParallelToolCalls: boolean;
+}

package/lib/esm/open-router-chat-model.js

@@ -0,0 +1,30 @@
+import { OpenAIChatModel } from "@aigne/openai";
+const OPEN_ROUTER_DEFAULT_CHAT_MODEL = "openai/gpt-4o";
+const OPEN_ROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+/**
+ * Implementation of the ChatModel interface for OpenRouter service
+ *
+ * OpenRouter provides access to a variety of large language models through a unified API.
+ * This implementation uses the OpenAI-compatible interface to connect to OpenRouter's service.
+ *
+ * Default model: 'openai/gpt-4o'
+ *
+ * @example
+ * Here's how to create and use an OpenRouter chat model:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model}
+ *
+ * @example
+ * Here's an example with streaming response:
+ * {@includeCode ../test/open-router-chat-model.test.ts#example-openrouter-chat-model-streaming}
+ */
+export class OpenRouterChatModel extends OpenAIChatModel {
+    constructor(options) {
+        super({
+            ...options,
+            model: options?.model || OPEN_ROUTER_DEFAULT_CHAT_MODEL,
+            baseURL: options?.baseURL || OPEN_ROUTER_BASE_URL,
+        });
+    }
+    apiKeyEnvName = "OPEN_ROUTER_API_KEY";
+    supportsParallelToolCalls = false;
+}

package/lib/esm/package.json

@@ -0,0 +1 @@
+{"type": "module"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@aigne/open-router",
+  "version": "0.1.0",
+  "description": "AIGNE OpenRouter SDK for accessing multiple AI models through a unified API",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
+  "homepage": "https://github.com/AIGNE-io/aigne-framework",
+  "license": "Elastic-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AIGNE-io/aigne-framework"
+  },
+  "files": [
+    "lib/cjs",
+    "lib/dts",
+    "lib/esm",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "./lib/cjs/index.js",
+  "module": "./lib/esm/index.js",
+  "types": "./lib/dts/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js",
+      "types": "./lib/dts/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@aigne/openai": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.12",
+    "@types/node": "^22.15.15",
+    "npm-run-all": "^4.1.5",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3",
+    "@aigne/core": "^1.16.0",
+    "@aigne/test-utils": "^0.3.0"
+  },
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsc --build scripts/tsconfig.build.json",
+    "clean": "rimraf lib test/coverage",
+    "test": "bun test",
+    "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
+    "postbuild": "echo '{\"type\": \"module\"}' > lib/esm/package.json && echo '{\"type\": \"commonjs\"}' > lib/cjs/package.json"
+  }
+}