@elizaos/plugin-knowledge 1.0.1 → 1.0.3

package/README.md

@@ -197,9 +197,194 @@ The document processing flow follows these steps regardless of database type:
 - Rate limiting to respect provider limitations
 - Support for multiple LLM providers
 
+## API Routes
+
+The Knowledge plugin provides a comprehensive REST API for managing knowledge documents. All routes are prefixed with `/api/agents/{agentId}/plugins/knowledge`.
+
+### Knowledge Panel UI
+
+#### GET `/display`
+Access the web-based knowledge management interface.
+
+- **URL**: `/api/agents/{agentId}/plugins/knowledge/display`
+- **Method**: GET
+- **Public**: Yes
+- **Description**: Serves the HTML frontend for managing knowledge documents
+- **Response**: HTML page with embedded configuration
+
+### Document Management
+
+#### POST `/documents` - Upload Knowledge
+Upload files or URLs to create knowledge documents.
+
+**File Upload:**
+```bash
+curl -X POST \
+  "/api/agents/{agentId}/plugins/knowledge/documents" \
+  -H "Content-Type: multipart/form-data" \
+  -F "files=@document.pdf" \
+  -F "documentId=optional-custom-id" \
+  -F "worldId=optional-world-id"
+```
+
+**URL Upload:**
+```bash
+curl -X POST \
+  "/api/agents/{agentId}/plugins/knowledge/documents" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "fileUrls": ["https://example.com/document.pdf"],
+    "worldId": "optional-world-id"
+  }'
+```
+
+**Request Parameters:**
+- `files`: File(s) to upload (multipart)
+- `fileUrl` or `fileUrls`: URL(s) to fetch content from (JSON)
+- `documentId` or `documentIds`: Optional custom document IDs
+- `worldId`: Optional world ID for scoping
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "id": "document-uuid",
+      "filename": "document.pdf",
+      "status": "success",
+      "fragmentCount": 15,
+      "createdAt": 1703123456789
+    }
+  ]
+}
+```
+
+**Supported File Types:**
+- **Documents**: PDF, DOC, DOCX
+- **Text**: TXT, MD, HTML, JSON, XML, YAML
+- **Code**: JS, TS, PY, JAVA, C, CPP, CS, PHP, RB, GO, RS, and more
+- **Config**: INI, CFG, CONF, ENV
+- **Data**: CSV, TSV, LOG
+
+#### GET `/documents` - List Documents
+Retrieve all knowledge documents.
+
+```bash
+curl "/api/agents/{agentId}/plugins/knowledge/documents?limit=20&before=1703123456789&includeEmbedding=false"
+```
+
+**Query Parameters:**
+- `limit`: Number of documents to return (default: 20)
+- `before`: Timestamp for pagination (default: current time)
+- `includeEmbedding`: Include embedding data (default: false)
+- `fileUrls`: Filter by specific URLs (comma-separated)
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "memories": [
+      {
+        "id": "document-uuid",
+        "content": { "text": "..." },
+        "metadata": {
+          "type": "document",
+          "title": "Document Title",
+          "filename": "document.pdf",
+          "fileType": "application/pdf",
+          "fileSize": 1024,
+          "timestamp": 1703123456789,
+          "source": "upload"
+        },
+        "createdAt": 1703123456789
+      }
+    ],
+    "urlFiltered": false,
+    "totalFound": 1,
+    "totalRequested": 0
+  }
+}
+```
+
+#### GET `/documents/:knowledgeId` - Get Specific Document
+Retrieve a specific knowledge document by ID.
+
+```bash
+curl "/api/agents/{agentId}/plugins/knowledge/documents/{documentId}"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "document": {
+      "id": "document-uuid",
+      "content": { "text": "..." },
+      "metadata": { "..." },
+      "createdAt": 1703123456789
+    }
+  }
+}
+```
+
+#### DELETE `/documents/:knowledgeId` - Delete Document
+Delete a knowledge document and all its fragments.
+
+```bash
+curl -X DELETE "/api/agents/{agentId}/plugins/knowledge/documents/{documentId}"
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": null
+}
+```
+
+### Knowledge Fragments
+
+#### GET `/knowledges` - List Knowledge Chunks
+Retrieve knowledge fragments/chunks for detailed analysis or graph view.
+
+```bash
+curl "/api/agents/{agentId}/plugins/knowledge/knowledges?limit=100&documentId=optional-filter"
+```
+
+**Query Parameters:**
+- `limit`: Number of chunks to return (default: 100)
+- `before`: Timestamp for pagination (default: current time)
+- `documentId`: Filter chunks by parent document ID
+
+**Response:**
+```json
+{
+  "success": true,
+  "data": {
+    "chunks": [
+      {
+        "id": "fragment-uuid",
+        "content": { "text": "chunk content..." },
+        "metadata": {
+          "type": "fragment",
+          "documentId": "parent-document-uuid",
+          "position": 0,
+          "timestamp": 1703123456789
+        },
+        "embedding": [0.1, 0.2, ...], // If included
+        "createdAt": 1703123456789
+      }
+    ]
+  }
+}
+```
+
 ## Usage
 
-### Basic Usage
+### Programmatic Usage
 
 ```typescript
 import { KnowledgeService } from '@elizaos/plugin-knowledge';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elizaos/plugin-knowledge",
   "description": "Plugin for Knowledge",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -74,5 +74,160 @@
   "resolutions": {
     "zod": "3.25.23"
   },
-  "gitHead": "b165ad83e5f7a21bc1edbd83374ca087e3cd6b33"
+  "gitHead": "b165ad83e5f7a21bc1edbd83374ca087e3cd6b33",
+  "agentConfig": {
+    "pluginType": "elizaos:plugin:1.0.0",
+    "pluginParameters": {
+      "CTX_KNOWLEDGE_ENABLED": {
+        "type": "boolean",
+        "description": "Enables or disables contextual knowledge functionality; when set to 'true' additional text-generation settings are validated.",
+        "required": false,
+        "default": "false",
+        "sensitive": false
+      },
+      "EMBEDDING_PROVIDER": {
+        "type": "string",
+        "description": "Specifies which provider to use for generating embeddings (e.g., openai, google). If omitted the code assumes 'openai' through plugin-openai.",
+        "required": false,
+        "default": "openai",
+        "sensitive": false
+      },
+      "OPENAI_API_KEY": {
+        "type": "string",
+        "description": "API key used to authenticate requests to OpenAI services for embeddings or text generation.",
+        "required": false,
+        "sensitive": true
+      },
+      "OPENAI_EMBEDDING_MODEL": {
+        "type": "string",
+        "description": "Name of the OpenAI embedding model; also used as a fallback for TEXT_EMBEDDING_MODEL when EMBEDDING_PROVIDER defaults to openai.",
+        "required": false,
+        "sensitive": false
+      },
+      "TEXT_EMBEDDING_MODEL": {
+        "type": "string",
+        "description": "Embedding model name to use with the configured EMBEDDING_PROVIDER.",
+        "required": false,
+        "default": "text-embedding-3-small",
+        "sensitive": false
+      },
+      "EMBEDDING_DIMENSION": {
+        "type": "number",
+        "description": "Custom embedding dimension size.",
+        "required": false,
+        "default": 1536,
+        "sensitive": false
+      },
+      "OPENAI_EMBEDDING_DIMENSIONS": {
+        "type": "number",
+        "description": "Alternative variable to supply embedding dimension when using OpenAI.",
+        "required": false,
+        "default": 1536,
+        "sensitive": false
+      },
+      "TEXT_PROVIDER": {
+        "type": "string",
+        "description": "Provider to use for text generation when contextual knowledge is enabled (e.g., openai, anthropic, openrouter, google).",
+        "required": false,
+        "sensitive": false
+      },
+      "ANTHROPIC_API_KEY": {
+        "type": "string",
+        "description": "API key for Anthropic text generation models.",
+        "required": false,
+        "sensitive": true
+      },
+      "OPENROUTER_API_KEY": {
+        "type": "string",
+        "description": "API key for OpenRouter when using it as a text provider.",
+        "required": false,
+        "sensitive": true
+      },
+      "GOOGLE_API_KEY": {
+        "type": "string",
+        "description": "API key for Google AI services used for embeddings or text generation.",
+        "required": false,
+        "sensitive": true
+      },
+      "OPENAI_BASE_URL": {
+        "type": "string",
+        "description": "Custom base URL for routing OpenAI API requests (useful for proxies).",
+        "required": false,
+        "sensitive": false
+      },
+      "ANTHROPIC_BASE_URL": {
+        "type": "string",
+        "description": "Custom base URL for Anthropic API requests.",
+        "required": false,
+        "sensitive": false
+      },
+      "OPENROUTER_BASE_URL": {
+        "type": "string",
+        "description": "Custom base URL for OpenRouter API requests.",
+        "required": false,
+        "sensitive": false
+      },
+      "GOOGLE_BASE_URL": {
+        "type": "string",
+        "description": "Custom base URL for Google AI API requests.",
+        "required": false,
+        "sensitive": false
+      },
+      "TEXT_MODEL": {
+        "type": "string",
+        "description": "The specific text generation model to use with the selected TEXT_PROVIDER.",
+        "required": false,
+        "sensitive": false
+      },
+      "MAX_INPUT_TOKENS": {
+        "type": "number",
+        "description": "Maximum number of input tokens permitted per request.",
+        "required": false,
+        "default": 4000,
+        "sensitive": false
+      },
+      "MAX_OUTPUT_TOKENS": {
+        "type": "number",
+        "description": "Maximum number of output tokens that can be generated.",
+        "required": false,
+        "default": 4096,
+        "sensitive": false
+      },
+      "MAX_CONCURRENT_REQUESTS": {
+        "type": "number",
+        "description": "Upper bound on concurrent API requests for rate limiting.",
+        "required": false,
+        "default": 30,
+        "sensitive": false
+      },
+      "REQUESTS_PER_MINUTE": {
+        "type": "number",
+        "description": "Maximum number of API requests allowed per minute.",
+        "required": false,
+        "default": 60,
+        "sensitive": false
+      },
+      "TOKENS_PER_MINUTE": {
+        "type": "number",
+        "description": "Maximum number of tokens that can be processed per minute.",
+        "required": false,
+        "default": 150000,
+        "sensitive": false
+      },
+      "KNOWLEDGE_PATH": {
+        "type": "string",
+        "description": "Filesystem path where the knowledge loader searches for documents. Overrides the default ./docs directory.",
+        "required": false,
+        "default": "./docs",
+        "sensitive": false
+      },
+      "LOAD_DOCS_ON_STARTUP": {
+        "type": "boolean",
+        "description": "Controls whether the plugin should automatically load documents from the docs folder when the agent starts. Any value other than the string 'false' enables loading.",
+        "required": false,
+        "default": true,
+        "sensitive": false
+      }
+    }
+  }
 }