@lzhzzzzwill/cofos 1.0.4 → 1.1.0

package/README.md

@@ -24,9 +24,9 @@ The package does not include model weights or KG/BM25 data. Those are resolved l
 
 | 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/` |
+| Student QA model | `Willlzh/COFOS` | `./.cofos/huggingface/` |
+| Runtime KG/BM25 | `Willlzh/COFOS_data/runtime` | `./.cofos/data/kg/`, `./.cofos/retrieval_store/bm25/` |
+| Local PDF chunks / manifest | user `--pdf-dir` | `./.cofos/data/processed/` |
 | Conversation history | local file | `~/.cofos_history.jsonl` |
 
 “Lazy” means the CLI checks local files first. It downloads or rebuilds only missing or changed resources.
@@ -49,6 +49,12 @@ Force PDF reparsing and BM25 rebuilding:
 npx @lzhzzzzwill/cofos --pdf-dir ./new_pdfs --rebuild-pdf-index
 ```
 
+Put model and RAG data somewhere explicit:
+
+```bash
+npx @lzhzzzzwill/cofos --cache-dir ./cofos_cache
+```
+
 Use a local merged model instead of Hugging Face:
 
 ```bash
@@ -66,15 +72,15 @@ npx @lzhzzzzwill/cofos --no-rag
 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.
+2. Uses the bundled `runtime/src` and `runtime/config` (staged from the project's `src/` and `config/` at publish time), so a full COFOS git checkout is not required.
+3. Checks the current folder cache, `./.cofos/`, for model and 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.
+PDF files are read locally and are not uploaded anywhere. Set `COFOS_CACHE_DIR` to override the COFOS cache root, or `HF_HOME` to override only the Hugging Face model cache.
 
 ## Chat Commands
 
@@ -82,8 +88,8 @@ PDF files are read locally and are not uploaded anywhere.
 |---|---|
 | `/help` | Show help |
 | `/exit` | Quit |
-| `/clear` | Clear conversation history for the session |
-| `/save` | Report persisted history path |
+| `/clear` | Clear conversation history, in the session *and* on disk |
+| `/save` | Write the current conversation history to `~/.cofos_history.jsonl` |
 | `/info` | Show model and RAG info |
 | `/topk <n>` | Change retrieval top-k |
 | `/rag off` | Disable RAG for this session |
@@ -98,6 +104,7 @@ cofos \
   --model Willlzh/COFOS \
   --config config/config.yaml \
   --pdf-dir ./new_pdfs \
+  --cache-dir ./.cofos \
   --top-k 5
 ```
 
@@ -106,6 +113,7 @@ cofos \
 | `--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 |
+| `--cache-dir` | Folder for model, KG/BM25, and parsed PDF cache; defaults to `./.cofos` |
 | `--rebuild-pdf-index` | Force PDF parsing and BM25 rebuild |
 | `--top-k` | Retrieval top-k |
 | `--max-new-tokens` | Override generation length |
@@ -122,12 +130,30 @@ cofos --help
 cofos --pdf-dir ../data/raw_pdfs
 ```
 
+### `runtime/` is generated — do not edit it
+
+`runtime/src` and `runtime/config` are **build output**, staged from the
+project's `src/` and `config/`. Those are the single source of truth; the copy
+under `runtime/` exists only so the published package is self-contained.
+
+- Fix bugs in `src/` (or `config/`), never in `runtime/`.
+- `npm pack` / `npm publish` rebuild `runtime/` automatically via the package-local
+  `prepack` wrapper when the full source checkout is present.
+- Rebuild by hand with `npm run build`, or
+  `python scripts/sync_fwdemo_runtime.py`.
+- Check for drift with `python scripts/sync_fwdemo_runtime.py --check`.
+
+The published package requires its bundled `runtime/`; the backend does not fall
+back to parent checkout folders. This keeps package tests from accidentally using
+files outside `fwdemo/`.
+
 Before publishing:
 
 ```bash
 node --check bin/cofos.js
 python -m py_compile scripts/chat.py
-npm pack --dry-run
+python -m pytest ../tests -q
+npm pack --dry-run          # runs prepack, rebuilding runtime/
 ```
 
-`npm pack --dry-run` should include `runtime/config`, `runtime/src`, `bin`, `scripts`, and `requirements.txt`, but should not include `__pycache__` or `*.pyc` files.
+`npm pack --dry-run` should include `runtime/config`, `runtime/src`, `bin`, `scripts`, `RUNTIME.md`, and `requirements.txt`, but should not include `__pycache__` or `*.pyc` files.

package/RUNTIME.md

@@ -0,0 +1,38 @@
+# COFOS fwdemo runtime model configuration
+
+This file describes the bundled runtime used by the standalone `@lzhzzzzwill/cofos` npm package.
+
+## Standalone QA path
+
+The standalone CLI does use Hugging Face by default:
+
+- Student QA model: `Willlzh/COFOS`
+- Runtime KG/BM25 data: `Willlzh/COFOS_data` under `runtime/`
+- Local cache/write location: `./.cofos/` in the folder where the user runs `cofos`
+
+On startup, fwdemo checks the current folder cache first. It downloads only missing model/data files. Use `--cache-dir`, `COFOS_CACHE_DIR`, or `HF_HOME` to override the defaults.
+
+```bash
+cofos
+cofos --pdf-dir ./new_pdfs
+cofos --cache-dir ./cofos_cache
+cofos --model /path/to/local/merged_model
+```
+
+PDFs passed with `--pdf-dir` are parsed into local chunks and merged into BM25 retrieval data under the COFOS cache root, defaulting to `./.cofos/`. They are not uploaded anywhere.
+
+## Runtime config scope
+
+The packaged `runtime/config/config.yaml` is generated from the full project config with a strict whitelist. It keeps only the fields needed by the standalone QA path: paths, retrieval, generation, prompt location, ROS normalization, and the student model pointer.
+
+The npm package does not ship internal Ollama teacher settings. The standalone QA model is loaded through Transformers from `Willlzh/COFOS` unless the user passes a local `--model` path. Runtime KG/BM25 files are downloaded from `Willlzh/COFOS_data`.
+
+## Retrieval
+
+BM25 is enabled by default. FAISS remains disabled in the standalone CLI; the packaged RAG path uses KG + BM25.
+
+```yaml
+retrieval:
+  enable_faiss: false
+  enable_bm25: true
+```

package/bin/cofos.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -9,6 +9,7 @@ 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 pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
 const DEFAULT_MODEL = process.env.COFOS_MODEL || "Willlzh/COFOS";
 const DEFAULT_CONFIG = process.env.COFOS_CONFIG || "config/config.yaml";
 
@@ -75,9 +76,12 @@ function render() {
 function cmdExist(c) { return spawnSync(c, ["--version"], { encoding: "utf-8", stdio: "pipe" }).status === 0; }
 function findPy() { return cmdExist("python3") ? "python3" : cmdExist("python") ? "python" : null; }
 
+// Only the modules the chat backend actually imports for the standalone merged-model path.
+const REQUIRED_MODULES = "import transformers, torch, yaml, huggingface_hub, pdfplumber, rank_bm25";
+
 function ensureDeps(py) {
   console.log("[cofos] Checking Python dependencies …");
-  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;
+  if (spawnSync(py, ["-c", `${REQUIRED_MODULES}; 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); }
@@ -88,7 +92,7 @@ function ensureDeps(py) {
 function main() {
   if (process.argv.includes("-h") || process.argv.includes("--help")) {
     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("  Usage:  cofos [--model PATH] [--config PATH] [--pdf-dir DIR] [--cache-dir DIR] [--top-k N] [--no-rag]\n");
     console.log("  Commands in chat:");
     console.log("    /help        Show this help");
     console.log("    /exit        Quit");
@@ -99,48 +103,86 @@ function main() {
     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("    --cache-dir DIR        Store model/data cache here (default: ./.cofos)");
     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();
-
-  const py = findPy();
-  if (!py) { console.error("[cofos] Python not found."); process.exit(1); }
-  if (!existsSync(chatScript)) { console.error("[cofos] Missing script:", chatScript); process.exit(1); }
-  ensureDeps(py);
-
-  console.log("  Loading COFOS 9B + RAG backend from Hugging Face … first run may take a while\n");
-
+  // Parse and validate before the banner and the dependency check, so a bad
+  // flag fails immediately instead of after a slow pip round-trip.
   const cliArgs = process.argv.slice(2);
   let modelPath = DEFAULT_MODEL;
   let configPath = DEFAULT_CONFIG;
   let topK = "5";
   let pdfDir = null;
+  let cacheDir = process.env.COFOS_CACHE_DIR ? resolve(process.env.COFOS_CACHE_DIR) : resolve(process.cwd(), ".cofos");
   let rebuildPdfIndex = false;
   const backendArgs = [chatScript];
+
+  const die = (msg) => { console.error("[cofos] " + msg); process.exit(1); };
+  // A flag placed last used to read `undefined` as its value, which then made
+  // spawn() throw an opaque TypeError instead of reporting the bad usage.
+  const value = (i, flag) => {
+    const v = cliArgs[i];
+    if (v === undefined || v.startsWith("--")) die(`Missing value for ${flag}`);
+    return v;
+  };
+
   for (let i = 0; i < cliArgs.length; i++) {
     const arg = cliArgs[i];
     if (arg === "--model" || arg === "--merged-model-path") {
-      modelPath = cliArgs[++i];
+      modelPath = value(++i, arg);
     } else if (arg === "--config") {
-      configPath = cliArgs[++i];
+      configPath = value(++i, arg);
     } else if (arg === "--top-k") {
-      topK = cliArgs[++i];
+      topK = value(++i, arg);
+      if (!/^\d+$/.test(topK) || Number(topK) < 1) die(`--top-k must be a positive integer, got "${topK}"`);
     } else if (arg === "--pdf-dir") {
-      pdfDir = cliArgs[++i];
+      pdfDir = resolve(value(++i, arg));
+      if (!existsSync(pdfDir)) die(`--pdf-dir does not exist: ${pdfDir}`);
+    } else if (arg === "--cache-dir") {
+      cacheDir = resolve(value(++i, arg));
     } else if (arg === "--rebuild-pdf-index") {
       rebuildPdfIndex = true;
     } else if (arg === "--no-rag") {
       backendArgs.push("--no-rag");
+    } else {
+      die(`Unknown option: ${arg}\n         Run "cofos --help" for usage.`);
     }
   }
   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, backendArgs, { stdio: ["pipe", "pipe", "pipe"], encoding: "utf-8" });
+  render();
+
+  const py = findPy();
+  if (!py) die("Python not found. Install Python 3.9+ and re-run.");
+  if (!existsSync(chatScript)) die(`Missing script: ${chatScript}`);
+  ensureDeps(py);
+
+  console.log("  Loading COFOS 9B + RAG backend from Hugging Face … first run may take a while\n");
+
+  const backendEnv = {
+    ...process.env,
+    COFOS_CACHE_DIR: cacheDir,
+    HF_HOME: process.env.HF_HOME || join(cacheDir, "huggingface"),
+    HF_HUB_DISABLE_XET: process.env.HF_HUB_DISABLE_XET || "1",
+    HF_HUB_ENABLE_HF_TRANSFER: process.env.HF_HUB_ENABLE_HF_TRANSFER || "0",
+    HF_HUB_DOWNLOAD_TIMEOUT: process.env.HF_HUB_DOWNLOAD_TIMEOUT || "120",
+    HF_HUB_ETAG_TIMEOUT: process.env.HF_HUB_ETAG_TIMEOUT || "30",
+  };
+  const proc = spawn(py, backendArgs, {
+    stdio: ["pipe", "pipe", "pipe"],
+    env: backendEnv,
+  });
+
+  // `encoding` is not a spawn() option — without setEncoding each Buffer chunk
+  // is decoded on its own, so a multi-byte character (·OH, ¹O₂, any Chinese)
+  // straddling a chunk boundary comes out as mojibake.
+  proc.stdout.setEncoding("utf-8");
+  proc.stderr.setEncoding("utf-8");
 
   let buf = "", ready = false, generating = false, closed = false;
   const inputQ = [];
@@ -162,7 +204,9 @@ function main() {
       }
       return;
     }
-    if (!generating) return;
+    // Anything arriving while no answer is in flight is not part of a response;
+    // dropping it keeps it from being prepended to the next one.
+    if (!generating) { buf = ""; return; }
 
     // Scan for DONE marker — stream everything before it.
     const di = buf.indexOf(DONE);
@@ -196,9 +240,23 @@ function main() {
     closed = true;
     if (c && c !== 0) console.error("[cofos] Python exited with code", c);
     try { rl.close(); } catch (_) {}
-    process.exit(c ?? 0);
+    // Let queued stdout writes flush before tearing the process down.
+    process.exitCode = c ?? 0;
   });
 
+  function shutdown() {
+    if (closed) return;
+    closed = true;
+    try { proc.stdin.end(); } catch (_) {}
+    try { rl.close(); } catch (_) {}
+    proc.kill("SIGTERM");
+  }
+
+  // Ctrl+C and Ctrl+D should stop the backend instead of orphaning it.
+  rl.on("SIGINT", () => { console.log("\n[cofos] Interrupted."); shutdown(); });
+  rl.on("close", () => { if (!closed) shutdown(); });
+  process.on("SIGTERM", shutdown);
+
   function drain() {
     while (inputQ.length) {
       const line = inputQ.shift();
@@ -244,9 +302,11 @@ function main() {
       return;
     }
     if (/^\/(info)$/.test(input)) {
-      console.log("\n  COFOS CLI — v1.0.0");
+      console.log(`\n  COFOS CLI — v${pkg.version}`);
       console.log("  Model:  Willlzh/COFOS (Hugging Face)");
       console.log("  RAG:    Willlzh/COFOS_data/runtime (KG + BM25) + optional --pdf-dir BM25 evidence");
+      console.log(`  Cache:  ${cacheDir}`);
+      console.log(`  HF:     ${backendEnv.HF_HOME}`);
       console.log("  Engine: StudentAdapterInference + transformers + PyTorch");
       console.log("  Hist:   ~/.cofos_history.jsonl\n");
       ask(); return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lzhzzzzwill/cofos",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "COFOS 9B + RAG chat CLI with optional local PDF ingestion.",
   "type": "module",
   "bin": {
@@ -9,16 +9,24 @@
   "files": [
     "bin",
     "scripts/chat.py",
+    "scripts/sync_runtime.py",
+    "RUNTIME.md",
     "runtime/config/*.yaml",
-    "runtime/config/*.md",
-    "runtime/src/data_processing/*.py",
+    "runtime/src/data_processing/__init__.py",
+    "runtime/src/data_processing/parse_pdf_text.py",
+    "runtime/src/data_processing/utils.py",
     "runtime/src/inference/*.py",
-    "runtime/src/retrieval/*.py",
+    "runtime/src/retrieval/__init__.py",
+    "runtime/src/retrieval/build_bm25_index.py",
+    "runtime/src/retrieval/retrieve_evidence.py",
+    "runtime/src/retrieval/text_search.py",
     "requirements.txt"
   ],
   "scripts": {
     "start": "node ./bin/cofos.js",
-    "test": "node ./bin/cofos.js --help"
+    "test": "node ./bin/cofos.js --help",
+    "build": "python3 scripts/sync_runtime.py",
+    "prepack": "python3 scripts/sync_runtime.py"
   },
   "keywords": [
     "cli",

package/requirements.txt

@@ -1,10 +1,7 @@
 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