compromise AGENTS.md

AGENTS.md — using compromise

Guidance for AI coding agents (and humans) writing code with compromise, a rule-based English NLP library. This file is the map; the linked docs are the territory. Prefer them over guessing — the published docs at observablehq.com are interactive notebooks and do not render as readable text.

Read these first

File	What's in it
docs/concepts.md	the document/View/Term model, mutability, build tiers — the mental model
docs/match-syntax.md	the .match() mini-language (#Tag, [capture], (a|b), ~fuzzy~, {root}, …)
docs/tags.md	the complete, valid part-of-speech tagset
docs/api.md	every method, signature, and one-line description
docs/recipes.md	copy-paste solutions to common tasks
llms-full.txt	all of the above concatenated into one file
docs/SKILL.md	example skill for using compromise in a coding agent

30-second mental model

import nlp from 'compromise'

let doc = nlp('she sells seashells by the seashore.')  // parse → a View of the whole document
doc.verbs().toPastTense()                               // select verbs, transform them (mutates doc)
doc.text()                                              // 'she sold seashells by the seashore.'

• nlp(text) returns a View. Almost every method returns a View, so calls chain.
• Find with .match(), .has(), .if(), or named selections like .people(), .numbers().
• Transform with .toPastTense(), .replace(), .tag(), .normalize(), etc.
• Output with .text(), .json(), .out('array'), .debug().

Rules that prevent most mistakes

1. Transforms mutate the document in place. The View they return is the selection, not the whole doc. Read the final result from the original variable:

   let doc = nlp('I walk to work')
   doc.verbs().toPastTense()
   doc.text()                       // ✅ 'I walked to work'
   // ❌ nlp('I walk to work').verbs().toPastTense().text()  →  'walked work' (selection only)
   

   Use .clone() to transform a copy without touching the original.