COFOS CLI

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.

npx @lzhzzzzwill/cofos

COFOS uses a plain terminal interface, so normal terminal scrollback, mouse selection, copy, and Ctrl+C work as expected.

Runtime Model

The standalone npm package includes a minimal Python runtime under runtime/:

fwdemo/
├── bin/cofos.js
├── scripts/chat.py
├── scripts/sync_runtime.py
├── runtime/
│   ├── config/
│   └── src/
├── RUNTIME.md
└── requirements.txt

The package does not include model weights or KG/BM25 data. Those are resolved lazily:

| Resource | Default | Local location | |---|---|---| | 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.

Quick Start

npx @lzhzzzzwill/cofos

Use local PDFs as additional BM25 evidence:

npx @lzhzzzzwill/cofos --pdf-dir ./new_pdfs

Force PDF reparsing and BM25 rebuilding:

npx @lzhzzzzwill/cofos --pdf-dir ./new_pdfs --rebuild-pdf-index

Put model and RAG data somewhere explicit:

npx @lzhzzzzwill/cofos --cache-dir ./cofos_cache

Use a local merged model instead of Hugging Face:

npx @lzhzzzzwill/cofos --model /path/to/merged_model

Disable RAG for a session:

npx @lzhzzzzwill/cofos --no-rag

Show model reasoning scaffold when emitted:

npx @lzhzzzzwill/cofos --show-reasoning

Select the inference device explicitly:

npx @lzhzzzzwill/cofos --device cuda   # CUDA GPU machine
npx @lzhzzzzwill/cofos --device mps    # Apple Silicon Mac
npx @lzhzzzzwill/cofos --device cpu    # CPU fallback, slow
npx @lzhzzzzwill/cofos --device mps --mps-load-mode direct  # advanced Mac path

Ask once and exit, useful for scripts and smoke tests:

npx @lzhzzzzwill/cofos -p "What ROS does TT-T-COF generate under visible-light photocatalysis?"

Startup Behavior

On startup, the CLI does the following:

1. Finds Python and checks required Python packages.
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. Selects the inference backend: CUDA first, then Apple Silicon MPS, then CPU.
9. 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. Set COFOS_CACHE_DIR to override the COFOS cache root, or HF_HOME to override only the Hugging Face model cache.

Chat Commands

| Command | Description | |---|---| | /help | Show help | | /exit | Quit | | /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 | | /rag on | Re-enable RAG for this session |

Multi-line questions are supported by ending a line with \.

CLI Options

cofos \
  --model Willlzh/COFOS \
  --config config/config.yaml \
  --pdf-dir ./new_pdfs \
  --cache-dir ./.cofos \
  --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 | | --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 | | --device | auto, cuda, mps, or cpu; defaults to auto | | --dtype | auto, float32, float16, or bfloat16; defaults to auto | | --mps-load-mode | staged or direct for Apple Silicon; defaults to staged | | -p, --prompt | Ask one question and exit | | --show-reasoning | Show emitted reasoning scaffold in dim text before the final answer | | --max-new-tokens | Override generation length | | --no-rag | Run without KG/BM25 retrieval |

Development

From this repository:

cd fwdemo
npm link
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 from fwdemo/ with npm run build.
• From the repository root, rebuild with python scripts/sync_fwdemo_runtime.py.
• The package-local wrapper fwdemo/scripts/sync_runtime.py delegates to the root sync script in a source checkout, and only validates bundled files in an installed package.
• 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:

node --check bin/cofos.js
python -m py_compile scripts/chat.py
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, RUNTIME.md, and requirements.txt, but should not include __pycache__ or *.pyc files.