@elizaos/plugin-knowledge 1.0.5 → 1.0.7

package/README.md

@@ -1,409 +1,239 @@
 # 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.
+Give your AI agent the ability to learn from documents and answer questions based on that knowledge. Works out of the box with zero configuration!
 
-## Quick Setup
+## 🚀 Getting Started (Beginner-Friendly)
 
-> **⚠️ Note**: `TEXT_PROVIDER` and `TEXT_MODEL` configuration are temporarily disabled. The plugin currently uses `runtime.useModel(TEXT_LARGE)` for text generation. Full provider configuration support will be added soon.
+### Step 1: Add the Plugin
+The Knowledge plugin works automatically with any ElizaOS agent. Just add it to your agent's plugin list:
 
-### Basic Setup (With plugin-openai)
+```typescript
+// In your character file (e.g., character.ts)
+export const character = {
+  name: 'MyAgent',
+  plugins: [
+    '@elizaos/plugin-openai',        // ← Make sure you have this
+    '@elizaos/plugin-knowledge',     // ← Add this line
+    // ... your other plugins
+  ],
+  // ... rest of your character config
+};
+```
+
+**That's it!** Your agent can now learn from documents. No environment variables or API keys needed.
 
-If you already have plugin-openai configured, you don't need any additional environment variables! The Knowledge plugin will automatically use your OpenAI configuration.
+### Step 2: Upload Documents (Optional)
+Want your agent to automatically learn from documents when it starts?
 
-1. Make sure you have plugin-openai configured with:
+1. **Create a `docs` folder** in your project root:
+   ```
+   your-project/
+   ├── .env
+   ├── docs/           ← Create this folder
+   │   ├── guide.pdf
+   │   ├── manual.txt
+   │   └── notes.md
+   └── package.json
+   ```
 
+2. **Add this line to your `.env` file:**
    ```env
-   OPENAI_API_KEY=your-openai-api-key
-   OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+   LOAD_DOCS_ON_STARTUP=true
    ```
 
-2. Add the Knowledge plugin to your agent's configuration
-3. That's it! The plugin will work without any additional variables
+3. **Start your agent** - it will automatically learn from all documents in the `docs` folder!
 
-### Enabling Contextual Knowledge
+### Step 3: Ask Questions
+Once documents are loaded, just talk to your agent naturally:
 
-If you want enhanced Knowledge capabilities with contextual embeddings, add:
+- "What does the guide say about setup?"
+- "Search your knowledge for configuration info"
+- "What do you know about [any topic]?"
 
-> **Note**: The TEXT_PROVIDER and TEXT_MODEL settings below are temporarily disabled. The plugin will use `runtime.useModel(TEXT_LARGE)` for now.
+Your agent will search through all loaded documents and give you relevant answers!
 
-```env
-# Enable contextual Knowledge
-CTX_KNOWLEDGE_ENABLED=true
+## 📁 Supported File Types
 
-# Required text generation settings (TEMPORARILY DISABLED)
-TEXT_PROVIDER=openrouter  # Choose your provider: openai, anthropic, openrouter, or google
-TEXT_MODEL=anthropic/claude-3.5-sonnet  # Model for your chosen provider
+The plugin can read almost any document:
 
-# 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
-```
+- **Text Files:** `.txt`, `.md`, `.csv`, `.json`, `.xml`, `.yaml`
+- **Documents:** `.pdf`, `.doc`, `.docx`
+- **Code Files:** `.js`, `.ts`, `.py`, `.java`, `.cpp`, `.html`, `.css` and many more
 
-### Custom Embedding Configuration (Without plugin-openai)
+## 💬 Using the Web Interface
 
-If you're not using plugin-openai or want to use different embedding settings:
+The plugin includes a web interface for managing documents! 
 
-```env
-# Required embedding settings
-EMBEDDING_PROVIDER=openai  # or google
-TEXT_EMBEDDING_MODEL=text-embedding-3-small
+**Access it at:** `http://localhost:3000/api/agents/[your-agent-id]/plugins/knowledge/display`
 
-# 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
+You can upload, view, and delete documents directly from your browser.
 
-# Optional: Custom embedding dimension
-EMBEDDING_DIMENSION=1536
-```
+## 🎯 Agent Actions
 
-## Advanced Configuration
+Your agent automatically gets these new abilities:
 
-### Recommended Configurations for Contextual Knowledge
+- **PROCESS_KNOWLEDGE** - "Remember this document: [file path or text]"
+- **SEARCH_KNOWLEDGE** - "Search your knowledge for [topic]"
 
-For optimal performance with contextual Knowledge, we recommend these provider combinations:
+## ❓ FAQ
 
-**Option 1: OpenRouter with Claude/Gemini (Best for cost efficiency)**
+**Q: Do I need any API keys?**  
+A: No! It uses your existing OpenAI/Google/Anthropic setup automatically.
 
-```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
-```
+**Q: What if I don't have any AI plugins?**  
+A: You need at least one AI provider plugin (like `@elizaos/plugin-openai`) for embeddings.
 
-**Option 2: OpenAI for Everything**
+**Q: Can I upload documents while the agent is running?**  
+A: Yes! Use the web interface or just tell your agent to process a file.
 
-```env
-# If using with plugin-openai, only need these additions:
-CTX_KNOWLEDGE_ENABLED=true
-TEXT_PROVIDER=openai
-TEXT_MODEL=gpt-4o
-```
+**Q: How much does this cost?**  
+A: Only the cost of generating embeddings (usually pennies per document).
 
-**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 Configuration (Developers)
 
-### Advanced Rate Limiting Options
+> **⚠️ Note for Beginners:** The settings below are for advanced users only. The plugin works great without any of this configuration!
 
-```env
-# Rate limiting (optional)
-MAX_CONCURRENT_REQUESTS=30  # Default: 30
-REQUESTS_PER_MINUTE=60      # Default: 60
-TOKENS_PER_MINUTE=150000    # Default: 150000
-```
+<details>
+<summary><strong>🚀 Enhanced Contextual Knowledge (Recommended for Developers)</strong></summary>
 
-### Custom API Endpoints
+For significantly better understanding of complex documents, enable contextual embeddings with caching:
 
 ```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
-```
-
-### Knowledge Document Path
-
-By default, the plugin looks for knowledge documents in a `docs` folder in your project root. You can customize this location using the `KNOWLEDGE_PATH` environment variable:
-
-```env
-# Custom path to your knowledge documents
-KNOWLEDGE_PATH=/path/to/your/documents
+# Enable enhanced contextual understanding
+CTX_KNOWLEDGE_ENABLED=true
 
-# Examples:
-# KNOWLEDGE_PATH=./my-docs           # Relative path from project root
-# KNOWLEDGE_PATH=/home/user/docs     # Absolute path
-# KNOWLEDGE_PATH=../shared/knowledge # Relative path to parent directory
+# Use OpenRouter with Claude for best results + 90% cost savings via caching
+TEXT_PROVIDER=openrouter
+TEXT_MODEL=anthropic/claude-3.5-sonnet
+OPENROUTER_API_KEY=your-openrouter-api-key
 ```
 
-**How it works:**
-- If `KNOWLEDGE_PATH` is set, the plugin will use that directory for loading knowledge documents
-- If `KNOWLEDGE_PATH` is not set, the plugin defaults to `./docs` (a `docs` folder in your project root)
-- Both relative and absolute paths are supported
-- If the specified path doesn't exist, the plugin will log a warning but continue to function
+**Benefits:**
+- 📈 **Better Understanding:** Chunks include surrounding context
+- 💰 **90% Cost Reduction:** Document caching reduces repeated processing costs
+- 🎯 **Improved Accuracy:** More relevant search results
+
+**Best Models for Contextual Mode:**
+- `anthropic/claude-3.5-sonnet` (recommended)
+- `google/gemini-2.5-flash` (fast + cheap)
+- `anthropic/claude-3.5-haiku` (budget option)
 
-**Supported document formats:**
-- PDF files (`.pdf`)
-- Text files (`.txt`, `.md`)
-- And other formats supported by the document processor
+</details>
 
-### Token Limits
+<details>
+<summary><strong>⚙️ Custom Configuration Options</strong></summary>
 
+### Document Loading
 ```env
-# Advanced token handling (optional)
-MAX_INPUT_TOKENS=4000   # Default: 4000
-MAX_OUTPUT_TOKENS=4096  # Default: 4096
+LOAD_DOCS_ON_STARTUP=true          # Auto-load from docs folder
+KNOWLEDGE_PATH=/custom/path        # Custom document path (default: ./docs)
 ```
 
-## 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
+### Embedding Configuration
+```env
+# Only needed if you're not using a standard AI plugin
+EMBEDDING_PROVIDER=openai          # openai | google
+TEXT_EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_DIMENSION=1536           # Vector dimension
 ```
 
-### 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
-
-## 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"
+### Text Generation (for Contextual Mode)
+```env
+TEXT_PROVIDER=openrouter           # openai | anthropic | openrouter | google
+TEXT_MODEL=anthropic/claude-3.5-sonnet
 ```
 
-**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"
-  }'
+### API Keys (as needed)
+```env
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
+GOOGLE_API_KEY=your-key
 ```
 
-**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
-    }
-  ]
-}
+### Performance Tuning
+```env
+MAX_CONCURRENT_REQUESTS=30         # Parallel processing limit
+REQUESTS_PER_MINUTE=60             # Rate limiting
+TOKENS_PER_MINUTE=150000           # Token rate limiting
+MAX_INPUT_TOKENS=4000              # Chunk size limit
+MAX_OUTPUT_TOKENS=4096             # Response size limit
 ```
 
-**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
+</details>
 
-#### GET `/documents` - List Documents
-Retrieve all knowledge documents.
+<details>
+<summary><strong>🔌 API Reference</strong></summary>
 
-```bash
-curl "/api/agents/{agentId}/plugins/knowledge/documents?limit=20&before=1703123456789&includeEmbedding=false"
-```
+### HTTP Endpoints
+- `POST /api/agents/{agentId}/plugins/knowledge/documents` - Upload documents
+- `GET /api/agents/{agentId}/plugins/knowledge/documents` - List all documents
+- `GET /api/agents/{agentId}/plugins/knowledge/documents/{id}` - Get specific document
+- `DELETE /api/agents/{agentId}/plugins/knowledge/documents/{id}` - Delete document
+- `GET /api/agents/{agentId}/plugins/knowledge/display` - Web interface
 
-**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}"
-```
+### Programmatic Usage
+```typescript
+import { KnowledgeService } from '@elizaos/plugin-knowledge';
 
-**Response:**
-```json
-{
-  "success": true,
-  "data": {
-    "document": {
-      "id": "document-uuid",
-      "content": { "text": "..." },
-      "metadata": { "..." },
-      "createdAt": 1703123456789
-    }
+// Add knowledge programmatically
+const result = await knowledgeService.addKnowledge({
+  clientDocumentId: 'unique-doc-id',
+  content: documentContent,          // Base64 for PDFs, plain text for others
+  contentType: 'application/pdf',
+  originalFilename: 'document.pdf',
+  worldId: runtime.worldId,
+  roomId: runtime.roomId,
+  entityId: runtime.entityId,
+  metadata: {                        // Optional
+    source: 'upload',
+    author: 'John Doe'
   }
-}
-```
-
-#### 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
-}
+// Search knowledge
+const searchResults = await knowledgeService.searchKnowledge({
+  query: 'quantum computing',
+  agentId: runtime.agentId,
+  limit: 10
+});
 ```
 
-### Knowledge Fragments
+</details>
 
-#### GET `/knowledges` - List Knowledge Chunks
-Retrieve knowledge fragments/chunks for detailed analysis or graph view.
+<details>
+<summary><strong>🐛 Troubleshooting</strong></summary>
 
-```bash
-curl "/api/agents/{agentId}/plugins/knowledge/knowledges?limit=100&documentId=optional-filter"
-```
+### Common Issues
 
-**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
-      }
-    ]
-  }
-}
-```
+**"Knowledge plugin failed to initialize"**
+- Make sure you have an AI provider plugin (openai, google-genai, etc.)
+- Check that your AI provider has valid API keys
 
-## Usage
+**"Documents not loading automatically"**
+- Verify `LOAD_DOCS_ON_STARTUP=true` in your `.env` file
+- Check that the `docs` folder exists in your project root
+- Make sure files are readable and in supported formats
 
-### Programmatic Usage
+**"Search returns no results"**
+- Documents need to be processed first (wait for startup to complete)
+- Try simpler search terms
+- Check that documents actually contain the content you're searching for
 
-```typescript
-import { KnowledgeService } from '@elizaos/plugin-knowledge';
+**"Out of memory errors"**
+- Reduce `MAX_CONCURRENT_REQUESTS` to 10-15
+- Process smaller documents or fewer documents at once
+- Increase Node.js memory limit: `node --max-old-space-size=4096`
 
-// 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
-});
+### Performance Tips
+- **Smaller chunks = better search precision** (but more tokens used)
+- **Contextual mode = better understanding** (but slower processing)
+- **Batch document uploads** rather than one-by-one for better performance
 
-console.log(`Document stored with ID: ${result.storedDocumentMemoryId}`);
-console.log(`Created ${result.fragmentCount} searchable fragments`);
-```
+</details>
 
-## License
+## 📝 License
 
-See the ElizaOS license for details.
+MIT License - See the main ElizaOS license for details.

package/dist/.vite/manifest.json

@@ -1,11 +1,11 @@
 {
   "index.html": {
-    "file": "assets/index-DZQIX0Kb.js",
+    "file": "assets/index-BMDX6vvo.js",
     "name": "index",
     "src": "index.html",
     "isEntry": true,
     "css": [
-      "assets/index-C77XebWS.css"
+      "assets/index-o1rKIvUo.css"
     ]
   }
 }