Compromise NLP Library

Using compromise

Compromise is a rule-based English NLP library that runs locally in Node.js and browsers. Its tagging and transformations are heuristic; it does not provide a dependency parse tree, semantic understanding, or an LLM service.

Choose the API for the installed version

Inspect the project's compromise version, import, and registered plugins before choosing APIs. Prefer the full import nlp from 'compromise' for ordinary use:

Use the existing module system; CommonJS can use const nlp = require('compromise'). If a method is missing, check the build tier, version, and plugins before inventing a replacement API. Specialized transforms belong on specialized selections: use .verbs().toPastTense(), not .match('#Verb').toPastTense().

Read only the detailed docs needed for the task. These paths resolve inside this repository and packages that ship this skill alongside docs/:

• API: method names, arguments, and specialized selection methods.
• Match syntax: pattern operators and capture groups.
• Tag definitions: valid tags and their hierarchy.
• Concepts: document, View, Term, and mutation semantics.
• Recipes: task-specific starting points.
• Tagging differences: conventions when comparing other taggers.

If this skill was installed separately, look for these files in the consuming project's node_modules/compromise/docs/ or its resolved package directory. If unavailable, consult the upstream repository at the installed version's tag when available. Do not assume the latest docs describe an older installed version. When docs and behavior disagree, reproduce against that version and inspect its source/types.

Keep the document and selection distinct

nlp(text) returns a View of the whole document. Selections return Views sharing that document. Transforms mutate the shared document; reading .text() from a selection gives only that fragment. Keep the whole-document variable when the requested output is the rewritten input:

import nlp from 'compromise'

const original = nlp('She walks home.')
const past = original.clone()
past.verbs().toPastTense()
past.text() // 'She walked home.'
original.text() // 'She walks home.'

Clone before transforming when the original must be preserved. Cloning a selection does not turn it into a whole-document selection. .all() returns a View of the whole underlying document.

• .match(pattern) extracts matching terms; .has(pattern) returns a boolean.
• .if(pattern) filters the current phrases, retaining each whole phrase containing a match. Use .sentences().if(pattern) to retain matching sentences.
• .found is a boolean property, not a method. An empty View is still a truthy JavaScript object.
• .replace(from, to) finds a pattern and replaces it; .replaceWith(to) replaces the selection.
• .text() returns a string; .out('array') returns strings per match; .json() returns structured records. These are outputs, not chainable Views.
• Text outputs can preserve case and punctuation. .text('normal') is not a universal punctuation stripper. Choose and verify normalization for the requested output rather than stripping blindly.

Write term patterns, not character regexes

Patterns operate on tokenized terms within each sentence. Literal words match case-insensitively; use {walk} to include inflections such as walked. Use real tag names: #Person, #Place, #Organization, #Noun, #Verb, #Adjective, #Value, and #Date are useful starting points. Tags form a hierarchy, so #FirstName also matches #Person and #Noun. Unknown tags silently match nothing unless explicitly defined by an extension. Do not invent tags such as #Name, #Location, #Subject, #Object, or #Adj.

const doc = nlp('John Smith arrived. Mary left.')
doc.match('[<who>#Person+] arrived').groups('who').text() // 'John Smith'
doc.sentences().if('arrived').out('array') // ['John Smith arrived.']
doc.has('#Person') // true

Matches do not cross sentence boundaries. Nested groups are unsupported; express complex logic as separate patterns or successive selections, verifying the scope at each step. Slashes in input split terms; do not assume a slash-joined string is one token. For literal word lists, consider .lookup(words) instead of constructing match syntax from arbitrary user input. For advanced patterns, consult the match reference before guessing.