objectivist-ner 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Anaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,355 @@
+# objectivist-ner
+
+Objectivist-inspired Named Entity Recognition with grammar-constrained LLM output.
+
+Uses [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) to run a small language model locally, enforcing structured output via JSON schema grammars. No API keys, no network calls -- everything runs on your machine.
+
+The CLI is installed as the `ner` command.
+
+## Features
+
+- Exact span extraction -- entity `text` is the substring from the input, not a paraphrase
+- Schema-constrained output via llama.cpp grammar (guaranteed valid JSON)
+- Restrict entity classes, attribute keys, and attribute values
+- Hierarchical class taxonomies
+- Relation extraction between entities
+- Coreference resolution (group mentions of the same entity)
+- Negation and modality detection
+- Confidence scores
+- Schema definition files for reusable ontologies
+- Long document chunking with `--file`
+- Batch processing with `--batch`
+- Three built-in model tiers: `--fast`, `--balanced`, `--best`
+- Reads from argument, file, or stdin
+- Compact JSON output for non-TTY / piping
+
+## Installation
+
+```bash
+# Local development
+bun install
+
+# Install globally as the `ner` command
+bun install -g objectivist-ner
+```
+
+After global install, use the `ner` command directly.
+
+## Usage
+
+```bash
+# Uses --best (4B) by default
+ner "the cat is blue and is feeling sad"
+
+# Pick a model tier
+ner --fast "the cat is blue"
+ner --balanced "John works at Google in NYC"
+ner --best "complex medical research text"
+```
+
+### Entity constraints
+
+```bash
+# Restrict entity classes
+ner "John works at Google" --classes person,organization
+
+# Restrict attribute keys
+ner "Alice is sad in Paris" --attributes emotional_state,location
+
+# Restrict attribute values with enums
+ner "The sky is blue" --attr-values '{"color":["blue","red","green"]}'
+
+# Hierarchical class taxonomy
+ner "Dr. Chen lives in Boston with her cat" \
+  --taxonomy '{"organism":["person","animal"],"place":["city","country"]}'
+```
+
+### Relation extraction
+
+```bash
+ner --relations "Dr. Chen works at MIT and collaborates with Prof. Wright"
+```
+
+Output:
+
+```json
+{
+  "entities": [
+    { "class": "person", "text": "Dr. Chen", "attributes": {} },
+    { "class": "organization", "text": "MIT", "attributes": {} },
+    { "class": "person", "text": "Prof. Wright", "attributes": {} }
+  ],
+  "relations": [
+    { "source": "Dr. Chen", "target": "MIT", "relation": "works at" },
+    {
+      "source": "Dr. Chen",
+      "target": "Prof. Wright",
+      "relation": "collaborates with"
+    }
+  ]
+}
+```
+
+### Coreference resolution
+
+```bash
+ner --resolve "Dr. Chen published a paper. She later won the Nobel Prize. The neurologist was celebrated."
+```
+
+Output:
+
+```json
+[
+  {
+    "class": "person",
+    "text": "Dr. Chen",
+    "attributes": {},
+    "entity_id": "e1"
+  },
+  { "class": "person", "text": "She", "attributes": {}, "entity_id": "e1" },
+  {
+    "class": "person",
+    "text": "The neurologist",
+    "attributes": {},
+    "entity_id": "e1"
+  },
+  {
+    "class": "event",
+    "text": "the Nobel Prize",
+    "attributes": {},
+    "entity_id": "e2"
+  }
+]
+```
+
+`entity_id` is a grammar-enforced top-level field, not inside `attributes`.
+
+### Negation detection
+
+```bash
+ner --detect-negation "The patient has diabetes but does not have cancer. He might develop hypertension."
+```
+
+### Confidence scores
+
+```bash
+ner --include-confidence "Dr. Maria Chen works at MIT. Someone named Bob might be there too."
+```
+
+### Schema definition files
+
+Define your ontology in a JSON file and reuse it:
+
+```json
+{
+  "taxonomy": {
+    "organism": ["person", "animal"],
+    "place": ["city", "country", "building"],
+    "institution": ["company", "university", "government_agency"]
+  },
+  "attributes": ["role", "age", "location", "affiliation"],
+  "relations": ["works_at", "located_in", "affiliated_with"]
+}
+```
+
+```bash
+ner --schema schema.json "Dr. Chen works at MIT in Boston"
+```
+
+Schema files support `taxonomy`, `classes`, `attributes`, `attrValues`, and `relations`. CLI flags override schema file values.
+
+### File and batch processing
+
+```bash
+# Process a long document (auto-chunked)
+ner --file document.txt
+
+# Process a JSONL file (one text per line, outputs JSONL)
+ner --batch inputs.jsonl
+
+# Process a directory of .txt files
+ner --batch ./documents/
+```
+
+### Other options
+
+```bash
+# Append to the built-in system prompt
+ner "text" --system-prompt-append "Focus only on emotions"
+
+# Replace the system prompt entirely
+ner "text" --system-prompt "You are a custom extractor."
+
+# Read from stdin
+echo "the cat is blue" | ner
+
+# Compact JSON output
+ner "the cat is blue" --compact
+```
+
+## Models
+
+fastner ships with three built-in model tiers. Pick one with a flag -- the model is downloaded automatically on first use to `~/.fastner/models/`.
+
+| Flag         | Model             | Size | Download | Best for                        |
+| ------------ | ----------------- | ---- | -------- | ------------------------------- |
+| `--fast`     | Qwen3.5-0.8B Q8_0 | 0.8B | ~0.9 GB  | Simple text, single entities    |
+| `--balanced` | Qwen3.5-2B Q8_0   | 2B   | ~2.3 GB  | Moderate complexity, most tasks |
+| `--best`     | Qwen3.5-4B Q8_0   | 4B   | ~4.5 GB  | Dense text, rare entity types   |
+
+`--best` is the default. See [Benchmarks](#benchmarks) for why.
+
+## Options
+
+| Flag                              | Description                                    |
+| --------------------------------- | ---------------------------------------------- |
+| `--fast`                          | Use 0.8B model -- quick, simple text only      |
+| `--balanced`                      | Use 2B model -- good accuracy/speed tradeoff   |
+| `--best`                          | Use 4B model -- best accuracy (default)        |
+| `-c, --classes <list>`            | Comma-separated allowed entity classes         |
+| `-a, --attributes <list>`         | Comma-separated allowed attribute keys         |
+| `--attr-values <json>`            | JSON enum map for attribute values             |
+| `--taxonomy <json>`               | Class hierarchy JSON                           |
+| `--relations`                     | Extract relations between entities             |
+| `--resolve`                       | Resolve coreferences                           |
+| `--include-confidence`            | Include confidence scores per entity           |
+| `--detect-negation`               | Detect negated/hypothetical entities           |
+| `--schema <path>`                 | Load schema definition from JSON file          |
+| `--file <path>`                   | Read input from file (with chunking)           |
+| `--batch <path>`                  | Process JSONL file or directory of .txt files  |
+| `--system-prompt <string>`        | Replace the built-in system prompt entirely    |
+| `--system-prompt-append <string>` | Append to the built-in system prompt           |
+| `--compact`                       | Output compact JSON (auto-enabled for non-TTY) |
+| `-m, --model <uri>`               | Use any GGUF model (see below)                 |
+
+## Benchmarks
+
+We tested all three tiers against a complex input containing 11 entities across 6 classes (person, organization, location, disease, drug, event):
+
+> "Dr. Maria Chen, a 42-year-old neurologist at Massachusetts General Hospital in Boston, published a groundbreaking paper with her colleague Prof. James Wright from Oxford University about a rare genetic mutation called BRCA3-delta found in 12 patients from rural Bangladesh, while simultaneously consulting for Pfizer on their new drug Nexavion priced at 450 dollars per dose, which the WHO classified as a Category A essential medicine last Tuesday during their Geneva summit"
+
+| Entity             | `--fast`   | `--balanced` | `--best` (default)       |
+| ------------------ | ---------- | ------------ | ------------------------ |
+| Dr. Maria Chen     | person     | person       | person                   |
+| Prof. James Wright | person     | person       | person, role: colleague  |
+| MGH                | -          | org          | org                      |
+| Oxford University  | -          | org          | org                      |
+| BRCA3-delta        | -          | disease      | disease                  |
+| Bangladesh         | -          | -            | location                 |
+| Pfizer             | -          | org          | org                      |
+| Nexavion           | -          | drug         | drug, price: 450 dollars |
+| WHO                | -          | -            | org, category: Cat A     |
+| Geneva summit      | -          | event        | location                 |
+| Boston             | location   | -            | location                 |
+| **Entities found** | **3 / 11** | **8 / 11**   | **11 / 11**              |
+
+All three tiers produce zero hallucinations with the current prompt design.
+
+## Epistemological design
+
+fastner's feature set is informed by Objectivist epistemology -- the theory that concepts are formed by abstracting essential characteristics from concretes, organized into hierarchical structures, and held in a specific relationship to reality.
+
+### Identity: A is A (`--resolve`)
+
+The law of identity demands that we track _what a thing is_ across all its references. When a text says "Dr. Chen", "she", and "the neurologist", these are three linguistic expressions of one entity. Without coreference resolution, an NER system treats them as three unrelated extractions -- a failure to maintain identity. `--resolve` enforces that A remains A regardless of how it is named.
+
+### Hierarchical concept formation (`--taxonomy`)
+
+Objectivist epistemology holds that concepts are organized hierarchically through a process of abstraction. "Cat" is subsumed under "animal", which is subsumed under "organism". Each level retains the essential characteristics of its parent while adding differentia. The `--taxonomy` flag mirrors this structure directly -- you define genus-species relationships between entity classes, and the model classifies at the most specific level it can justify. This isn't just organization; it's how valid concepts are formed.
+
+### Distinguishing existence from assertion (`--detect-negation`)
+
+A concept must be connected to reality. "The patient has diabetes" and "the patient does not have diabetes" both contain the entity "diabetes", but their relationship to existence is opposite. Naive NER systems that extract "diabetes" from both sentences without distinguishing assertion from negation commit a fundamental error -- they detach the concept from its existential status. `--detect-negation` forces every entity to declare its relationship to reality: present, negated, or hypothetical.
+
+### Certainty and the hierarchy of evidence (`--include-confidence`)
+
+Knowledge exists on a spectrum from certain to speculative. "Dr. Maria Chen" appearing with a full name and title is a high-confidence extraction. "Someone named Bob" is low-confidence. Objectivism rejects both dogmatism (asserting certainty where none exists) and skepticism (denying certainty where it does). `--include-confidence` makes the epistemic status of each extraction explicit, letting downstream systems apply appropriate thresholds.
+
+### Relations as conceptual integration (`--relations`)
+
+Entities don't exist in isolation. The relationship "Dr. Chen works at MIT" is not a property of Chen or of MIT alone -- it's a fact about reality that connects two existents. Extracting entities without their relations is like forming concepts without integrating them into propositions. `--relations` extracts the connective tissue between entities, producing a knowledge graph rather than an isolated list.
+
+### Schema files as objective definitions (`--schema`)
+
+Definitions, in Objectivist epistemology, identify the essential characteristics that distinguish a concept from all others. A schema file serves this function for NER: it defines your ontology once -- the class hierarchy, the valid attributes, the relation types -- and applies it consistently across all extractions. This is the difference between ad-hoc classification and principled concept formation.
+
+### Grammar enforcement as logical constraint
+
+Several fields (`assertion`, `confidence`, `entity_id`, `class` enums) are enforced at the grammar level, not merely prompted. The model literally cannot produce an invalid value. This is the computational equivalent of the principle that contradictions cannot exist -- the system's structure makes certain errors impossible rather than merely unlikely.
+
+## Building Up Knowledge
+
+fastner is designed as a tool for the Objectivist project of building knowledge from percepts through concepts to principles and finally to action — the exact process implemented in the companion project **[objectivist-lattice](https://github.com/richardanaya/objectivist-lattice)**.
+
+### The Epistemological Pipeline
+
+Objectivism holds that all knowledge begins with **percepts** (raw sensory data), which are integrated into **concepts**, which are organized into **principles** (general truths), which are finally applied as **actions** in specific contexts.
+
+`objectivist-lattice` enforces this hierarchy strictly on a filesystem of Markdown files with validation rules:
+
+- **Axioms** and **percepts** are bedrock — they have no `reduces_to` links
+- **Principles** must reduce to axioms or percepts
+- **Applications** must reduce to principles
+- Promotion from `Tentative/Hypothesis` to `Integrated/Validated` can only happen bottom-up
+
+### How NER Helps Build the Lattice
+
+fastner acts as the **percept-to-concept extraction layer** for this system:
+
+1. **Percept Extraction** (`--detect-negation`)
+   - Identifies concrete entities from source material (books, articles, personal observations)
+   - Distinguishes what is asserted as present, negated, or hypothetical
+   - Feeds raw perceptual data into the `02-Percepts/` directory
+
+2. **Concept Formation** (`--classes`, `--taxonomy`, `--resolve`)
+   - Groups multiple mentions of the same entity (`entity_id`)
+   - Classifies entities into hierarchical taxonomies (`organism > person > neurologist`)
+   - Maintains identity across contexts — "Dr. Chen", "she", and "the neurologist" are recognized as the same existent
+
+3. **Principle Discovery** (`--relations`, `--schema`)
+   - Extracts relations between entities ("works at", "causes", "implies")
+   - Uses schema files to enforce your ontological commitments
+   - Surfaces potential principles by showing what consistently reduces to what
+
+4. **Action Guidance** (`--include-confidence`)
+   - Rates confidence in each extraction
+   - Helps distinguish high-certainty principles (suitable for action) from speculative ones (still tentative)
+
+### Practical Workflow
+
+```bash
+# Extract entities from a book chapter
+ner --file chapter1.txt --detect-negation --resolve --include-confidence > percepts.json
+
+# Convert to lattice format
+cat percepts.json | jq '.[] | {title: .text, level: "percept", proposition: (.text + " was observed")}' > 02-Percepts/20260315-percept-001.md
+
+# Later, when forming principles
+ner --relations --schema ontology.json "text from multiple chapters" > principles.json
+```
+
+The combination of **objectivist-ner** (extraction) and **objectivist-lattice** (validation and organization) creates a complete pipeline:
+
+**Percepts → Concepts → Principles → Validated Knowledge → Action**
+
+This is not just information extraction. It is epistemological engineering — using computation to enforce the proper hierarchical structure of knowledge, preventing floating abstractions and ensuring every principle is grounded in percepts and axioms.
+
+The grammar-enforced fields (`assertion`, `confidence`, `entity_id`) are not arbitrary features. They are computational implementations of fundamental epistemological requirements: every concept must have a relationship to reality, every claim must have an epistemic status, and identity must be maintained across contexts.
+
+See the [objectivist-lattice](https://github.com/richardanaya/objectivist-lattice) repository for the validation and knowledge management layer that pairs with this tool.
+
+## Custom models
+
+If the built-in tiers don't fit your needs, you can pass any GGUF model with `--model`. This overrides `--fast`/`--balanced`/`--best`.
+
+```bash
+# HuggingFace URI
+ner "text" --model "hf:unsloth/Qwen3-8B-GGUF:Qwen3-8B-Q4_K_M.gguf"
+
+# Local file
+ner "text" --model ./my-custom-model.gguf
+```
+
+## License
+
+MIT © Richard Anaya

package/index.ts

@@ -0,0 +1,514 @@
+import { program } from "commander";
+import path from "path";
+import os from "os";
+import fs from "fs";
+import { getLlama, LlamaChatSession, resolveModelFile } from "node-llama-cpp";
+
+// === MODELS ===
+const MODELS = {
+  fast: "hf:unsloth/Qwen3.5-0.8B-GGUF:Qwen3.5-0.8B-Q8_0.gguf",
+  balanced: "hf:unsloth/Qwen3.5-2B-GGUF:Qwen3.5-2B-Q8_0.gguf",
+  best: "hf:unsloth/Qwen3.5-4B-GGUF:Qwen3.5-4B-Q8_0.gguf",
+} as const;
+
+// === SYSTEM PROMPTS ===
+const SYSTEM_PROMPT = `You are a named entity recognition (NER) system. Your task is to extract entities from text.
+
+Rules:
+- "text" must be the EXACT substring from the input that refers to the entity. Do NOT paraphrase or include extra words.
+- "class" is the entity type (e.g. person, animal, location, organization).
+- "attributes" are properties of the entity found in context.
+- Return one object per distinct entity mention.
+- If no entities are found, return an empty array [].`;
+
+const FEW_SHOT_EXAMPLES = `Example 1:
+Input: "the cat is blue and is feeling sad"
+Output: [{"class":"animal","text":"cat","attributes":{"color":"blue","emotional_state":"sad"}}]
+
+Example 2:
+Input: "John Smith lives in New York City and works at Google"
+Output: [{"class":"person","text":"John Smith","attributes":{"location":"New York City","employer":"Google"}},{"class":"location","text":"New York City","attributes":{}},{"class":"organization","text":"Google","attributes":{}}]
+
+Example 3:
+Input: "The quick brown fox jumps over the lazy dog near the river"
+Output: [{"class":"animal","text":"fox","attributes":{"color":"brown","speed":"quick"}},{"class":"animal","text":"dog","attributes":{"temperament":"lazy"}},{"class":"location","text":"the river","attributes":{}}]
+
+Example 4:
+Input: "Researchers at MIT found that the drug Riluzole slows progression of ALS in a trial last March"
+Output: [{"class":"organization","text":"MIT","attributes":{}},{"class":"drug","text":"Riluzole","attributes":{}},{"class":"disease","text":"ALS","attributes":{}},{"class":"event","text":"trial last March","attributes":{"date":"last March"}}]`;
+
+// === SCHEMA FILE TYPES ===
+interface SchemaFile {
+  taxonomy?: Record<string, string[]>;
+  classes?: string[];
+  attributes?: string[];
+  attrValues?: Record<string, string[]>;
+  relations?: string[];
+}
+
+// === TAXONOMY HELPERS ===
+function flattenTaxonomy(taxonomy: Record<string, string[]>): string[] {
+  const all = new Set<string>();
+  for (const [parent, children] of Object.entries(taxonomy)) {
+    all.add(parent);
+    for (const child of children) all.add(child);
+  }
+  return [...all];
+}
+
+function taxonomyToPrompt(taxonomy: Record<string, string[]>): string {
+  const lines = Object.entries(taxonomy)
+    .map(([parent, children]) => `  ${parent}: ${children.join(", ")}`)
+    .join("\n");
+  return `Use the following class hierarchy. Classify at the most specific level.\n${lines}`;
+}
+
+// === CHUNKING ===
+function chunkText(text: string, maxChars: number): string[] {
+  if (text.length <= maxChars) return [text];
+  const chunks: string[] = [];
+  const sentences = text.split(/(?<=[.!?])\s+/);
+  let current = "";
+  for (const sentence of sentences) {
+    if (current.length + sentence.length > maxChars && current.length > 0) {
+      chunks.push(current.trim());
+      current = "";
+    }
+    current += (current ? " " : "") + sentence;
+  }
+  if (current.trim()) chunks.push(current.trim());
+  return chunks;
+}
+
+// === CLI ===
+program
+  .name("ner")
+  .description(
+    "Objectivist-inspired named entity recognition with grammar constraints",
+  )
+  .argument("[text]", "Text to extract entities from (omit to read from stdin)")
+  .option("-c, --classes <list>", "Comma-separated allowed entity classes")
+  .option("-a, --attributes <list>", "Comma-separated allowed attribute keys")
+  .option(
+    "--attr-values <json>",
+    'JSON enum map for attributes e.g. {"color":["blue","red"]}',
+  )
+  .option(
+    "--taxonomy <json>",
+    'Class hierarchy JSON e.g. {"organism":["animal","plant"]}',
+  )
+  .option("--relations", "Extract relations between entities")
+  .option("--resolve", "Resolve coreferences (group mentions of same entity)")
+  .option("--include-confidence", "Include confidence scores per entity")
+  .option("--detect-negation", "Detect negated/hypothetical entities")
+  .option("--schema <path>", "Load entity schema definition from a JSON file")
+  .option(
+    "--file <path>",
+    "Read input from a file (with chunking for long docs)",
+  )
+  .option(
+    "--batch <path>",
+    "Process JSONL file (one text per line) or directory of .txt files",
+  )
+  .option(
+    "--system-prompt <string>",
+    "Replace the built-in system prompt entirely",
+  )
+  .option(
+    "--system-prompt-append <string>",
+    "Append to the built-in system prompt",
+  )
+  .option("-m, --model <uri>", "Model URI or path to GGUF file")
+  .option("--fast", "Use smallest model (0.8B) -- quick, simple text only")
+  .option(
+    "--balanced",
+    "Use mid-size model (2B) -- good accuracy/speed tradeoff",
+  )
+  .option("--best", "Use largest model (4B) -- best accuracy (default)")
+  .option("--compact", "Output compact JSON (also auto-enabled for non-TTY)")
+  .addHelpText(
+    "after",
+    `
+Examples:
+  fastner "the cat is blue"
+  fastner --fast "simple short text"
+  fastner "John works at Google" --classes person,organization
+  fastner "sky is blue" --attr-values '{"color":["blue","red"]}'
+  fastner --relations "Dr. Chen works at MIT"
+  fastner --resolve "Dr. Chen published a paper. She won an award."
+  fastner --detect-negation "The patient does not have diabetes"
+  fastner --schema schema.json "complex text"
+  fastner --file document.txt
+  fastner --batch inputs.jsonl
+  echo "the cat is blue" | fastner
+`,
+  )
+  .parse();
+
+const opts = program.opts();
+
+// === VALIDATIONS ===
+const tierFlags = [opts.fast, opts.balanced, opts.best].filter(Boolean).length;
+if (tierFlags > 1) {
+  console.error(
+    "Error: --fast, --balanced, and --best are mutually exclusive.",
+  );
+  process.exit(1);
+}
+
+if (opts.systemPrompt && opts.systemPromptAppend) {
+  console.error(
+    "Error: --system-prompt and --system-prompt-append are mutually exclusive.",
+  );
+  process.exit(1);
+}
+
+// === LOAD SCHEMA FILE ===
+let schemaFile: SchemaFile | undefined;
+if (opts.schema) {
+  try {
+    const raw = fs.readFileSync(opts.schema, "utf-8");
+    schemaFile = JSON.parse(raw);
+  } catch (e) {
+    console.error(`Error: Failed to load schema file: ${(e as Error).message}`);
+    process.exit(1);
+  }
+}
+
+// === MERGE OPTIONS (CLI flags override schema file) ===
+const allowedClasses: string[] | undefined = opts.classes
+  ? opts.classes.split(",").map((s: string) => s.trim())
+  : schemaFile?.classes;
+
+const allowedAttrs: string[] | undefined = opts.attributes
+  ? opts.attributes.split(",").map((s: string) => s.trim())
+  : schemaFile?.attributes;
+
+let attrValuesMap: Record<string, string[]> | undefined;
+if (opts.attrValues) {
+  try {
+    attrValuesMap = JSON.parse(opts.attrValues);
+  } catch (e) {
+    console.error(
+      `Error: Invalid JSON for --attr-values: ${(e as Error).message}`,
+    );
+    process.exit(1);
+  }
+} else if (schemaFile?.attrValues) {
+  attrValuesMap = schemaFile.attrValues;
+}
+
+let taxonomy: Record<string, string[]> | undefined;
+if (opts.taxonomy) {
+  try {
+    taxonomy = JSON.parse(opts.taxonomy);
+  } catch (e) {
+    console.error(
+      `Error: Invalid JSON for --taxonomy: ${(e as Error).message}`,
+    );
+    process.exit(1);
+  }
+} else if (schemaFile?.taxonomy) {
+  taxonomy = schemaFile.taxonomy;
+}
+
+const enableRelations = opts.relations || !!schemaFile?.relations;
+const relationTypes: string[] | undefined = schemaFile?.relations || undefined;
+const enableResolve = !!opts.resolve;
+const enableConfidence = !!opts.includeConfidence;
+const enableNegation = !!opts.detectNegation;
+
+// === READ INPUT ===
+let inputTexts: string[] = [];
+
+if (opts.batch) {
+  const batchPath = opts.batch as string;
+  const stat = fs.statSync(batchPath);
+  if (stat.isDirectory()) {
+    const files = fs
+      .readdirSync(batchPath)
+      .filter((f: string) => f.endsWith(".txt"));
+    inputTexts = files.map((f: string) =>
+      fs.readFileSync(path.join(batchPath, f), "utf-8").trim(),
+    );
+  } else {
+    const content = fs.readFileSync(batchPath, "utf-8").trim();
+    inputTexts = content.split("\n").map((line: string) => {
+      try {
+        const parsed = JSON.parse(line);
+        return typeof parsed === "string" ? parsed : parsed.text || line;
+      } catch {
+        return line;
+      }
+    });
+  }
+} else if (opts.file) {
+  const content = fs.readFileSync(opts.file, "utf-8").trim();
+  inputTexts = chunkText(content, 2000);
+} else {
+  let text = program.args[0];
+  if (!text) {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk as Buffer);
+    }
+    text = Buffer.concat(chunks).toString().trim();
+  }
+  if (!text) {
+    console.error(
+      "Error: No input text provided. Pass as argument, --file, --batch, or stdin.",
+    );
+    process.exit(1);
+  }
+  inputTexts = [text];
+}
+
+// === RESOLVE MODEL ===
+const modelUri = opts.model
+  ? opts.model
+  : opts.fast
+    ? MODELS.fast
+    : opts.balanced
+      ? MODELS.balanced
+      : MODELS.best;
+
+const modelsDir = path.join(os.homedir(), ".fastner", "models");
+const modelPath = await resolveModelFile(modelUri, modelsDir);
+
+const llama = await getLlama();
+const model = await llama.loadModel({ modelPath });
+const context = await model.createContext();
+
+// === BUILD SYSTEM PROMPT ===
+function buildSystemPrompt(): string {
+  if (opts.systemPrompt) return opts.systemPrompt;
+
+  let base = SYSTEM_PROMPT;
+
+  if (enableNegation) {
+    base += `\n- Every entity has a top-level "assertion" field: "present", "negated", or "hypothetical". "negated" means the text explicitly denies it (e.g. "does not have"). "hypothetical" means it is speculative (e.g. "might develop").`;
+  }
+  if (enableConfidence) {
+    base += `\n- Every entity has a top-level "confidence" field: "low", "medium", or "high".`;
+  }
+  if (enableResolve) {
+    base += `\n- Every entity has a top-level "entity_id" field. If multiple text spans refer to the same real-world entity (e.g. "Dr. Chen" and "she"), they share the same entity_id. Use short IDs like "e1", "e2".`;
+  }
+
+  let prompt = `${base}\n\n${FEW_SHOT_EXAMPLES}`;
+
+  if (opts.systemPromptAppend) {
+    prompt += `\n\n${opts.systemPromptAppend}`;
+  }
+
+  return prompt;
+}
+
+// === BUILD GRAMMAR SCHEMA ===
+function buildGrammarSchema() {
+  // Determine allowed classes from taxonomy or explicit list
+  const classEnum = taxonomy ? flattenTaxonomy(taxonomy) : allowedClasses;
+
+  const attributesSchema: any = {
+    type: "object",
+    additionalProperties: { type: "string" },
+  };
+
+  const properties: any = {
+    class: {
+      type: "string",
+      ...(classEnum && { enum: classEnum }),
+    },
+    text: { type: "string" },
+    attributes: attributesSchema,
+  };
+  const required: string[] = ["class", "text"];
+
+  // Grammar-enforced fields for enabled features.
+  // These are top-level entity properties (not inside attributes)
+  // so the grammar can enforce them as required on every entity.
+  if (enableNegation) {
+    properties.assertion = {
+      type: "string",
+      enum: ["present", "negated", "hypothetical"],
+    };
+    required.push("assertion");
+  }
+  if (enableConfidence) {
+    properties.confidence = {
+      type: "string",
+      enum: ["low", "medium", "high"],
+    };
+    required.push("confidence");
+  }
+  if (enableResolve) {
+    properties.entity_id = { type: "string" };
+    required.push("entity_id");
+  }
+
+  const schema: any = {
+    type: "array",
+    items: {
+      type: "object",
+      properties,
+      required,
+      additionalProperties: false,
+    },
+  };
+
+  return schema;
+}
+
+// === BUILD RELATIONS SCHEMA ===
+function buildRelationsSchema() {
+  const relSchema: any = {
+    type: "object",
+    properties: {
+      entities: buildGrammarSchema(),
+      relations: {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            source: { type: "string" },
+            target: { type: "string" },
+            relation: {
+              type: "string",
+              ...(relationTypes && { enum: relationTypes }),
+            },
+          },
+          required: ["source", "target", "relation"],
+          additionalProperties: false,
+        },
+      },
+    },
+    required: ["entities", "relations"],
+    additionalProperties: false,
+  };
+  return relSchema;
+}
+
+// === BUILD PROMPT CONSTRAINTS ===
+function buildConstraints(): string {
+  let constraints = "";
+
+  if (taxonomy) {
+    constraints += `\n${taxonomyToPrompt(taxonomy)}`;
+  } else if (allowedClasses) {
+    constraints += `\nAllowed entity classes: ${allowedClasses.join(", ")}. Only use these classes.`;
+  }
+
+  if (attrValuesMap) {
+    const desc = Object.entries(attrValuesMap)
+      .map(([k, v]) => `${k}: ${v.join(", ")}`)
+      .join("; ");
+    constraints += `\nOnly use these attribute keys and values: ${desc}. Omit attributes that don't apply to an entity.`;
+  } else if (allowedAttrs) {
+    constraints += `\nOnly use these attribute keys: ${allowedAttrs.join(", ")}. Omit attributes that don't apply to an entity.`;
+  }
+
+  if (enableNegation) {
+    constraints += `\nEvery entity has an "assertion" field (not in attributes). Example: [{"class":"disease","text":"diabetes","assertion":"present","attributes":{}},{"class":"disease","text":"cancer","assertion":"negated","attributes":{}}]`;
+  }
+  if (enableConfidence) {
+    constraints += `\nEvery entity has a "confidence" field (not in attributes). Example: [{"class":"person","text":"John","confidence":"high","attributes":{}}]`;
+  }
+  if (enableResolve) {
+    constraints += `\nEvery entity has an "entity_id" field (not in attributes). Coreferent mentions share the same entity_id. Example: [{"class":"person","text":"Dr. Chen","entity_id":"e1","attributes":{}},{"class":"person","text":"She","entity_id":"e1","attributes":{}}]`;
+  }
+  if (enableRelations) {
+    constraints += `\nAlso extract relations between entities. Return {"entities": [...], "relations": [{"source": "entity text", "target": "entity text", "relation": "relation type"}]}.`;
+    if (relationTypes) {
+      constraints += ` Allowed relation types: ${relationTypes.join(", ")}.`;
+    }
+  }
+
+  return constraints;
+}
+
+// === PROCESS A SINGLE TEXT ===
+async function processText(
+  inputText: string,
+  session: LlamaChatSession,
+): Promise<any> {
+  const constraints = buildConstraints();
+  const prompt = `Extract all named entities from the following text.${constraints}\n\nText: ${inputText}`;
+
+  const schema = enableRelations
+    ? buildRelationsSchema()
+    : buildGrammarSchema();
+  const grammar = await llama.createGrammarForJsonSchema(schema);
+
+  const res = await session.prompt(prompt, { grammar });
+
+  let parsed: any;
+  try {
+    parsed = grammar.parse(res);
+  } catch {
+    try {
+      parsed = JSON.parse(res.trim());
+    } catch {
+      console.error(
+        "Warning: Failed to parse model output. Raw response:",
+        res,
+      );
+      parsed = enableRelations ? { entities: [], relations: [] } : [];
+    }
+  }
+
+  return parsed;
+}
+
+// === MAIN ===
+const systemPrompt = buildSystemPrompt();
+const compact = opts.compact || !process.stdout.isTTY;
+
+const contextSequence = context.getSequence();
+
+if (inputTexts.length === 1) {
+  const session = new LlamaChatSession({
+    contextSequence,
+    systemPrompt,
+  });
+  const result = await processText(inputTexts[0]!, session);
+  console.log(JSON.stringify(result, null, compact ? 0 : 2));
+} else {
+  // Batch / chunked: process each text, collect results
+  const allResults: any[] = [];
+  for (const inputText of inputTexts) {
+    // Erase context and create fresh session for each input
+    await contextSequence.eraseContextTokenRanges([
+      { start: 0, end: contextSequence.nextTokenIndex },
+    ]);
+    const session = new LlamaChatSession({
+      contextSequence,
+      systemPrompt,
+    });
+    const result = await processText(inputText, session);
+    allResults.push(result);
+  }
+
+  if (opts.file) {
+    // Merge chunked results into one
+    if (enableRelations) {
+      const merged = {
+        entities: allResults.flatMap((r) => r.entities || []),
+        relations: allResults.flatMap((r) => r.relations || []),
+      };
+      console.log(JSON.stringify(merged, null, compact ? 0 : 2));
+    } else {
+      const merged = allResults.flat();
+      console.log(JSON.stringify(merged, null, compact ? 0 : 2));
+    }
+  } else {
+    // Batch: output one result per line (JSONL)
+    for (const result of allResults) {
+      console.log(JSON.stringify(result));
+    }
+  }
+}
+
+// === CLEANUP ===
+// Bun segfaults if process.exit() triggers synchronous native addon unloading.
+// Setting exitCode lets the event loop drain naturally, avoiding the crash.
+process.exitCode = 0;

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "objectivist-ner",
+  "version": "0.0.0",
+  "description": "Objectivist-inspired Named Entity Recognition with grammar-constrained LLM output",
+  "bin": {
+    "ner": "index.ts"
+  },
+  "module": "index.ts",
+  "type": "module",
+  "license": "MIT",
+  "author": "Richard Anaya",
+  "repository": "git@github.com:richardanaya/objectivist-ner.git",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "prettier": "^3.8.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "node-llama-cpp": "^3.17.1"
+  }
+}