@elizaos/plugin-knowledge 1.0.6 → 1.0.8

package/README.md

@@ -1,183 +1,277 @@
 # Knowledge Plugin for ElizaOS
 
-This plugin gives your agent the ability to learn from documents and answer questions based on that knowledge.
+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 Start (No Configuration Needed!)
+## 🚀 Getting Started (Beginner-Friendly)
 
-If you already have **plugin-openai** configured in your agent, this plugin works automatically! Just add it to your agent and you're done.
+### Step 1: Add the Plugin
+The Knowledge plugin works automatically with any ElizaOS agent. Just add it to your agent's plugin list:
 
 ```typescript
-import { knowledgePlugin } from '@elizaos/plugin-knowledge';
-
-// Add to your agent's plugins
-plugins: [
-  '@elizaos/plugin-knowledge',
-  // ... other plugins
-];
+// 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 process and learn from documents.
-
-## 📁 Auto-Load Documents on Startup
-
-Want your agent to automatically learn from documents when it starts? Just:
-
-1. **Add this to your `.env` file:**
-
-   ```env
-   LOAD_DOCS_ON_STARTUP=true
-   ```
+**That's it!** Your agent can now learn from documents. No environment variables or API keys needed.
 
-2. **Create a `docs` folder in your project root and add your documents:**
+### Step 2: Upload Documents (Optional)
+Want your agent to automatically learn from documents when it starts?
 
+1. **Create a `docs` folder** in your project root:
    ```
    your-project/
    ├── .env
-   ├── docs/           <-- Create this folder
+   ├── docs/           ← Create this folder
    │   ├── guide.pdf
    │   ├── manual.txt
    │   └── notes.md
-   └── ... other files
+   └── package.json
    ```
 
-3. **Start your agent** - it will automatically load all documents from the `docs` folder!
+2. **Add this line to your `.env` file:**
+   ```env
+   LOAD_DOCS_ON_STARTUP=true
+   ```
 
-### Supported File Types
+3. **Start your agent** - it will automatically learn from all documents in the `docs` folder!
 
-- 📄 **Documents:** PDF, TXT, MD, DOC, DOCX
-- 💻 **Code:** JS, TS, PY, and many more
-- 📊 **Data:** JSON, CSV, XML, YAML
+### Step 3: Ask Questions
+Once documents are loaded, just talk to your agent naturally:
 
-## 💬 How to Use
+- "What does the guide say about setup?"
+- "Search your knowledge for configuration info"
+- "What do you know about [any topic]?"
 
-Once documents are loaded, just ask your agent questions naturally:
+Your agent will search through all loaded documents and give you relevant answers!
 
-- "What does the guide say about setup?"
-- "Search your knowledge for information about configuration"
-- "What do you know about [topic]?"
+## 📁 Supported File Types
 
-Your agent will search through all loaded documents and provide relevant answers!
+The plugin can read almost any document:
 
-## 🎯 Actions Available
+- **Text Files:** `.txt`, `.md`, `.csv`, `.json`, `.xml`, `.yaml`
+- **Documents:** `.pdf`, `.doc`, `.docx`
+- **Code Files:** `.js`, `.ts`, `.py`, `.java`, `.cpp`, `.html`, `.css` and many more
 
-The plugin provides these actions that your agent can use:
+## 💬 Using the Web Interface
 
-1. **PROCESS_KNOWLEDGE** - Add new documents or text to the knowledge base
+The plugin includes a web interface for managing documents! 
 
-   - "Process the document at /path/to/file.pdf"
-   - "Remember this: The sky is blue"
+**Access it at:** `http://localhost:3000/api/agents/[your-agent-id]/plugins/knowledge/display`
 
-2. **SEARCH_KNOWLEDGE** - Search the knowledge base
-   - "Search your knowledge for quantum computing"
+You can upload, view, and delete documents directly from your browser.
 
-## 🌐 Web Interface
+## 🎯 Agent Actions
 
-The plugin includes a web interface for managing documents! Access it at:
+Your agent automatically gets these new abilities:
 
-```
-http://localhost:3000/api/agents/[your-agent-id]/plugins/knowledge/display
-```
+- **PROCESS_KNOWLEDGE** - "Remember this document: [file path or text]"
+- **SEARCH_KNOWLEDGE** - "Search your knowledge for [topic]"
 
----
+## ❓ FAQ
 
-## ⚠️ Advanced Configuration (Developers Only)
+**Q: Do I need any API keys?**  
+A: No! It uses your existing OpenAI/Google/Anthropic setup automatically.
 
-**Note: If you're not a developer, don't use the settings below! The plugin works great with just the quick start setup above.**
+**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.
 
-<details>
-<summary>Click to show advanced configuration options</summary>
+**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.
 
-### Custom Document Path
+**Q: How much does this cost?**  
+A: Only the cost of generating embeddings (usually pennies per document).
 
-Change where documents are loaded from:
+---
 
-```env
-KNOWLEDGE_PATH=/path/to/your/documents
-```
+## 🔧 Advanced Configuration (Developers)
 
-### Enhanced Contextual Knowledge
+> **⚠️ Note for Beginners:** The settings below are for advanced users only. The plugin works great without any of this configuration!
 
-For better understanding of complex documents:
+<details>
+<summary><strong>🚀 Enhanced Contextual Knowledge (Recommended for Developers)</strong></summary>
+
+For significantly better understanding of complex documents, enable contextual embeddings with caching:
 
 ```env
+# Enable enhanced contextual understanding
 CTX_KNOWLEDGE_ENABLED=true
+
+# 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-api-key
+OPENROUTER_API_KEY=your-openrouter-api-key
 ```
 
-### Custom Embedding Configuration
+**Benefits:**
+- 📈 **Better Understanding:** Chunks include surrounding context
+- 💰 **90% Cost Reduction:** Document caching reduces repeated processing costs
+- 🎯 **Improved Accuracy:** More relevant search results
 
-If not using plugin-openai:
+**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)
 
-```env
-EMBEDDING_PROVIDER=openai
-TEXT_EMBEDDING_MODEL=text-embedding-3-small
-OPENAI_API_KEY=your-api-key
-```
+</details>
 
-### All Configuration Options
+<details>
+<summary><strong>⚙️ Custom Configuration Options</strong></summary>
 
+### Document Loading
 ```env
-# Document Loading
 LOAD_DOCS_ON_STARTUP=true          # Auto-load from docs folder
-KNOWLEDGE_PATH=/custom/path        # Custom document path
-
-# Contextual Enhancement (improves understanding)
-CTX_KNOWLEDGE_ENABLED=true         # Enable contextual embeddings
+KNOWLEDGE_PATH=/custom/path        # Custom document path (default: ./docs)
+```
 
-# Embedding Provider (if not using plugin-openai)
-EMBEDDING_PROVIDER=openai          # or google
+### 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
+EMBEDDING_DIMENSION=1536           # Vector dimension
+```
 
-# Text Generation Provider (for contextual mode)
-TEXT_PROVIDER=openai               # or anthropic, openrouter, google
-TEXT_MODEL=gpt-4o                  # Model name for your provider
+### Text Generation (for Contextual Mode)
+```env
+TEXT_PROVIDER=openrouter           # openai | anthropic | openrouter | google
+TEXT_MODEL=anthropic/claude-3.5-sonnet
+```
 
-# API Keys (based on providers used)
-OPENAI_API_KEY=your-key
-ANTHROPIC_API_KEY=your-key
-OPENROUTER_API_KEY=your-key
+### API Keys (as needed)
+```env
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+OPENROUTER_API_KEY=sk-or-...
 GOOGLE_API_KEY=your-key
+```
 
-# Rate Limiting
-MAX_CONCURRENT_REQUESTS=30
-REQUESTS_PER_MINUTE=60
-TOKENS_PER_MINUTE=150000
-
-# Token Limits
-MAX_INPUT_TOKENS=4000
-MAX_OUTPUT_TOKENS=4096
+### 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
 ```
 
-### API Routes Reference
+</details>
+
+<details>
+<summary><strong>🔌 API Reference</strong></summary>
 
+### HTTP Endpoints
 - `POST /api/agents/{agentId}/plugins/knowledge/documents` - Upload documents
-- `GET /api/agents/{agentId}/plugins/knowledge/documents` - List 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
 
 ### Programmatic Usage
-
 ```typescript
 import { KnowledgeService } from '@elizaos/plugin-knowledge';
 
 // Add knowledge programmatically
 const result = await knowledgeService.addKnowledge({
-  clientDocumentId: 'unique-id',
-  content: documentContent,
+  clientDocumentId: 'unique-doc-id',
+  content: documentContent,          // Base64 for PDFs, plain text for others
   contentType: 'application/pdf',
   originalFilename: 'document.pdf',
-  worldId: 'world-id',
-  roomId: 'room-id',
-  entityId: 'entity-id',
+  worldId: runtime.worldId,
+  roomId: runtime.roomId,
+  entityId: runtime.entityId,
+  metadata: {                        // Optional
+    source: 'upload',
+    author: 'John Doe'
+  }
+});
+
+// Search knowledge
+const searchResults = await knowledgeService.searchKnowledge({
+  query: 'quantum computing',
+  agentId: runtime.agentId,
+  limit: 10
 });
 ```
 
 </details>
 
+<details>
+<summary><strong>🐛 Troubleshooting</strong></summary>
+
+### Common Issues
+
+**"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
+
+**"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
+
+**"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
+
+**"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`
+
+### 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
+
+### File Upload Configuration
+
+#### Automatic MIME Type Correction
+The frontend automatically corrects MIME types for code and document files to ensure proper processing:
+
+```typescript
+const getCorrectMimeType = (file: File): string => {
+  const filename = file.name.toLowerCase();
+  const ext = filename.split('.').pop() || '';
+
+  // Map common text file extensions to text/plain
+  const textExtensions = [
+    'ts', 'tsx', 'js', 'jsx', 'mjs', 'cjs',
+    'py', 'pyw', 'pyi', 'java', 'c', 'cpp', 'cc', 'cxx', 'h', 'hpp',
+    'cs', 'php', 'rb', 'go', 'rs', 'swift', 'kt', 'kts', 'scala',
+    // ... and many more
+  ];
+
+  if (textExtensions.includes(ext)) {
+    return 'text/plain';
+  } else if (['md', 'markdown'].includes(ext)) {
+    return 'text/markdown';
+  } else if (ext === 'json') {
+    return 'application/json';
+  }
+  // ... additional mappings
+
+  return file.type || 'application/octet-stream';
+};
+```
+
+#### Supported File Types
+
+- **Documents**: PDF, DOC, DOCX
+- **Code**: JS, TS, PY, JAVA, C, CPP, etc.
+- **Text**: TXT, MD, CSV, JSON, XML, HTML
+- **Configuration**: ENV, CFG, INI, YAML, YML
+
+</details>
+
 ## 📝 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-DlJcnv-R.js",
+    "file": "assets/index-BMDX6vvo.js",
     "name": "index",
     "src": "index.html",
     "isEntry": true,
     "css": [
-      "assets/index-DiVvUMt0.css"
+      "assets/index-o1rKIvUo.css"
     ]
   }
 }