lightrag 1.0.0 → 1.1.1

package/README.md

@@ -1,7 +1,7 @@
 # LightRAG
 
 Lightweight Retrieval-Augmented Generation library with Knowledge Graph.  
-Runs in Node.js (CommonJS). Browser usage requires a bundler.
+Runs in Node.js (CommonJS) and browsers (Web Worker, no bundler required).
 
 ## Install
 
@@ -11,6 +11,8 @@ npm install lightrag
 
 ## Usage
 
+### Node.js
+
 ```js
 const { pipeline } = require('@huggingface/transformers');
 const { LightRAG, Embedder } = require('lightrag');
@@ -22,17 +24,50 @@ const { LightRAG, Embedder } = require('lightrag');
         embedder: _embedder,
         tokenizer: _pipe.tokenizer,
         llmFunc: async (prompt, opts = {}) => {
-            // call your LLM API here, return string
+            const _resp = await fetch('https://api.deepseek.com/v1/chat/completions', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer YOUR_KEY' },
+                body: JSON.stringify({ model: 'deepseek-v4-flash', messages: [{ role: 'user', content: prompt }] }),
+            });
+            const _json = await _resp.json();
+            return _json.choices?.[0]?.message?.content || '';
         },
     });
 
     await _rag.insert('Your document text here...');
-
     const _answer = await _rag.query('What is this about?', { mode: 'hybrid' });
     console.log(_answer);
 })();
 ```
 
+### Browser (Web Worker)
+
+Load Transformers.js from CDN in your Worker, then create a LightRAG instance. The `storage.js` module provides IndexedDB persistence for saving/restoring RAG state across page reloads.
+
+```js
+import { pipeline, env } from 'https://unpkg.com/@huggingface/transformers@4.2.0/dist/transformers.js';
+
+env.allowLocalModels = false;
+env.useBrowserCache = true;
+
+const _pipe = await pipeline('feature-extraction', 'Xenova/multilingual-e5-small', { dtype: 'fp32' });
+const _embedder = new Embedder(_pipe);
+const _rag = new LightRAG({
+    embedder: _embedder,
+    tokenizer: _pipe.tokenizer,
+    llmFunc: async (prompt) => {
+        const _resp = await fetch('https://api.deepseek.com/v1/chat/completions', { ... });
+        const _json = await _resp.json();
+        return _json.choices?.[0]?.message?.content || '';
+    },
+});
+
+await _rag.insert(documentText);
+const _context = await _rag.buildContext(question, 'hybrid');
+```
+
+See the [BlackboardLM](https://github.com/Mirakelor/BlackboardLM) project for a complete browser integration example using Web Workers, IndexedDB persistence, and streaming LLM responses.
+
 ## API
 
 ### `new LightRAG(opts)`
@@ -53,14 +88,25 @@ Inserts document text: tokenizes → chunks → embeds each chunk into vector DB
 
 ### `rag.query(question, options)`
 
-Query with RAG.
+Query with RAG. Calls `llmFunc` with the question, system prompt (including retrieved context), and conversation history.
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `options.mode` | `string` | `'hybrid'` | `'naive'` \| `'local'` \| `'global'` \| `'hybrid'` \| `'mix'` |
 | `options.systemPrompt` | `string` | `''` | System prompt prepended to LLM context |
 | `options.history` | `array` | `[]` | Conversation history `[{role, content}]` |
-| `options.stream` | `boolean` | `false` | Whether the LLM should stream (passed to `llmFunc`) |
+| `options.stream` | `boolean` | `false` | Passed through to `llmFunc` |
+
+### `rag.buildContext(question, mode)`
+
+Returns the retrieved context string for a given question and mode, **without** calling the LLM. Useful when you want to handle the LLM call yourself (e.g., for streaming).
+
+| Arg | Type | Description |
+|-----|------|-------------|
+| `question` | `string` | The query to build context for |
+| `mode` | `string` | Retrieval mode (`'local'` / `'global'` / `'hybrid'` / `'mix'`) |
+
+Returns `''` for `'naive'` mode or when no documents are indexed.
 
 ### `rag.getGraphData()`
 
@@ -70,9 +116,26 @@ Returns `{ nodes, edges }` — nodes with `id, entity_type, description, degree`
 
 Returns `{ total, ready, isInserting, isReady }` — insertion progress.
 
+### `rag.vdbSize`
+
+Getter returning the number of vectors currently stored (read-only).
+
 ### `rag.toJSON()` / `LightRAG.fromJSON(data, opts)`
 
-Serialize/deserialize the entire RAG state (vector DB + knowledge graph).
+Serialize/deserialize the entire RAG state (vector DB + knowledge graph). Use with `storage.js` for IndexedDB persistence in browsers, or with `fs` in Node.js.
+
+## Storage (Browser)
+
+`lightrag/src/storage.js` provides a simple IndexedDB wrapper for persisting RAG state:
+
+```js
+import { Storage } from 'lightrag/src/storage.js';
+
+await Storage.save('rag_state', rag.toJSON());
+const _data = await Storage.load('rag_state');
+const _rag = LightRAG.fromJSON(_data, opts);
+await Storage.clear();
+```
 
 ## License
 

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "lightrag",
-  "version": "1.0.0",
-  "description": "Lightweight RAG library with knowledge graph — browser and Node.js, MIT licensed",
+  "version": "1.1.1",
+  "description": "Lightweight RAG library with knowledge graph — runs in Node.js and browsers (Web Worker, no bundler), MIT licensed",
   "main": "src/index.js",
+  "browser": "src/index.js",
   "files": [
-    "src/"
+    "src/",
+    "server.js"
   ],
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -16,16 +18,27 @@
     "llm",
     "transformers.js",
     "lightrag",
-    "entity-extraction"
+    "entity-extraction",
+    "embeddings",
+    "retrieval",
+    "browser",
+    "web-worker",
+    "indexeddb"
   ],
   "author": "BlackboardLM",
   "license": "MIT",
+  "homepage": "https://github.com/Mirakelor/BlackboardLM/tree/main/lightrag#readme",
   "repository": {
     "type": "git",
-    "url": "https://github.com/winterist/BlackboardLM"
+    "url": "https://github.com/Mirakelor/BlackboardLM"
   },
   "type": "commonjs",
-  "dependencies": {
-    "@huggingface/transformers": "^4.2.0"
+  "peerDependencies": {
+    "@huggingface/transformers": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
   }
 }

package/server.js

@@ -0,0 +1,162 @@
+const { pipeline, env } = require('@huggingface/transformers');
+const { LightRAG, Embedder } = require('./src/index');
+const fs = require('fs');
+
+env.remoteHost = process.env.HF_REMOTE_HOST || 'https://huggingface.co/';
+const MODEL_NAME = process.env.TRANSFORMERS_JS_MODEL || 'Xenova/multilingual-e5-small';
+const STORAGE_FILE = (process.env.LIGHTRAG_STORAGE || '/tmp/blackboardlm_rag.json');
+
+let _rag = null;
+let _pipe = null;
+
+async function _llmFunc(prompt, opts = {}) {
+    const _apiKey = process.env.DEEPSEEK_API_KEY || '';
+    const _baseUrl = process.env.DEEPSEEK_BASE_URL || 'https://api.deepseek.com';
+    const _model = process.env.LLM_MODEL || 'deepseek-v4-flash';
+    const _messages = [];
+    if (opts.system_prompt) _messages.push({ role: 'system', content: opts.system_prompt });
+    if (opts.history) _messages.push(...opts.history);
+    _messages.push({ role: 'user', content: prompt });
+    const _resp = await fetch(`${_baseUrl}/v1/chat/completions`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${_apiKey}` },
+        body: JSON.stringify({
+            model: _model,
+            messages: _messages,
+            temperature: 0.7,
+            max_tokens: parseInt(process.env.LLM_MAX_TOKENS || '16384'),
+            stream: !!opts.stream,
+            extra_body: {
+                thinking: { type: process.env.LLM_THINKING || 'disabled' },
+                reasoning_effort: process.env.LLM_REASONING_EFFORT || 'max',
+            },
+        }),
+    });
+    if (!_resp.ok) throw new Error(`LLM API error: ${_resp.status}`);
+    if (opts.stream) {
+        let _text = '';
+        const _body = _resp.body;
+        const _reader = _body.getReader();
+        const _decoder = new TextDecoder();
+        while (true) {
+            const { done, value } = await _reader.read();
+            if (done) break;
+            const _chunk = _decoder.decode(value, { stream: true });
+            const _lines = _chunk.split('\n').filter(_l => _l.startsWith('data: '));
+            for (const _line of _lines) {
+                const _data = _line.slice(6);
+                if (_data === '[DONE]') continue;
+                try {
+                    const _json = JSON.parse(_data);
+                    const _content = _json.choices?.[0]?.delta?.content || '';
+                    _text += _content;
+                } catch (_e) {}
+            }
+        }
+        return _text;
+    }
+    const _json = await _resp.json();
+    return _json.choices?.[0]?.message?.content || '';
+}
+
+async function _init() {
+    const _start = Date.now();
+    _pipe = await pipeline('feature-extraction', MODEL_NAME, {
+        dtype: 'fp32',
+        progress_callback: (_info) => {
+            if (_info.status === 'progress' && _info.total) {
+                process.stderr.write(JSON.stringify({ status: 'progress', loaded: _info.loaded, total: _info.total, file: _info.file }) + '\n');
+            }
+        },
+    });
+    const _embedder = new Embedder(_pipe);
+    if (fs.existsSync(STORAGE_FILE)) {
+        try {
+            const _json = JSON.parse(fs.readFileSync(STORAGE_FILE, 'utf-8'));
+            _rag = LightRAG.fromJSON(_json, { embedder: _embedder, llmFunc: _llmFunc, tokenizer: _pipe.tokenizer });
+        } catch (_e) {
+            _rag = new LightRAG({ embedder: _embedder, llmFunc: _llmFunc, tokenizer: _pipe.tokenizer });
+        }
+    } else {
+        _rag = new LightRAG({ embedder: _embedder, llmFunc: _llmFunc, tokenizer: _pipe.tokenizer });
+    }
+    const _elapsed = Date.now() - _start;
+    process.stderr.write(JSON.stringify({ status: 'ready', model: MODEL_NAME, init_ms: _elapsed, loaded: _rag._vdb.size > 0 }) + '\n');
+}
+
+function _save() {
+    fs.writeFileSync(STORAGE_FILE, JSON.stringify(_rag.toJSON()), 'utf-8');
+}
+
+function _clearStorage() {
+    if (fs.existsSync(STORAGE_FILE)) fs.unlinkSync(STORAGE_FILE);
+}
+
+async function _handle(req) {
+    console.error(`[Server] Request: action=${req.action}`);
+    switch (req.action) {
+        case 'insert':
+            console.error(`[Server] Inserting text (${(req.text || '').length} chars)`);
+            await _rag.insert(req.text);
+            _save();
+            console.error(`[Server] Insert done, saved to ${STORAGE_FILE}`);
+            return { ok: true, progress: _rag.getProgress() };
+        case 'query': {
+            console.error(`[Server] Query: mode=${req.mode || 'hybrid'}, history_len=${(req.history || []).length}`);
+            const _text = await _rag.query(req.question, {
+                mode: req.mode || 'hybrid',
+                systemPrompt: req.systemPrompt || '',
+                history: req.history || [],
+            });
+            return { ok: true, text: _text };
+        }
+        case 'graph':
+            return { ok: true, ..._rag.getGraphData() };
+        case 'progress':
+            return { ok: true, ..._rag.getProgress() };
+        case 'reset':
+            const { LightRAG: _LR, Embedder: _E } = require('./src/index');
+            _rag = new _LR({ embedder: new _E(_pipe), llmFunc: _llmFunc, tokenizer: _pipe.tokenizer });
+            _clearStorage();
+            return { ok: true };
+        case 'save':
+            _save();
+            return { ok: true };
+        case 'load':
+            if (fs.existsSync(STORAGE_FILE)) {
+                const _json = JSON.parse(fs.readFileSync(STORAGE_FILE, 'utf-8'));
+                const { LightRAG: _LR2, Embedder: _E2 } = require('./src/index');
+                _rag = LightRAG.fromJSON(_json, { embedder: new _E2(_pipe), llmFunc: _llmFunc, tokenizer: _pipe.tokenizer });
+                return { ok: true, loaded: _rag._vdb.size > 0 };
+            }
+            return { ok: true, loaded: false };
+        default:
+            return { error: `Unknown action: ${req.action}` };
+    }
+}
+
+async function main() {
+    await _init();
+    let _buf = '';
+    process.stdin.setEncoding('utf-8');
+    for await (const _chunk of process.stdin) {
+        _buf += _chunk;
+        const _parts = _buf.split('\n');
+        _buf = _parts.pop();
+        for (const _line of _parts) {
+            if (!_line.trim()) continue;
+            try {
+                const _req = JSON.parse(_line);
+                const _resp = await _handle(_req);
+                if (_resp !== null) process.stdout.write(JSON.stringify(_resp) + '\n');
+            } catch (_e) {
+                process.stdout.write(JSON.stringify({ error: _e.message }) + '\n');
+            }
+        }
+    }
+}
+
+main().catch(_e => {
+    process.stderr.write(JSON.stringify({ error: _e.message }) + '\n');
+    process.exit(1);
+});

package/src/lightrag.js

@@ -89,6 +89,12 @@ class LightRAG {
         return await this._llmFunc(question, { system_prompt: _sysPrompt, history: options.history || [], stream: options.stream });
     }
 
+    async buildContext(question, mode) {
+        if (mode === 'naive' || this._vdb.size === 0) return '';
+        const _qVec = await this._embedder.embedQuery(question);
+        return await this._buildContext(new Float32Array(_qVec), mode);
+    }
+
     async _buildContext(_qVec, mode) {
         let _parts = [];
         if (mode === 'local' || mode === 'hybrid' || mode === 'mix') {

package/src/storage.js

@@ -0,0 +1,60 @@
+const _DB_NAME = 'blackboardlm_rag';
+const _DB_VERSION = 1;
+const _STORE_NAME = 'rag_state';
+
+function _open() {
+  return new Promise((_resolve, _reject) => {
+    const _req = indexedDB.open(_DB_NAME, _DB_VERSION);
+    _req.onupgradeneeded = (_e) => {
+      const _db = _e.target.result;
+      if (!_db.objectStoreNames.contains(_STORE_NAME)) {
+        _db.createObjectStore(_STORE_NAME);
+      }
+    };
+    _req.onsuccess = (_e) => _resolve(_e.target.result);
+    _req.onerror = (_e) => _reject(_e.target.error);
+  });
+}
+
+async function _save(key, data) {
+  const _db = await _open();
+  return new Promise((_resolve, _reject) => {
+    const _tx = _db.transaction(_STORE_NAME, 'readwrite');
+    const _store = _tx.objectStore(_STORE_NAME);
+    _store.put(data, key);
+    _tx.oncomplete = () => _resolve();
+    _tx.onerror = (_e) => _reject(_e.target.error);
+  });
+}
+
+async function _load(key) {
+  const _db = await _open();
+  return new Promise((_resolve, _reject) => {
+    const _tx = _db.transaction(_STORE_NAME, 'readonly');
+    const _store = _tx.objectStore(_STORE_NAME);
+    const _req = _store.get(key);
+    _req.onsuccess = (_e) => _resolve(_e.target.result);
+    _req.onerror = (_e) => _reject(_e.target.error);
+  });
+}
+
+async function _clear() {
+  const _db = await _open();
+  return new Promise((_resolve, _reject) => {
+    const _tx = _db.transaction(_STORE_NAME, 'readwrite');
+    const _store = _tx.objectStore(_STORE_NAME);
+    _store.clear();
+    _tx.oncomplete = () => _resolve();
+    _tx.onerror = (_e) => _reject(_e.target.error);
+  });
+}
+
+const Storage = {
+  save: (key, data) => _save(key, data),
+  load: (key) => _load(key),
+  clear: () => _clear(),
+};
+
+if (typeof module !== 'undefined' && module.exports) {
+  module.exports = { Storage };
+}