@elizaos/plugin-openrouter 2.0.0-alpha.9 → 2.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shaw Walters and elizaOS Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @elizaos/plugin-openrouter
+
+This plugin provides integration with various models available through the OpenRouter API via the ElizaOS platform.
+
+## Usage
+
+Add the plugin to your character configuration:
+
+```json
+"plugins": ["@elizaos/plugin-openrouter"]
+```
+
+## Configuration
+
+The plugin requires the OpenRouter API key and can be configured via environment variables or character settings.
+
+**Character Settings Example:**
+
+```json
+"settings": {
+  "OPENROUTER_API_KEY": "your_openrouter_api_key",
+  "OPENROUTER_BASE_URL": "https://openrouter.ai/api/v1", // Optional: Default is OpenRouter endpoint
+  "OPENROUTER_SMALL_MODEL": "google/gemini-flash", // Optional: Overrides default small model
+  "OPENROUTER_LARGE_MODEL": "google/gemini-pro", // Optional: Overrides default large model
+  "OPENROUTER_IMAGE_MODEL": "x-ai/grok-2-vision-1212", // Optional: Overrides default image model
+  "OPENROUTER_IMAGE_GENERATION_MODEL": "google/gemini-2.5-flash-image-preview", // Optional: Overrides default image generation model
+  "OPENROUTER_EMBEDDING_MODEL": "openai/text-embedding-3-small", // Optional: Overrides default embedding model
+  "OPENROUTER_EMBEDDING_DIMENSIONS": "1536", // Optional: Sets embedding vector dimensions (256, 384, 512, 768, 1024, 1536, 2048, 3072)
+  "OPENROUTER_BROWSER_BASE_URL": "https://your-proxy.example.com/openrouter"
+  // Fallbacks if specific OPENROUTER models are not set
+  "SMALL_MODEL": "google/gemini-flash",
+  "LARGE_MODEL": "google/gemini-pro",
+  "IMAGE_MODEL": "x-ai/grok-2-vision-1212",
+  "IMAGE_GENERATION_MODEL": "google/gemini-2.5-flash-image-preview",
+  "EMBEDDING_MODEL": "openai/text-embedding-3-small",
+  "EMBEDDING_DIMENSIONS": "1536"
+}
+```
+
+**`.env` File Example:**
+
+```
+OPENROUTER_API_KEY=your_openrouter_api_key
+# Optional overrides:
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_SMALL_MODEL=google/gemini-flash
+OPENROUTER_LARGE_MODEL=google/gemini-pro
+OPENROUTER_IMAGE_MODEL=x-ai/grok-2-vision-1212
+OPENROUTER_IMAGE_GENERATION_MODEL=google/gemini-2.5-flash-image-preview
+OPENROUTER_EMBEDDING_MODEL=openai/text-embedding-3-small
+OPENROUTER_EMBEDDING_DIMENSIONS=1536
+# Browser proxy (frontend builds only)
+OPENROUTER_BROWSER_BASE_URL=https://your-proxy.example.com/openrouter
+# Fallbacks if specific OPENROUTER models are not set
+SMALL_MODEL=google/gemini-flash
+LARGE_MODEL=google/gemini-pro
+IMAGE_MODEL=x-ai/grok-2-vision-1212
+IMAGE_GENERATION_MODEL=google/gemini-2.5-flash-image-preview
+EMBEDDING_MODEL=openai/text-embedding-3-small
+EMBEDDING_DIMENSIONS=1536
+```
+
+### Configuration Options
+
+- `OPENROUTER_API_KEY` (required): Your OpenRouter API key.
+- `OPENROUTER_BASE_URL`: Custom API endpoint (default: https://openrouter.ai/api/v1).
+- `OPENROUTER_BROWSER_BASE_URL`: Browser-only base URL to a proxy endpoint that forwards requests to OpenRouter without exposing keys.
+
+### Browser mode and proxying
+
+When bundled for the browser, this plugin avoids sending Authorization headers. Set `OPENROUTER_BROWSER_BASE_URL` to a server-side proxy you control that injects the OpenRouter API key. This prevents exposing secrets in frontend builds.
+
+Example minimal proxy (Express):
+
+```ts
+import express from "express";
+import fetch from "node-fetch";
+
+const app = express();
+app.use(express.json());
+
+app.post("/openrouter/*", async (req, res) => {
+  const url = `https://openrouter.ai/api/v1/${req.params[0]}`;
+  const r = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(req.body),
+  });
+  res
+    .status(r.status)
+    .set(Object.fromEntries(r.headers))
+    .send(await r.text());
+});
+
+app.listen(3000);
+```
+
+- `OPENROUTER_SMALL_MODEL`: Specific model to use for `TEXT_SMALL`. Overrides `SMALL_MODEL` if set.
+- `OPENROUTER_LARGE_MODEL`: Specific model to use for `TEXT_LARGE`. Overrides `LARGE_MODEL` if set.
+- `OPENROUTER_IMAGE_MODEL`: Specific model to use for `IMAGE_DESCRIPTION`. Overrides `IMAGE_MODEL` if set.
+- `OPENROUTER_IMAGE_GENERATION_MODEL`: Specific model to use for `IMAGE` generation. Overrides `IMAGE_GENERATION_MODEL` if set.
+- `OPENROUTER_EMBEDDING_MODEL`: Specific model to use for `TEXT_EMBEDDING`. Overrides `EMBEDDING_MODEL` if set.
+- `OPENROUTER_EMBEDDING_DIMENSIONS`: Number of dimensions for embedding vectors. Supported values: 256, 384, 512, 768, 1024, 1536, 2048, 3072. Defaults to 1536.
+- `OPENROUTER_AUTO_CLEANUP_IMAGES`: Whether to automatically delete generated images after 30 seconds (default: "false"). Set to "true" to enable auto-cleanup.
+- `SMALL_MODEL`: Fallback model for small tasks (default: "google/gemini-2.0-flash-001"). Used if `OPENROUTER_SMALL_MODEL` is not set.
+- `LARGE_MODEL`: Fallback model for large tasks (default: "openai/gpt-5.1-nano"). Used if `OPENROUTER_LARGE_MODEL` is not set.
+- `IMAGE_MODEL`: Fallback model for image analysis (default: "x-ai/grok-2-vision-1212"). Used if `OPENROUTER_IMAGE_MODEL` is not set.
+- `IMAGE_GENERATION_MODEL`: Fallback model for image generation (default: "google/gemini-2.5-flash-image-preview"). Used if `OPENROUTER_IMAGE_GENERATION_MODEL` is not set.
+- `EMBEDDING_MODEL`: Fallback model for text embeddings (default: "openai/text-embedding-3-small"). Used if `OPENROUTER_EMBEDDING_MODEL` is not set.
+- `EMBEDDING_DIMENSIONS`: Fallback dimension setting for embeddings (default: "1536"). Used if `OPENROUTER_EMBEDDING_DIMENSIONS` is not set.
+
+## Provided Models
+
+The plugin currently provides these model types:
+
+- `TEXT_SMALL`: Optimized for fast, cost-effective text generation using the configured small model. Supports `tools`, `toolChoice`, and `responseSchema` for structured output via native tool calling.
+- `TEXT_LARGE`: For more complex text generation tasks requiring larger models, using the configured large model. Supports `tools`, `toolChoice`, and `responseSchema` for structured output via native tool calling.
+- `IMAGE_DESCRIPTION`: Analyzes images and provides descriptive text and titles, using the configured image model.
+- `IMAGE`: Generates images from text prompts using the configured image generation model (e.g., Gemini 2.5 Flash Image Preview).
+- `TEXT_EMBEDDING`: Generates vector embeddings for text input, supporting configurable dimensions from 256 to 3072, using the configured embedding model.
+
+_Note: Audio Transcription is not currently implemented in this specific OpenRouter plugin._

package/auto-enable.ts

@@ -0,0 +1,17 @@
+// Auto-enable check for @elizaos/plugin-openrouter.
+//
+// Plugin manifest entry-point — referenced by package.json's
+// `elizaos.plugin.autoEnableModule`. Keep this module light: env reads only,
+// no service init, no transitive imports of the full plugin runtime. The
+// auto-enable engine loads dozens of these per boot.
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+const ENV_KEYS = ["OPENROUTER_API_KEY"] as const;
+
+/** Enable when an OpenRouter API key is present. */
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  return ENV_KEYS.some((k) => {
+    const v = ctx.env[k];
+    return typeof v === "string" && v.trim() !== "";
+  });
+}