Recursive AI

Rule-based entity recognition in C#

OneNLP is a free, open-source natural language processing library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

NuGet GitHub Docs Download example (.zip)

Rule-based entity recognition labels known names or token patterns without training a model.

No model package is needed.

Terminal
dotnet add package RecursiveAI.OneNlp

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using RecursiveAI.OneNlp;
using RecursiveAI.OneNlp.Matching;
 
var doc = Nlp.Analyze(
    "Acme Corp hired Jo.");
var ruler = new EntityRuler();
ruler.AddPhrase("ORG", "Acme Corp");
ruler.Process(doc);
foreach (var entity in doc.Ents)
    Console.WriteLine(
        $"{entity.Label}: {entity}");
Text
ORG: Acme Corp

Invalid rule files raise PatternFormatException; a valid rule that finds nothing adds no entities.

Unzip the example, then dotnet run.

Variations

Return rule IDs and match an identifier by shape. In Xdddd, X means an uppercase letter and each d means a digit. Replace Program.cs with:

C#
using RecursiveAI.OneNlp;
using RecursiveAI.OneNlp.Matching;
 
var doc = Nlp.Analyze("Acme Corp filed K1234.");
var ruler = new EntityRuler();
ruler.AddPhrase("ORG", "Acme Corp", "acme");
ruler.Add("CASE_NO",
    Pattern.Shape("Xdddd"), "case");
var entities = ruler.FindEntities(doc);
foreach (var entity in entities)
    Console.WriteLine(
        $"{entity.Id}: {entity.Span}");
Text
acme: Acme Corp
case: K1234

The short answer

Create an EntityRuler, add a phrase or token pattern under an entity label, and call Process(doc). The example adds Acme Corp as an ORG entity. This is a spelling rule, not a statistical prediction about every organization name. No model package is needed for these rules.

What is an example of a rule-based approach?

A company dictionary is one example: label an exact phrase such as Acme Corp as ORG. A structured identifier is another: label a token whose shape is one uppercase letter followed by four digits as CASE_NO. The variation implements both and prints their rule IDs.

Phrase rules compare ORTH by default: the original spelling, including capitalization. LOWER compares lowercase spellings using .NET’s invariant culture. NORM compares the document’s normalized token value, falling back to lowercase spelling when no value was set.

For case-insensitive phrase rules, replace the ruler’s constructor line with:

C#
var ruler = new EntityRuler(false, TokenProperty.Lower);

The first argument leaves entity overwriting disabled. The ruler also accepts SHAPE for phrase comparison. Token rules can combine tests across consecutive positions, so a rule can depend on nearby words or punctuation as well as the identifier itself.

Process writes accepted spans into the document’s entities. Use FindEntities when you need the rule ID alongside each candidate selected by the ruler. IDs belong to rules and are not stored in the document’s entity annotations. The variation therefore reads RuleEntity.Id, not a property on doc.Ents.

According to the ruler documentation, competing rule matches are considered longest first. Equal lengths prefer the earlier start; an exact tie prefers the rule added first. Once a match is accepted, overlapping rule matches are dropped. This means the order of dictionary registration matters for identical spans with different labels or IDs.

By default, a rule match overlapping an existing entity is dropped. To let rule matches replace overlapping existing entities, set this property after creating the ruler and before calling Process:

C#
ruler.OverwriteEnts = true;

Each existing entity overlapped by an accepted rule match is removed.

What is the purpose of NER in NLP?

Named entity recognition marks spans and assigns labels so a program can work with mentions instead of scanning raw prose. In this rule-based example, ORG identifies the exact company phrase to a downstream consumer. Your application chooses the labels and decides what to do with them; adding a label does not resolve two differently written names to one company.

Rules are useful when you can enumerate the names or state the spelling pattern. They cannot infer an unlisted organization merely because a sentence sounds like it describes one.

Rule entities have confidence 1 under the library’s documented contract. That value is not measured evidence that the phrase is a real organization or that the dictionary is correct. A misspelled rule, an overly broad shape or an ambiguous name can still produce an unwanted entity. Test rules on examples containing both intended mentions and similar text that should remain unmarked.

All onenlp recipes