@elizaos/plugin-lmstudio 2.0.11-beta.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 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,79 @@
+# @elizaos/plugin-lmstudio
+
+Connects [LM Studio](https://lmstudio.ai/) to elizaOS agents as a local inference backend via LM Studio's built-in OpenAI-compatible API.
+
+## What it does
+
+This plugin registers text-generation and embedding model handlers for every elizaOS model tier. When active, all agent inference calls (chat, action planning, response handling, embeddings) are routed to a locally-running LM Studio instance instead of a cloud provider.
+
+**Capabilities declared in `package.json`:** `text-large`, `text-small`, `embedding`.
+
+## Auto-enable behavior
+
+The plugin activates automatically when either condition is true:
+
+- `LMSTUDIO_BASE_URL` is set in the environment, **or**
+- `http://localhost:1234/v1/models` responds successfully at startup (the default LM Studio port).
+
+No manual plugin registration is needed in the common case.
+
+## Requirements
+
+- [LM Studio](https://lmstudio.ai/) installed and running with its **Local Server** enabled (default port 1234).
+- At least one model loaded in LM Studio.
+- Node.js 20+ or Bun 1.x. Browser build is included but LM Studio is a local desktop server — browser use requires a CORS-permissive reverse proxy.
+
+## Configuration
+
+All settings are optional. Use environment variables or character/agent settings (`runtime.getSetting`).
+
+| Variable | Default | Description |
+|---|---|---|
+| `LMSTUDIO_BASE_URL` | `http://localhost:1234/v1` | LM Studio server URL. The plugin appends `/v1` if omitted. |
+| `LMSTUDIO_API_KEY` | _(none)_ | Bearer token. Not needed unless LM Studio sits behind an auth proxy. |
+| `LMSTUDIO_SMALL_MODEL` | _(auto)_ | Model identifier for small/nano/medium tiers. Falls back to the first model returned by `/v1/models`. |
+| `LMSTUDIO_LARGE_MODEL` | _(auto)_ | Model identifier for large/mega/action-planner tiers. Same fallback. |
+| `LMSTUDIO_EMBEDDING_MODEL` | _(none)_ | Model identifier for embedding calls. **Required** for memory/recall features. Without it, embeddings return a zero vector. |
+| `LMSTUDIO_AUTO_DETECT` | `true` | Set to `0` or `false` to skip the init-time `/v1/models` probe. |
+
+### Example `.env`
+
+```
+LMSTUDIO_BASE_URL=http://localhost:1234/v1
+LMSTUDIO_SMALL_MODEL=llama-3.2-3b-instruct
+LMSTUDIO_LARGE_MODEL=llama-3.3-70b-instruct
+LMSTUDIO_EMBEDDING_MODEL=nomic-embed-text-v1.5
+```
+
+## Model tier mapping
+
+| elizaOS tier | Routed to |
+|---|---|
+| `TEXT_NANO`, `TEXT_SMALL`, `TEXT_MEDIUM` | `LMSTUDIO_SMALL_MODEL` (or first loaded model) |
+| `TEXT_LARGE`, `TEXT_MEGA`, `ACTION_PLANNER` | `LMSTUDIO_LARGE_MODEL` (or first loaded model) |
+| `RESPONSE_HANDLER` | `LMSTUDIO_SMALL_MODEL` |
+| `TEXT_EMBEDDING` | `LMSTUDIO_EMBEDDING_MODEL` |
+
+## Features
+
+- **Streaming**: enabled by default when `params.stream` is set; streaming is disabled automatically when structured output (JSON schema) is also requested.
+- **Structured output**: `responseSchema` is converted to `Output.object` via the Vercel AI SDK.
+- **Tool calls**: native tool definitions are normalized and forwarded to the model.
+- **Usage tracking**: emits `MODEL_USED` events with token counts (real or estimated) for each call.
+- **Graceful degradation**: init-time detection failures are logged but do not crash the agent.
+
+## Installation
+
+```bash
+# elizaOS picks it up automatically if LM Studio is running.
+# To add it explicitly:
+bun add @elizaos/plugin-lmstudio
+```
+
+Then reference it in your character file or plugin list:
+
+```json
+{
+  "plugins": ["@elizaos/plugin-lmstudio"]
+}
+```

package/auto-enable.ts

@@ -0,0 +1,24 @@
+// Auto-enable check for @elizaos/plugin-lmstudio.
+//
+// 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.
+//
+// LM Studio activates when either:
+//   1. The operator opted in explicitly via `LMSTUDIO_BASE_URL`, or
+//   2. The default `http://localhost:1234/v1/models` endpoint is reachable —
+//      handled at runtime by the plugin's `autoEnable.shouldEnable` predicate.
+//      This manifest just registers the env signal; the live probe is the
+//      plugin's responsibility so the autoenable engine can stay synchronous.
+
+import type { PluginAutoEnableContext } from "@elizaos/core";
+
+const ENV_KEYS = ["LMSTUDIO_BASE_URL"] as const;
+
+export function shouldEnable(ctx: PluginAutoEnableContext): boolean {
+  return ENV_KEYS.some((k) => {
+    const v = ctx.env[k];
+    return typeof v === "string" && v.trim() !== "";
+  });
+}

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "@elizaos/plugin-lmstudio",
+  "version": "2.0.11-beta.7",
+  "type": "module",
+  "main": "dist/node/index.node.js",
+  "module": "dist/node/index.node.js",
+  "types": "dist/node/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elizaOS/eliza.git",
+    "directory": "plugins/plugin-lmstudio"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/node/index.d.ts",
+      "browser": {
+        "types": "./dist/browser/index.d.ts",
+        "import": "./dist/browser/index.browser.js",
+        "default": "./dist/browser/index.browser.js"
+      },
+      "node": {
+        "types": "./dist/node/index.d.ts",
+        "import": "./dist/node/index.node.js",
+        "default": "./dist/node/index.node.js"
+      },
+      "bun": {
+        "types": "./dist/node/index.d.ts",
+        "default": "./dist/node/index.node.js"
+      },
+      "default": "./dist/node/index.node.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "auto-enable.ts"
+  ],
+  "elizaos": {
+    "plugin": {
+      "autoEnableModule": "./auto-enable.ts",
+      "capabilities": [
+        "text-large",
+        "text-small",
+        "embedding"
+      ]
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@ai-sdk/openai-compatible": "^2.0.51",
+    "ai": "^6.0.174"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@types/node": "^25.0.3",
+    "bun-types": "^1.3.12",
+    "typescript": "^6.0.3",
+    "vitest": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@elizaos/core": "2.0.11-beta.7"
+  },
+  "scripts": {
+    "dev": "bun run build.ts --watch",
+    "lint": "bunx @biomejs/biome check --write --unsafe .",
+    "clean": "rm -rf dist .turbo .turbo-tsconfig.json tsconfig.tsbuildinfo",
+    "format": "bunx @biomejs/biome format --write .",
+    "format:check": "bunx @biomejs/biome format .",
+    "typecheck": "tsc --noEmit --noCheck -p tsconfig.json",
+    "test": "vitest run --config ./vitest.config.ts __tests__/",
+    "test:unit": "vitest run --config ./vitest.config.ts __tests__/",
+    "lint:check": "bunx @biomejs/biome check .",
+    "build": "bun run build.ts",
+    "build:ts": "bun run build.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "LMSTUDIO_BASE_URL": {
+        "type": "string",
+        "description": "Base URL for the LM Studio OpenAI-compatible API (default http://localhost:1234/v1).",
+        "required": false,
+        "default": "http://localhost:1234/v1",
+        "sensitive": false
+      },
+      "LMSTUDIO_API_KEY": {
+        "type": "string",
+        "description": "Optional API key. LM Studio does not require one by default; set this only if you've put it behind an auth proxy.",
+        "required": false,
+        "sensitive": true
+      },
+      "LMSTUDIO_SMALL_MODEL": {
+        "type": "string",
+        "description": "Identifier of the small-sized LM Studio model to use for text generation.",
+        "required": false,
+        "sensitive": false
+      },
+      "LMSTUDIO_LARGE_MODEL": {
+        "type": "string",
+        "description": "Identifier of the large-sized LM Studio model to use for text generation.",
+        "required": false,
+        "sensitive": false
+      },
+      "LMSTUDIO_EMBEDDING_MODEL": {
+        "type": "string",
+        "description": "Identifier of the LM Studio model used to generate text embeddings, when embeddings are served by the same LM Studio instance.",
+        "required": false,
+        "sensitive": false
+      },
+      "LMSTUDIO_AUTO_DETECT": {
+        "type": "string",
+        "description": "When set to 1/true, the plugin probes http://localhost:1234/v1/models on init and logs a clear warning if LM Studio is not reachable.",
+        "required": false,
+        "default": "true",
+        "sensitive": false
+      }
+    }
+  },
+  "eliza": {
+    "platforms": [
+      "browser",
+      "node"
+    ],
+    "runtime": "both",
+    "platformDetails": {
+      "browser": "Browser-compatible build available via exports.browser",
+      "node": "Node.js build available via exports.node"
+    }
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}