@elizaos/plugin-knowledge 1.0.0-beta.70

package/README.md

@@ -0,0 +1,195 @@
+# Knowledge Plugin for ElizaOS
+
+This plugin provides Retrieval Augmented Generation (Knowledge) capabilities for ElizaOS agents, allowing them to load, index, and query knowledge from various sources.
+
+## Quick Setup
+
+### Basic Setup (With plugin-openai)
+
+If you already have plugin-openai configured, you don't need any additional environment variables! The Knowledge plugin will automatically use your OpenAI configuration.
+
+1. Make sure you have plugin-openai configured with:
+
+   ```env
+   OPENAI_API_KEY=your-openai-api-key
+   OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+   ```
+
+2. Add the Knowledge plugin to your agent's configuration
+3. That's it! The plugin will work without any additional variables
+
+### Enabling Contextual Knowledge
+
+If you want enhanced Knowledge capabilities with contextual embeddings, add:
+
+```env
+# Enable contextual Knowledge
+CTX_KNOWLEDGE_ENABLED=true
+
+# Required text generation settings
+TEXT_PROVIDER=openrouter  # Choose your provider: openai, anthropic, openrouter, or google
+TEXT_MODEL=anthropic/claude-3.5-sonnet  # Model for your chosen provider
+
+# Provider-specific API key (based on TEXT_PROVIDER)
+OPENROUTER_API_KEY=your-openrouter-api-key
+# OR ANTHROPIC_API_KEY=your-anthropic-api-key
+# OR GOOGLE_API_KEY=your-google-api-key
+# OR use existing OPENAI_API_KEY
+```
+
+### Custom Embedding Configuration (Without plugin-openai)
+
+If you're not using plugin-openai or want to use different embedding settings:
+
+```env
+# Required embedding settings
+EMBEDDING_PROVIDER=openai  # or google
+TEXT_EMBEDDING_MODEL=text-embedding-3-small
+
+# Provider-specific API key
+OPENAI_API_KEY=your-openai-api-key  # if using openai
+# OR GOOGLE_API_KEY=your-google-api-key  # if using google
+
+# Optional: Custom embedding dimension
+EMBEDDING_DIMENSION=1536
+```
+
+## Advanced Configuration
+
+### Recommended Configurations for Contextual Knowledge
+
+For optimal performance with contextual Knowledge, we recommend these provider combinations:
+
+**Option 1: OpenRouter with Claude/Gemini (Best for cost efficiency)**
+
+```env
+# If using with plugin-openai, only need these additions:
+CTX_KNOWLEDGE_ENABLED=true
+TEXT_PROVIDER=openrouter
+TEXT_MODEL=anthropic/claude-3.5-sonnet  # or google/gemini-2.5-flash-preview
+OPENROUTER_API_KEY=your-openrouter-api-key
+```
+
+**Option 2: OpenAI for Everything**
+
+```env
+# If using with plugin-openai, only need these additions:
+CTX_KNOWLEDGE_ENABLED=true
+TEXT_PROVIDER=openai
+TEXT_MODEL=gpt-4o
+```
+
+**Option 3: Google AI for Everything**
+
+```env
+EMBEDDING_PROVIDER=google
+TEXT_EMBEDDING_MODEL=text-embedding-004
+TEXT_PROVIDER=google
+TEXT_MODEL=gemini-1.5-pro-latest
+GOOGLE_API_KEY=your-google-api-key
+CTX_KNOWLEDGE_ENABLED=true
+```
+
+### Advanced Rate Limiting Options
+
+```env
+# Rate limiting (optional)
+MAX_CONCURRENT_REQUESTS=30  # Default: 30
+REQUESTS_PER_MINUTE=60      # Default: 60
+TOKENS_PER_MINUTE=150000    # Default: 150000
+```
+
+### Custom API Endpoints
+
+```env
+# Only needed if using custom API endpoints
+OPENAI_BASE_URL=https://your-openai-proxy.com/v1
+ANTHROPIC_BASE_URL=https://your-anthropic-proxy.com
+OPENROUTER_BASE_URL=https://your-openrouter-proxy.com/api/v1
+GOOGLE_BASE_URL=https://your-google-proxy.com
+```
+
+### Token Limits
+
+```env
+# Advanced token handling (optional)
+MAX_INPUT_TOKENS=4000   # Default: 4000
+MAX_OUTPUT_TOKENS=4096  # Default: 4096
+```
+
+## Architecture
+
+The plugin is built with a modular, clean architecture that follows SOLID principles:
+
+```
+packages/plugin-knowledge/
+├── src/
+│   ├── index.ts           # Main entry point and plugin definition
+│   ├── service.ts         # Knowledge service implementation
+│   ├── types.ts           # Type definitions
+│   ├── llm.ts             # LLM interactions (text generation, embeddings)
+│   ├── config.ts          # Configuration validation
+│   ├── ctx-embeddings.ts  # Contextual embedding generation
+│   ├── document-processor.ts # Shared document processing utilities
+│   └── utils.ts           # Utility functions
+├── README.md              # This file
+└── package.json           # Package definition
+```
+
+### Database-Specific Processing Paths
+
+The Knowledge plugin adapts to the database technology being used:
+
+1. **PostgreSQL Mode**: Uses worker threads to offload document processing from the main thread
+2. **PGLite Mode**: Uses synchronous processing in the main thread due to PGLite's single-threaded nature
+
+This allows the plugin to work optimally with both databases while maintaining the same functionality.
+
+### Processing Flow
+
+The document processing flow follows these steps regardless of database type:
+
+1. Extract text from the document based on content type
+2. Store the main document in the database
+3. Split the document into chunks
+4. Generate embeddings for each chunk (with optional context enrichment)
+5. Store the chunks with embeddings in the database
+
+## Component Overview
+
+- **KnowledgeService**: Core service that manages document processing and storage
+- **Document Processor**: Provides shared document processing utilities for both processing paths
+
+## Features
+
+- Document upload and processing (PDF, text, and other formats)
+- Contextual chunking and embedding generation
+- Robust error handling and recovery
+- Rate limiting to respect provider limitations
+- Support for multiple LLM providers
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { KnowledgeService } from '@elizaos/plugin-knowledge';
+
+// Add knowledge to an agent
+const result = await knowledgeService.addKnowledge({
+  clientDocumentId: 'unique-id',
+  content: documentContent, // Base64 string for binary files or plain text for text files
+  contentType: 'application/pdf',
+  originalFilename: 'document.pdf',
+  worldId: 'world-id',
+  roomId: 'optional-room-id', // Optional scoping
+  entityId: 'optional-entity-id', // Optional scoping
+});
+
+console.log(`Document stored with ID: ${result.storedDocumentMemoryId}`);
+console.log(`Created ${result.fragmentCount} searchable fragments`);
+```
+
+## License
+
+See the ElizaOS license for details.

package/dist/docs-loader-3LDO3WCY.js

@@ -0,0 +1,129 @@
+// src/docs-loader.ts
+import { logger } from "@elizaos/core";
+import * as fs from "fs";
+import * as path from "path";
+function getKnowledgePath() {
+  const envPath = process.env.KNOWLEDGE_PATH;
+  if (envPath) {
+    const resolvedPath = path.resolve(envPath);
+    if (!fs.existsSync(resolvedPath)) {
+      logger.warn(
+        `Knowledge path from environment variable does not exist: ${resolvedPath}`
+      );
+      logger.warn(
+        "Please create the directory or update KNOWLEDGE_PATH environment variable"
+      );
+    }
+    return resolvedPath;
+  }
+  const defaultPath = path.join(process.cwd(), "docs");
+  if (!fs.existsSync(defaultPath)) {
+    logger.info(`Default docs folder does not exist at: ${defaultPath}`);
+    logger.info("To use the knowledge plugin, either:");
+    logger.info('1. Create a "docs" folder in your project root');
+    logger.info(
+      "2. Set KNOWLEDGE_PATH environment variable to your documents folder"
+    );
+  }
+  return defaultPath;
+}
+async function loadDocsFromPath(service, agentId, worldId) {
+  const docsPath = getKnowledgePath();
+  if (!fs.existsSync(docsPath)) {
+    logger.warn(`Knowledge path does not exist: ${docsPath}`);
+    return { total: 0, successful: 0, failed: 0 };
+  }
+  logger.info(`Loading documents from: ${docsPath}`);
+  const files = getAllFiles(docsPath);
+  if (files.length === 0) {
+    logger.info("No files found in knowledge path");
+    return { total: 0, successful: 0, failed: 0 };
+  }
+  logger.info(`Found ${files.length} files to process`);
+  let successful = 0;
+  let failed = 0;
+  for (const filePath of files) {
+    try {
+      const fileName = path.basename(filePath);
+      const fileExt = path.extname(filePath).toLowerCase();
+      if (fileName.startsWith(".")) {
+        continue;
+      }
+      const contentType = getContentType(fileExt);
+      if (!contentType) {
+        logger.debug(`Skipping unsupported file type: ${filePath}`);
+        continue;
+      }
+      const fileBuffer = fs.readFileSync(filePath);
+      const isBinary = [
+        "application/pdf",
+        "application/msword",
+        "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+      ].includes(contentType);
+      const content = isBinary ? fileBuffer.toString("base64") : fileBuffer.toString("utf-8");
+      const knowledgeOptions = {
+        clientDocumentId: `${agentId}-docs-${Date.now()}-${fileName}`,
+        contentType,
+        originalFilename: fileName,
+        worldId: worldId || agentId,
+        content
+      };
+      logger.debug(`Processing document: ${fileName}`);
+      const result = await service.addKnowledge(knowledgeOptions);
+      logger.info(
+        `Successfully processed ${fileName}: ${result.fragmentCount} fragments created`
+      );
+      successful++;
+    } catch (error) {
+      logger.error(`Failed to process file ${filePath}:`, error);
+      failed++;
+    }
+  }
+  logger.info(
+    `Document loading complete: ${successful} successful, ${failed} failed out of ${files.length} total`
+  );
+  return {
+    total: files.length,
+    successful,
+    failed
+  };
+}
+function getAllFiles(dirPath, files = []) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (!["node_modules", ".git", ".vscode", "dist", "build"].includes(
+          entry.name
+        )) {
+          getAllFiles(fullPath, files);
+        }
+      } else if (entry.isFile()) {
+        files.push(fullPath);
+      }
+    }
+  } catch (error) {
+    logger.error(`Error reading directory ${dirPath}:`, error);
+  }
+  return files;
+}
+function getContentType(extension) {
+  const contentTypes = {
+    ".txt": "text/plain",
+    ".md": "text/plain",
+    ".tson": "text/plain",
+    ".xml": "text/plain",
+    ".csv": "text/plain",
+    ".html": "text/html",
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+  };
+  return contentTypes[extension] || null;
+}
+export {
+  getKnowledgePath,
+  loadDocsFromPath
+};
+//# sourceMappingURL=docs-loader-3LDO3WCY.js.map

package/dist/docs-loader-3LDO3WCY.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/docs-loader.ts"],"sourcesContent":["import { logger, UUID } from \"@elizaos/core\";\nimport * as fs from \"fs\";\nimport * as path from \"path\";\nimport { KnowledgeService } from \"./service.ts\";\nimport { AddKnowledgeOptions } from \"./types.ts\";\n\n/**\n * Get the knowledge path from environment or default to ./docs\n */\nexport function getKnowledgePath(): string {\n  const envPath = process.env.KNOWLEDGE_PATH;\n\n  if (envPath) {\n    // Resolve relative paths from current working directory\n    const resolvedPath = path.resolve(envPath);\n\n    if (!fs.existsSync(resolvedPath)) {\n      logger.warn(\n        `Knowledge path from environment variable does not exist: ${resolvedPath}`\n      );\n      logger.warn(\n        \"Please create the directory or update KNOWLEDGE_PATH environment variable\"\n      );\n    }\n\n    return resolvedPath;\n  }\n\n  // Default to docs folder in current working directory\n  const defaultPath = path.join(process.cwd(), \"docs\");\n\n  if (!fs.existsSync(defaultPath)) {\n    logger.info(`Default docs folder does not exist at: ${defaultPath}`);\n    logger.info(\"To use the knowledge plugin, either:\");\n    logger.info('1. Create a \"docs\" folder in your project root');\n    logger.info(\n      \"2. Set KNOWLEDGE_PATH environment variable to your documents folder\"\n    );\n  }\n\n  return defaultPath;\n}\n\n/**\n * Load documents from the knowledge path\n */\nexport async function loadDocsFromPath(\n  service: KnowledgeService,\n  agentId: UUID,\n  worldId?: UUID\n): Promise<{ total: number; successful: number; failed: number }> {\n  const docsPath = getKnowledgePath();\n\n  if (!fs.existsSync(docsPath)) {\n    logger.warn(`Knowledge path does not exist: ${docsPath}`);\n    return { total: 0, successful: 0, failed: 0 };\n  }\n\n  logger.info(`Loading documents from: ${docsPath}`);\n\n  // Get all files recursively\n  const files = getAllFiles(docsPath);\n\n  if (files.length === 0) {\n    logger.info(\"No files found in knowledge path\");\n    return { total: 0, successful: 0, failed: 0 };\n  }\n\n  logger.info(`Found ${files.length} files to process`);\n\n  let successful = 0;\n  let failed = 0;\n\n  for (const filePath of files) {\n    try {\n      const fileName = path.basename(filePath);\n      const fileExt = path.extname(filePath).toLowerCase();\n\n      // Skip hidden files and directories\n      if (fileName.startsWith(\".\")) {\n        continue;\n      }\n\n      // Determine content type\n      const contentType = getContentType(fileExt);\n\n      // Skip unsupported file types\n      if (!contentType) {\n        logger.debug(`Skipping unsupported file type: ${filePath}`);\n        continue;\n      }\n\n      // Read file\n      const fileBuffer = fs.readFileSync(filePath);\n\n      // For binary files, convert to base64\n      const isBinary = [\n        \"application/pdf\",\n        \"application/msword\",\n        \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n      ].includes(contentType);\n\n      const content = isBinary\n        ? fileBuffer.toString(\"base64\")\n        : fileBuffer.toString(\"utf-8\");\n\n      // Create knowledge options\n      const knowledgeOptions: AddKnowledgeOptions = {\n        clientDocumentId: `${agentId}-docs-${Date.now()}-${fileName}` as UUID,\n        contentType,\n        originalFilename: fileName,\n        worldId: worldId || agentId,\n        content,\n      };\n\n      // Process the document\n      logger.debug(`Processing document: ${fileName}`);\n      const result = await service.addKnowledge(knowledgeOptions);\n\n      logger.info(\n        `Successfully processed ${fileName}: ${result.fragmentCount} fragments created`\n      );\n      successful++;\n    } catch (error) {\n      logger.error(`Failed to process file ${filePath}:`, error);\n      failed++;\n    }\n  }\n\n  logger.info(\n    `Document loading complete: ${successful} successful, ${failed} failed out of ${files.length} total`\n  );\n\n  return {\n    total: files.length,\n    successful,\n    failed,\n  };\n}\n\n/**\n * Recursively get all files in a directory\n */\nfunction getAllFiles(dirPath: string, files: string[] = []): string[] {\n  try {\n    const entries = fs.readdirSync(dirPath, { withFileTypes: true });\n\n    for (const entry of entries) {\n      const fullPath = path.join(dirPath, entry.name);\n\n      if (entry.isDirectory()) {\n        // Skip node_modules and other common directories\n        if (\n          ![\"node_modules\", \".git\", \".vscode\", \"dist\", \"build\"].includes(\n            entry.name\n          )\n        ) {\n          getAllFiles(fullPath, files);\n        }\n      } else if (entry.isFile()) {\n        files.push(fullPath);\n      }\n    }\n  } catch (error) {\n    logger.error(`Error reading directory ${dirPath}:`, error);\n  }\n\n  return files;\n}\n\n/**\n * Get content type based on file extension\n */\nfunction getContentType(extension: string): string | null {\n  const contentTypes: Record<string, string> = {\n    \".txt\": \"text/plain\",\n    \".md\": \"text/plain\",\n    \".tson\": \"text/plain\",\n    \".xml\": \"text/plain\",\n    \".csv\": \"text/plain\",\n    \".html\": \"text/html\",\n    \".pdf\": \"application/pdf\",\n    \".doc\": \"application/msword\",\n    \".docx\":\n      \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n  };\n\n  return contentTypes[extension] || null;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { Plugin } from '@elizaos/core';
+
+/**
+ * Knowledge Plugin - Main Entry Point
+ *
+ * This file exports all the necessary functions and types for the Knowledge plugin.
+ */
+
+/**
+ * Knowledge Plugin - Provides Retrieval Augmented Generation capabilities
+ */
+declare const knowledgePlugin: Plugin;
+
+export { knowledgePlugin as default, knowledgePlugin };