@elizaos/plugin-documents 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,67 @@
+# @elizaos/plugin-documents
+
+Adds a document management REST API to an elizaOS agent.
+
+## What it does
+
+This plugin registers HTTP routes on the agent server that let clients (the dashboard UI, other agents, and external tools) upload, retrieve, search, edit, and delete documents from the agent's document store.
+
+Documents are stored as memories in the runtime's `documents` table and chunked into fragments in the `document_fragments` table for vector/semantic search. The plugin handles:
+
+- Uploading text files, markdown, JSON, CSV, images, and other content types
+- Fetching and ingesting content from arbitrary URLs or YouTube transcripts
+- Bulk uploading up to 100 documents in a single request
+- Semantic, keyword, and hybrid search across document fragments
+- Listing fragments for a document (ordered by position)
+- Editing text-backed documents (replaces content and re-fragments)
+- Deleting documents and their fragments
+- Access control: `global`, `owner-private`, `user-private`, and `agent-private` document scopes
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET    | `/api/documents` | List documents; supports `scope`, `addedBy`, `tags`, `timeRangeStart/End`, `q` query, `limit`, `offset` |
+| GET    | `/api/documents/stats` | Document and fragment counts |
+| GET    | `/api/documents/search` | Semantic/keyword/hybrid search; params: `q`, `threshold`, `limit`, `searchMode` |
+| GET    | `/api/documents/:id` | Fetch a document with full content |
+| GET    | `/api/documents/:id/fragments` | List all text fragments ordered by position |
+| POST   | `/api/documents` | Upload a document: `{ content, filename, contentType?, metadata?, scope?, ... }` |
+| POST   | `/api/documents/bulk` | Upload up to 100 documents at once |
+| POST   | `/api/documents/url` | Ingest a URL or YouTube transcript: `{ url, scope?, metadata? }` |
+| PATCH  | `/api/documents/:id` | Update document text (only for non-bundled, non-character, text-backed documents) |
+| DELETE | `/api/documents/:id` | Delete document and all its fragments |
+
+## Document scopes
+
+| Scope | Who can read/write |
+|-------|--------------------|
+| `global` | Anyone; only OWNER/RUNTIME can write |
+| `owner-private` | OWNER and RUNTIME only |
+| `user-private` | Scoped to a specific user entity |
+| `agent-private` | OWNER, AGENT, and RUNTIME |
+
+The caller's role is resolved from the `x-eliza-entity-id` / `x-eliza-actor-entity-id` request headers and the `ELIZA_ADMIN_ENTITY_ID` runtime setting.
+
+## Configuration
+
+No additional environment variables are required beyond those needed by the document storage service (`@elizaos/agent`). The plugin uses `ELIZA_ADMIN_ENTITY_ID` (read from the agent runtime settings) to identify the owner actor for access control decisions.
+
+## Enabling the plugin
+
+Add `@elizaos/plugin-documents` to the agent's plugin list in the character configuration or register it programmatically:
+
+```typescript
+import { documentsPlugin } from "@elizaos/plugin-documents";
+
+const character = {
+  plugins: ["@elizaos/plugin-documents"],
+  // ...
+};
+```
+
+## Limitations
+
+- Image uploads are converted to text descriptions when `includeImageDescriptions: true` is set in metadata (requires a vision model). Without a generated description, the stored text explicitly records that text extraction or image description was unavailable.
+- Bundled documents (seeded by the runtime) and character documents (from character source files) cannot be edited or deleted through this API.
+- Bulk upload is capped at 100 documents per request; individual upload bodies are capped at 32 MB.

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@elizaos/plugin-documents",
+  "version": "2.0.11-beta.7",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "eliza-source": {
+        "types": "./src/index.ts",
+        "import": "./src/index.ts",
+        "default": "./src/index.ts"
+      },
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js",
+      "default": "./dist/plugin.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "eliza-source": {
+        "types": "./src/*.ts",
+        "import": "./src/*.ts",
+        "default": "./src/*.ts"
+      },
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
+  },
+  "dependencies": {
+    "@elizaos/agent": "2.0.11-beta.7",
+    "@elizaos/app-core": "2.0.11-beta.7",
+    "@elizaos/core": "2.0.11-beta.7",
+    "@elizaos/shared": "2.0.11-beta.7",
+    "@elizaos/ui": "2.0.11-beta.7",
+    "lucide-react": "^1.0.0"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {}
+  },
+  "elizaos": {
+    "app": {
+      "heroImage": "assets/hero.png"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "bun run build:js && bun run build:views && bun run build:types",
+    "clean": "rm -rf dist",
+    "build:js": "tsup --config ../tsup.plugin-packages.shared.ts",
+    "build:views": "bunx --bun vite build --config vite.config.views.ts",
+    "build:types": "tsc --noCheck -p tsconfig.build.json",
+    "test": "vitest run --config ./vitest.config.ts",
+    "test:e2e:manual": "vitest run --config ../../vitest.config.ts test/*.live.e2e.test.ts"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^25.0.6",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.0"
+  },
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
+}