Getting started

nlpgraph turns a sentence into a labeled Universal-Dependencies dependency graph with POS tags — offline, deterministic (byte-identical output across runs), on CPU, with no server, no Python/Java, and no LLM. It runs in Node and the browser from one codebase.

Install

npm install nlpgraph

The package is code only (~18 kB). The ONNX Runtime engine is pulled in automatically as a dependency, and the model weights (~288 MB) are downloaded from Cloudflare R2 on first use, then cached locally (~/.cache/nlpgraph) and reused offline.

Parse a sentence (Node)

import { NlpGraph } from 'nlpgraph';

const nlp = await NlpGraph.load();   // first call downloads + caches the model
const doc = await nlp.parse('Access rights shall be reviewed annually by the system owner.');

for (const t of doc[0].tokens) console.log(t.id, t.form, t.upos, t.head, t.deprel);
// 1 Access   NOUN 2 compound
// 2 rights   NOUN 5 nsubj:pass
// 3 shall    AUX  5 aux
// 4 be       AUX  5 aux:pass
// 5 reviewed VERB 0 root
// 6 annually ADV  5 advmod
// ...
// 10 owner   NOUN 5 obl:agent

Each token is a DepToken = { id, form, upos, head, deprel }, aligned to the CoNLL-U column model (head is 1-indexed, 0 = ROOT).

Preload the model (CI/CD & Docker)

To avoid a runtime download, bake the model into your image at build time:

RUN npx nlpgraph download            # downloads into ~/.cache/nlpgraph (or $NLPGRAPH_CACHE_DIR)

npx nlpgraph download --help                 # options
npx nlpgraph download --dir ./models         # download to an explicit directory
npx nlpgraph download --model xsmall         # smaller (~145 MB) variant

Resolution order for load(): opts.modelDir → NLPGRAPH_MODEL_DIR → a local ./models dir → the on-disk cache → download from R2. Override the cache root with NLPGRAPH_CACHE_DIR and the model host with NLPGRAPH_BASE_URL. Everything is cross-platform and dependency-free.