spencermountain/compromise

compromise – a lightweight JavaScript NLP library

What it is – compromise (formerly nlp‑compromise) is a small, fast, pure‑JavaScript library that turns raw English text into a manipulable data structure. It focuses on practical, rule‑based processing rather than deep learning, offering tokenisation, part‑of‑speech tagging, lemmatisation, and a handful of higher‑level helpers (numbers, dates, contractions, etc.).

Why it matters – For many web‑oriented projects you need quick, on‑the‑fly language handling without pulling in a multi‑hundred‑megabyte model. compromise fits that niche: the minified bundle is ~250 KB, it runs in the browser or Node, and can process about 1 MB of text per second.

Key features (as described in the README)

• Three‑tier API – compromise/one (tokeniser), compromise/two (POS tagger & grammar interpreter), compromise/three (phrase‑level utilities). You can load only the tier you need.
• Tag set – 83 built‑in tags (e.g., #Verb, #Noun, #FirstName). Tags are hierarchical and can be inspected with debug() or verbose('tagger').
• Match syntax – a mini‑language (doc.match('#Adjective of times')) lets you query the document with patterns similar to regular expressions but aware of tags.
• Convenient transforms – change tense (doc.verbs().toPastTense()), pluralise nouns, expand/contract contractions, add/subtract numbers, etc.
• Data extraction – doc.json() returns a structured representation (terms, normalised forms, computed metadata like syllables, money, fractions).
• Extensibility – plug‑in additional modules such as compromise-speech for syllable counting.
• Client‑side ready – can be loaded via a <script> tag from a CDN, making it trivial to add to static pages.

Typical use‑cases

• Simple text‑cleaning or normalisation before sending data to a larger AI pipeline.
• Building chat‑bots or voice assistants that need quick intent detection without a heavyweight model.
• Generating or editing content on the fly (e.g., auto‑pluralising nouns, converting verbs to past tense).
• Extracting structured information (numbers, dates, places) from user‑generated text in a web app.

Strengths

• Size & speed – tiny bundle, can run on every key‑press.
• Zero‑dependency, pure JS – works in any environment that runs JavaScript.
• Deterministic – rule‑based output is predictable, which is useful for templating and rule‑driven agents.
• Modular – load only the tier you need to keep the footprint minimal.

Limitations

• Accuracy trade‑off – the README admits it is “not as smart as you’d think”; it won’t match the performance of modern transformer‑based parsers on ambiguous or domain‑specific text.
• English‑centric – core library targets English; other languages are separate forks (French, German, Italian, Spanish) and may lag behind.
• Rule‑based – limited ability to learn new patterns without manually extending the lexicon.

Getting started

npm install compromise   # or use a CDN script tag

import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')
console.log(doc.verbs().toPastTense().text()) // "she sold seashells by the seashore."

Further reading – The repo ships extensive markdown docs (docs/api.md, docs/match-syntax.md, etc.) and a collection of Observable notebooks that illustrate performance, internals, and the tag graph.

---

All statements are taken directly from the repository’s README; no external claims have been added.