@lzhzzzzwill/cofos 1.0.0 → 1.0.2

package/README.md

@@ -1,112 +1,133 @@
 # COFOS CLI
 
-一个本地 LLM 聊天 CLI：3D 立体欢迎界面 + Hugging Face 模型对话。
+COFOS CLI is a standalone Node.js command line wrapper around the COFOS Python runtime. It starts a persistent Python backend, loads the COFOS student model, prepares KG/BM25 runtime data when missing, and can ingest local PDFs as extra retrieval evidence.
 
 ```bash
-npx cofos
+npx @lzhzzzzwill/cofos
 ```
 
-```
-╭─────────────────────────────────────────────────────────╮
-│   ██████╗     ██████╗    ███████╗    ██████╗  ███████╗ │
-│  ██╔════╝    ██╔═══██╗   ██╔════╝   ██╔═══██╗ ██╔════╝ │
-│  ██║         ██║   ██║   ███████╗   ██║   ██║ ███████╗ │
-│  ██║         ██║   ██║   ██╔════╝   ██║   ██║ ╚════██║ │
-│  ╚██████╗    ╚██████╔╝   ██║        ╚██████╔╝ ███████║ │
-│   ╚═════╝     ╚═════╝    ╚═╝         ╚═════╝  ╚══════╝ │
-│    ░░░░░░░     ░░░░░░░    ░░░         ░░░░░░░  ░░░░░░░  │  ← 3D shadow
-│                    Welcome to COFOS CLI — local LLM chat  │
-│              Type  /help  for commands  ·  /exit  to quit│
-╰─────────────────────────────────────────────────────────╯
-  cofos > What is a MOF material?
-[Model streams response...]
-  cofos > Tell me more about its applications.
+## Runtime Model
+
+The standalone npm package includes a minimal Python runtime under `runtime/`:
+
+```text
+fwdemo/
+├── bin/cofos.js
+├── scripts/chat.py
+├── runtime/
+│   ├── config/
+│   └── src/
+└── requirements.txt
 ```
 
-## 快速开始
+The package does not include model weights or KG/BM25 data. Those are resolved lazily:
 
-```bash
-# 直接运行
-npx cofos
+| Resource | Default | Local location |
+|---|---|---|
+| Student QA model | `Willlzh/COFOS` | Hugging Face cache |
+| Runtime KG/BM25 | `Willlzh/COFOS_data/runtime` | `~/.cache/cofos/` |
+| Local PDF chunks / manifest | user `--pdf-dir` | `~/.cache/cofos/data/processed/` |
+| Conversation history | local file | `~/.cofos_history.jsonl` |
 
-# 或本地
-git clone <repo> && cd demo && npm link
-cofos
-```
+“Lazy” means the CLI checks local files first. It downloads or rebuilds only missing or changed resources.
+
+## Quick Start
 
-首次运行会自动安装 Python 依赖并下载模型（约 30-60 秒）。
+```bash
+npx @lzhzzzzwill/cofos
+```
 
-## 命令
+Use local PDFs as additional BM25 evidence:
 
-| 命令 | 说明 |
-|------|------|
-| `/help` | 显示帮助 |
-| `/exit` | 退出 |
-| `/clear` | 清屏重新显示欢迎界面 |
-| `/info` | 显示模型和版本信息 |
-| `/model <id>` | 切换 Hugging Face 模型 |
+```bash
+npx @lzhzzzzwill/cofos --pdf-dir ./new_pdfs
+```
 
-## 项目结构
+Force PDF reparsing and BM25 rebuilding:
 
+```bash
+npx @lzhzzzzwill/cofos --pdf-dir ./new_pdfs --rebuild-pdf-index
 ```
-├── package.json          # npm 包配置，bin → cofos
-├── requirements.txt      # Python 依赖：transformers + torch
-├── .gitignore
-├── bin/
-│   └── cofos.js          # Node.js CLI：3D 前端 + 子进程管理
-└── scripts/
-    └── chat.py           # Python 推理：加载模型、生成回复
+
+Use a local merged model instead of Hugging Face:
+
+```bash
+npx @lzhzzzzwill/cofos --model /path/to/merged_model
 ```
 
-## 架构概览
+Disable RAG for a session:
 
+```bash
+npx @lzhzzzzwill/cofos --no-rag
 ```
-终端                          Node.js (cofos.js)                    Python (chat.py)
- │                                │                                      │
- │  cofos                         │                                      │
- │────────────────────────────────>│                                      │
- │                                │  spawn python3 scripts/chat.py       │
- │                                │──────────────────────────────────────>│
- │                                │                                      │ 加载模型
- │                                │  stdout ← ===READY===                │
- │                                │<──────────────────────────────────────│
- │  显示 3D 欢迎界面 + 提示符     │                                      │
- │<───────────────────────────────│                                      │
- │                                │                                      │
- │  用户输入 "What is MOF?"      │                                      │
- │────────────────────────────────>│                                      │
- │                                │  stdin → "What is MOF?"              │
- │                                │──────────────────────────────────────>│
- │                                │                                      │ 生成 token
- │                                │  stdout ← 流式 token                 │
- │  流式显示回复                 │<──────────────────────────────────────│
- │<───────────────────────────────│                                      │
- │                                │  stdout ← \n===DONE===\n             │
- │                                │<──────────────────────────────────────│
- │  显示 "cofos >" 等待下一条    │                                      │
- │<───────────────────────────────│                                      │
+
+## Startup Behavior
+
+On startup, the CLI does the following:
+
+1. Finds Python and checks required Python packages.
+2. Uses bundled `runtime/src` and `runtime/config`, so a full COFOS git checkout is not required.
+3. Checks `~/.cache/cofos/` for KG/BM25 runtime data.
+4. Downloads missing runtime files from `Willlzh/COFOS_data` only if needed.
+5. If `--pdf-dir` is provided, scans PDF names, sizes, and mtimes.
+6. Re-parses PDFs only when the folder contents changed or `--rebuild-pdf-index` is passed.
+7. Merges ROS-related PDF chunks into BM25 retrieval.
+8. Loads the model once and keeps the Python backend alive for the whole chat session.
+
+PDF files are read locally and are not uploaded anywhere.
+
+## Chat Commands
+
+| Command | Description |
+|---|---|
+| `/help` | Show help |
+| `/exit` | Quit |
+| `/clear` | Clear conversation history for the session |
+| `/save` | Report persisted history path |
+| `/info` | Show model and RAG info |
+| `/topk <n>` | Change retrieval top-k |
+| `/rag off` | Disable RAG for this session |
+| `/rag on` | Re-enable RAG for this session |
+
+Multi-line questions are supported by ending a line with `\`.
+
+## CLI Options
+
+```bash
+cofos \
+  --model Willlzh/COFOS \
+  --config config/config.yaml \
+  --pdf-dir ./new_pdfs \
+  --top-k 5
 ```
 
-## 技术栈
+| Option | Description |
+|---|---|
+| `--model`, `--merged-model-path` | Hugging Face repo id or local merged model path |
+| `--config` | Config path; defaults to bundled runtime config |
+| `--pdf-dir` | Folder of PDFs to add as extra BM25 evidence |
+| `--rebuild-pdf-index` | Force PDF parsing and BM25 rebuild |
+| `--top-k` | Retrieval top-k |
+| `--max-new-tokens` | Override generation length |
+| `--no-rag` | Run without KG/BM25 retrieval |
 
-| 层 | 技术 | 职责 |
-|----|------|------|
-| CLI 前端 | Node.js (ESM) | 终端 UI、子进程管理、管道通信 |
-| 模型后端 | Python + transformers | 模型加载、token 生成、流式输出 |
-| 模型 | SmolLM2-360M-Instruct (HF) | 对话推理 |
-| 通信 | stdin/stdout 管道 | 进程间消息传递 |
-| 分發 | npm | 包管理、全局命令、npx |
+## Development
 
-## 依赖
+From this repository:
 
-- Node.js ≥ 18
-- Python 3.8+
-- 首次运行需联网（下载模型，~360MB）
+```bash
+cd fwdemo
+npm link
+cofos --help
+cofos --pdf-dir ../data/raw_pdfs
+```
 
-## 开发
+Before publishing:
 
 ```bash
-npm link          # 注册全局命令
-cofos             # 启动
-npm run start     # 或直接 node ./bin/cofos.js
+node --check bin/cofos.js
+python -m py_compile scripts/chat.py
+npm pack --dry-run
 ```
+
+`npm pack --dry-run` should include `runtime/config`, `runtime/src`, `bin`, `scripts`, and `requirements.txt`, but should not include `__pycache__` or `*.pyc` files.

package/bin/cofos.js

@@ -9,10 +9,15 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = resolve(__dirname, "..");
 const chatScript = join(root, "scripts", "chat.py");
 const reqFile = join(root, "requirements.txt");
+const DEFAULT_MODEL = process.env.COFOS_MODEL || "Willlzh/COFOS";
+const DEFAULT_CONFIG = process.env.COFOS_CONFIG || "config/config.yaml";
 
 /* ─── ANSI ─── */
 const R = "\x1b[0m", B = "\x1b[1m", D = "\x1b[2m";
-const C = "\x1b[96m", W = "\x1b[97m", G = "\x1b[90m";
+const C = "\x1b[96m", W = "\x1b[97m", G = "\x1b[90m", Y = "\x1b[93m";
+
+/* ─── Protocol markers ─── */
+const READY = "===READY===", RESPONSE = "===RESPONSE===", DONE = "===DONE===";
 
 /* ─── 3D COFOS art ─── */
 const C_ = [" ██████╗ ","██╔════╝ ","██║      ","██║      ","╚██████╗ "," ╚═════╝ "];
@@ -57,9 +62,9 @@ function render() {
   l.push(emp(w));
   l.push(sep(w));
   l.push(emp(w));
-  l.push(cnt(W + B + "Welcome to COFOS CLI — local LLM chat" + R, w));
+  l.push(cnt(W + B + "Welcome to COFOS CLI — 9B + RAG chat (Willlzh/COFOS)" + R, w));
   l.push(emp(w));
-  l.push(cnt(G + "Type  /help  for commands  ·  /exit  to quit" + R, w));
+  l.push(cnt(G + "Type /help · /exit · /topk 5 · /rag off · \\ for multiline" + R, w));
   l.push(emp(w));
   l.push(bot(w));
   console.log(l.join("\n"));
@@ -72,7 +77,7 @@ function findPy() { return cmdExist("python3") ? "python3" : cmdExist("python")
 
 function ensureDeps(py) {
   console.log("[cofos] Checking Python dependencies …");
-  if (spawnSync(py, ["-c", "import transformers, torch; print('ok')"], { encoding: "utf-8", stdio: "pipe" }).status === 0) return;
+  if (spawnSync(py, ["-c", "import transformers, torch, yaml, huggingface_hub, requests, numpy, pdfplumber; import peft; import rank_bm25; print('ok')"], { encoding: "utf-8", stdio: "pipe" }).status === 0) return;
   console.log("[cofos] Installing Python dependencies (first run, may take a while) …");
   const r = spawnSync(py, ["-m", "pip", "install", "-r", reqFile], { encoding: "utf-8", stdio: "inherit" });
   if (r.status !== 0) { console.error("[cofos] Failed to install Python dependencies."); process.exit(1); }
@@ -82,7 +87,21 @@ function ensureDeps(py) {
 
 function main() {
   if (process.argv.includes("-h") || process.argv.includes("--help")) {
-    console.log("\n  COFOS CLI — local LLM chat\n  Usage:  cofos\n"); process.exit(0);
+    console.log("\n  COFOS CLI — 9B + RAG chat (Willlzh/COFOS)\n");
+    console.log("  Usage:  cofos [--model PATH] [--config PATH] [--pdf-dir DIR] [--top-k N] [--no-rag]\n");
+    console.log("  Commands in chat:");
+    console.log("    /help        Show this help");
+    console.log("    /exit        Quit");
+    console.log("    /clear       Clear screen + conversation history");
+    console.log("    /save        Persist conversation history");
+    console.log("    /info        Show model and RAG info");
+    console.log("    /topk N      Set retrieval top-k");
+    console.log("    /rag on|off  Enable / disable RAG\n");
+    console.log("  Startup options:");
+    console.log("    --pdf-dir DIR          Add PDFs from DIR as extra BM25 evidence");
+    console.log("    --rebuild-pdf-index    Force reparsing PDFs and rebuilding BM25\n");
+    console.log("  Multi-line: end a line with \\ to continue on the next line.\n");
+    process.exit(0);
   }
 
   render();
@@ -92,42 +111,84 @@ function main() {
   if (!existsSync(chatScript)) { console.error("[cofos] Missing script:", chatScript); process.exit(1); }
   ensureDeps(py);
 
-  console.log("  Loading model … (30–60 s on first run)\n");
+  console.log("  Loading COFOS 9B + RAG backend from Hugging Face … first run may take a while\n");
+
+  const cliArgs = process.argv.slice(2);
+  let modelPath = DEFAULT_MODEL;
+  let configPath = DEFAULT_CONFIG;
+  let topK = "5";
+  let pdfDir = null;
+  let rebuildPdfIndex = false;
+  const backendArgs = [chatScript];
+  for (let i = 0; i < cliArgs.length; i++) {
+    const arg = cliArgs[i];
+    if (arg === "--model" || arg === "--merged-model-path") {
+      modelPath = cliArgs[++i];
+    } else if (arg === "--config") {
+      configPath = cliArgs[++i];
+    } else if (arg === "--top-k") {
+      topK = cliArgs[++i];
+    } else if (arg === "--pdf-dir") {
+      pdfDir = cliArgs[++i];
+    } else if (arg === "--rebuild-pdf-index") {
+      rebuildPdfIndex = true;
+    } else if (arg === "--no-rag") {
+      backendArgs.push("--no-rag");
+    }
+  }
+  backendArgs.push("--merged-model-path", modelPath, "--config", configPath, "--top-k", topK);
+  if (pdfDir) backendArgs.push("--pdf-dir", pdfDir);
+  if (rebuildPdfIndex) backendArgs.push("--rebuild-pdf-index");
 
-  const proc = spawn(py, [chatScript], { stdio: ["pipe", "pipe", "inherit"], encoding: "utf-8" });
+  const proc = spawn(py, backendArgs, { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" });
 
   let buf = "", ready = false, generating = false, closed = false;
   const inputQ = [];
-  const rl = createInterface({ input: process.stdin });
+  const rl = createInterface({ input: process.stdin, terminal: true });
   rl.on("line", (l) => { inputQ.push(l); });
 
+  // Forward Python stderr (status / progress messages) to our stderr.
+  proc.stderr.on("data", (chunk) => { process.stderr.write(chunk); });
+
   proc.stdout.on("data", (chunk) => {
-    try {
-      buf += chunk;
-      if (!ready) {
-        const i = buf.indexOf("===READY===");
-        if (i !== -1) {
-          ready = true;
-          buf = buf.slice(i + 10);
-          if (buf[0] === "\n") buf = buf.slice(1);
-          drain();
-        }
-        return;
-      }
-      if (!generating) return;
-      const i = buf.indexOf("\n===DONE===");
+    buf += chunk;
+    if (!ready) {
+      const i = buf.indexOf(READY);
       if (i !== -1) {
-        process.stdout.write(buf.slice(0, i));
-        buf = buf.slice(i + 11);
+        ready = true;
+        buf = buf.slice(i + READY.length);
         if (buf[0] === "\n") buf = buf.slice(1);
-        generating = false;
-        console.log("");
         drain();
-      } else {
-        const k = 10;
-        if (buf.length > k) { process.stdout.write(buf.slice(0, -k)); buf = buf.slice(-k); }
       }
-    } catch (_) {}
+      return;
+    }
+    if (!generating) return;
+
+    // Scan for DONE marker — stream everything before it.
+    const di = buf.indexOf(DONE);
+    if (di !== -1) {
+      // Flush any pre-DONE content (cleaned of RESPONSE marker).
+      let pre = buf.slice(0, di);
+      const ri = pre.indexOf(RESPONSE);
+      if (ri !== -1) pre = pre.slice(ri + RESPONSE.length);
+      if (pre) process.stdout.write(pre);
+      buf = buf.slice(di + DONE.length);
+      if (buf[0] === "\n") buf = buf.slice(1);
+      generating = false;
+      console.log("");
+      drain();
+    } else {
+      // Stream buffered content, keeping only enough tail to catch a
+      // partial DONE marker.
+      const keep = DONE.length;
+      if (buf.length > keep) {
+        let out = buf.slice(0, -keep);
+        const ri = out.indexOf(RESPONSE);
+        if (ri !== -1) out = out.slice(ri + RESPONSE.length);
+        if (out) process.stdout.write(out);
+        buf = buf.slice(-keep);
+      }
+    }
   });
 
   proc.on("error", (e) => { console.error("[cofos] Python error:", e.message); process.exit(1); });
@@ -151,30 +212,47 @@ function main() {
     try { rl.question(C + "  cofos " + R, handle); } catch (_) {}
   }
 
+  /* ─── multi-line accumulator ─── */
+  let mlBuf = [];
+
   function handle(input) {
+    // Multi-line continuation: lines ending with "\"
+    if (input.endsWith("\\")) {
+      mlBuf.push(input.slice(0, -1));
+      try { rl.question(G + "  ...   " + R, handle); } catch (_) {}
+      return;
+    }
+    if (mlBuf.length > 0) {
+      mlBuf.push(input);
+      input = mlBuf.join("\n");
+      mlBuf = [];
+    }
+
     input = input.trim();
     if (!input) { ask(); return; }
 
+    // Local-only commands (don't hit the backend).
     if (/^\/(exit|quit)$/.test(input)) { proc.stdin.write("/exit\n"); proc.stdin.end(); return; }
     if (/^\/(help)$/.test(input)) {
-      console.log("\n  Commands:\n    /help    Show help\n    /exit    Exit\n    /clear   Clear screen\n    /info    Model info\n    /model   Switch model\n");
-      ask(); return;
-    }
-    if (/^\/(clear)$/.test(input)) { render(); console.log(""); ask(); return; }
-    if (/^\/(info)$/.test(input)) {
-      console.log("\n  COFOS CLI — v1.0.0");
-      console.log("  Model: HuggingFaceTB/SmolLM2-360M-Instruct");
-      console.log("  Backend: transformers + PyTorch\n");
+      console.log("\n  Commands:\n    /help        Show help\n    /exit        Quit\n    /clear       Clear conversation history\n    /save        Persist conversation history\n    /info        Model and RAG info\n    /topk N      Set retrieval top-k\n    /rag on|off  Enable/disable RAG\n\n  Multi-line: end a line with \\ to continue.\n");
       ask(); return;
     }
-    if (/^\/model\s/.test(input)) {
-      const m = input.slice(7).trim();
-      console.log("[cofos] Switching model to", m);
+    if (/^\/(clear)$/.test(input)) {
+      mlBuf = [];
       proc.stdin.write(input + "\n");
       generating = true;
       return;
     }
+    if (/^\/(info)$/.test(input)) {
+      console.log("\n  COFOS CLI — v1.0.0");
+      console.log("  Model:  Willlzh/COFOS (Hugging Face)");
+      console.log("  RAG:    Willlzh/COFOS_data/runtime (KG + BM25) + optional --pdf-dir BM25 evidence");
+      console.log("  Engine: StudentAdapterInference + transformers + PyTorch");
+      console.log("  Hist:   ~/.cofos_history.jsonl\n");
+      ask(); return;
+    }
 
+    // Forward to backend.
     generating = true;
     proc.stdin.write(input + "\n");
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lzhzzzzwill/cofos",
-  "version": "1.0.0",
-  "description": "A local LLM chat CLI with a 3D stereoscopic welcome screen.",
+  "version": "1.0.2",
+  "description": "COFOS 9B + RAG chat CLI with optional local PDF ingestion.",
   "type": "module",
   "bin": {
     "cofos": "bin/cofos.js"
@@ -9,6 +9,7 @@
   "files": [
     "bin",
     "scripts",
+    "runtime",
     "requirements.txt"
   ],
   "scripts": {

package/requirements.txt

@@ -1,2 +1,10 @@
 transformers>=4.40.0
 torch
+accelerate
+peft
+PyYAML
+rank-bm25
+huggingface_hub>=0.20.0
+requests>=2.31.0
+numpy>=1.24.0
+pdfplumber>=0.9.0