objectivist-ner 0.0.1 → 0.0.3

package/README.md

@@ -148,6 +148,39 @@ ner --relations "Dr. Chen works at MIT and collaborates with Prof. Wright"
 
 Relations show how entities connect — extracting the "connective tissue" between concepts.
 
+You can also categorize relations by class:
+
+```bash
+ner --relations --relation-classes "employment,location,causal,professional" \
+  "Dr. Chen works at MIT and collaborates with Prof. Wright"
+```
+
+```json
+{
+  "entities": [
+    { "class": "person", "text": "Dr. Chen" },
+    { "class": "organization", "text": "MIT" },
+    { "class": "person", "text": "Prof. Wright" }
+  ],
+  "relations": [
+    {
+      "source": "Dr. Chen",
+      "target": "MIT",
+      "relation": "works at",
+      "class": "employment"
+    },
+    {
+      "source": "Dr. Chen",
+      "target": "Prof. Wright",
+      "relation": "collaborates with",
+      "class": "professional"
+    }
+  ]
+}
+```
+
+The `class` field categorizes the relation type (e.g., employment, causal, spatial), allowing you to group and analyze connections by category.
+
 ## Installation
 
 ```bash
@@ -274,6 +307,7 @@ cat article.txt | ner --detect-negation
 | `--attr-values <json>`            | Enum map for attribute values                      |
 | `--taxonomy <json>`               | Class hierarchy (parent → children)                |
 | `--relations`                     | Extract relations between entities                 |
+| `--relation-classes <list>`       | Allowed relation classes (e.g. employment,causal)  |
 | `--resolve`                       | Resolve coreferences (adds entity_id)              |
 | `--detect-negation`               | Add assertion field (present/negated/hypothetical) |
 | `--include-confidence`            | Add confidence field (low/medium/high)             |
@@ -304,22 +338,6 @@ Tested on a complex input with 11 entities across 6 classes:
 | Boston             | location | —            | location  |
 | **Found**          | **3/11** | **8/11**     | **11/11** |
 
-## Integration with objectivist-lattice
-
-This tool is designed to work with **[objectivist-lattice](https://github.com/richardanaya/objectivist-lattice)** — a knowledge management system that enforces the Objectivist hierarchy: percepts → concepts → principles → actions.
-
-**objectivist-ner** extracts the percepts and concepts. **objectivist-lattice** validates and organizes them into principles you can act on.
-
-### Workflow
-
-```bash
-# Extract structured observations from text
-ner --file chapter1.txt --detect-negation --resolve > percepts.json
-
-# Import into your knowledge lattice
-# (See objectivist-lattice documentation for details)
-```
-
 ## Epistemological Design
 
 Each feature maps to an Objectivist principle:
@@ -338,3 +356,71 @@ Use any GGUF model:
 ner "text" --model "hf:unsloth/Qwen3-8B-GGUF:Qwen3-8B-Q4_K_M.gguf"
 ner "text" --model ./my-model.gguf
 ```
+
+---
+
+## Complete Ontology Schema Example
+
+Schema files let you define your entire ontology in one place:
+
+```json
+{
+  "taxonomy": {
+    "organism": [
+      "person",
+      {
+        "animal": ["dog", "cat", "bird"]
+      }
+    ],
+    "place": [
+      "city",
+      "country",
+      {
+        "building": ["hospital", "school", "office"]
+      }
+    ],
+    "institution": ["company", "university", "government_agency"],
+    "concept": ["idea", "theory", "principle"]
+  },
+  "classes": ["person", "organization", "location", "event", "disease", "drug"],
+  "attributes": ["role", "age", "location", "date", "affiliation", "specialty"],
+  "attrValues": {
+    "role": ["doctor", "researcher", "patient", "student"],
+    "location": ["Boston", "New York", "London", "Tokyo"]
+  },
+  "relations": [
+    "works_at",
+    "located_in",
+    "treats",
+    "studies",
+    "collaborates_with"
+  ],
+  "relationClasses": [
+    "employment",
+    "spatial",
+    "medical",
+    "academic",
+    "professional"
+  ]
+}
+```
+
+Usage:
+
+```bash
+ner --schema complete-ontology.json "Dr. Chen works at Massachusetts General Hospital in Boston"
+```
+
+This loads taxonomy, classes, attributes, attribute values, relation types, and relation classes all at once.
+
+---
+
+## Building Principles from Percepts
+
+`objectivist-ner` extracts the raw perceptual material from any text: concrete entities with exact spans, hierarchical taxonomy (genus and differentia), coreferences preserving identity, assertions vs. negations, and relations.
+
+This supplies the inductive base required by Objectivist epistemology.
+
+Feed it philosophical works, scientific papers, historical accounts, or any reality-grounded writing. The parsed output gives you the concretes needed to form concepts and derive principles—anchored in observed facts, not floating abstractions.
+
+Use it to mine source material, reduce arguments to their perceptual roots, and build your own objective knowledge from existence.

package/index.ts

@@ -44,6 +44,7 @@ interface SchemaFile {
   attributes?: string[];
   attrValues?: Record<string, string[]>;
   relations?: string[];
+  relationClasses?: string[];
 }
 
 // === TAXONOMY HELPERS ===
@@ -178,6 +179,10 @@ program
     'Class hierarchy JSON e.g. {"organism":["animal","plant"]}',
   )
   .option("--relations", "Extract relations between entities")
+  .option(
+    "--relation-classes <list>",
+    "Comma-separated allowed relation classes (e.g. employment,location,causal)",
+  )
   .option("--resolve", "Resolve coreferences (group mentions of same entity)")
   .option("--include-confidence", "Include confidence scores per entity")
   .option("--detect-negation", "Detect negated/hypothetical entities")
@@ -293,6 +298,9 @@ if (opts.taxonomy) {
 
 const enableRelations = opts.relations || !!schemaFile?.relations;
 const relationTypes: string[] | undefined = schemaFile?.relations || undefined;
+const relationClasses: string[] | undefined = opts.relationClasses
+  ? opts.relationClasses.split(",").map((s: string) => s.trim())
+  : schemaFile?.relationClasses;
 const enableResolve = !!opts.resolve;
 const enableConfidence = !!opts.includeConfidence;
 const enableNegation = !!opts.detectNegation;
@@ -444,6 +452,23 @@ function buildGrammarSchema() {
 
 // === BUILD RELATIONS SCHEMA ===
 function buildRelationsSchema() {
+  const relationProperties: any = {
+    source: { type: "string" },
+    target: { type: "string" },
+    relation: {
+      type: "string",
+      ...(relationTypes && { enum: relationTypes }),
+    },
+  };
+
+  // Add class field if relationClasses is specified
+  if (relationClasses) {
+    relationProperties.class = {
+      type: "string",
+      enum: relationClasses,
+    };
+  }
+
   const relSchema: any = {
     type: "object",
     properties: {
@@ -452,15 +477,10 @@ function buildRelationsSchema() {
         type: "array",
         items: {
           type: "object",
-          properties: {
-            source: { type: "string" },
-            target: { type: "string" },
-            relation: {
-              type: "string",
-              ...(relationTypes && { enum: relationTypes }),
-            },
-          },
-          required: ["source", "target", "relation"],
+          properties: relationProperties,
+          required: relationClasses
+            ? ["source", "target", "relation", "class"]
+            : ["source", "target", "relation"],
           additionalProperties: false,
         },
       },
@@ -500,10 +520,18 @@ function buildConstraints(): string {
     constraints += `\nEvery entity has "entity_id" and "is_canonical" fields. Coreferent mentions share entity_id; exactly one per group has is_canonical:true (the most specific reference). Example: [{"class":"person","text":"Dr. Chen","entity_id":"e1","is_canonical":true,"attributes":{}},{"class":"person","text":"She","entity_id":"e1","is_canonical":false,"attributes":{}}]`;
   }
   if (enableRelations) {
-    constraints += `\nAlso extract relations between entities. Return {"entities": [...], "relations": [{"source": "entity text", "target": "entity text", "relation": "relation type"}]}.`;
+    let relDesc = `\nAlso extract relations between entities.`;
+    if (relationClasses) {
+      relDesc += ` Each relation must have a "class" field categorizing the relation type.`;
+    }
+    relDesc += ` Return {"entities": [...], "relations": [{"source": "entity text", "target": "entity text", "relation": "relation type"${relationClasses ? ', "class": "relation class"' : ""}}]}.`;
+    constraints += relDesc;
     if (relationTypes) {
       constraints += ` Allowed relation types: ${relationTypes.join(", ")}.`;
     }
+    if (relationClasses) {
+      constraints += ` Allowed relation classes: ${relationClasses.join(", ")}.`;
+    }
   }
 
   return constraints;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "objectivist-ner",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Objectivist-inspired Named Entity Recognition with grammar-constrained LLM output",
   "bin": {
     "ner": "index.ts"