simple_NER

Lightweight named-entity recognition library with pluggable annotators, multi-language support, and an async pipeline.

Installation

pip install simple_NER
pip install "simple_NER[dev]"   # + testing tools

Quick Start

from simple_NER import create_pipeline

pipe = create_pipeline(["email", "phone", "url", "temporal", "currency"])
for entity in pipe.process("Call +1-800-555-0100 or email info@example.com by 2025-06-01"):
    print(entity.entity_type, entity.value, entity.confidence)
# phone    +1-800-555-0100   0.9
# email    info@example.com  1.0
# date     2025-06-01        0.85

Annotators

Key annotator parameters

LocationNER: include_countries=True, include_capitals=True, include_cities=False, label_confidence={"City": 0.7, "Country": 0.95}

PhoneAnnotator: require_country_code=False, min_length=7

OrganizationAnnotator: strict_mode=False (when True, requires corporate suffix like Inc./GmbH)

TemporalNER / NumberNER / DateAnnotator / LookUpNER: lang="en-us", optionally anchor_date for TemporalNER

Entity Data Fields

Each Entity carries a data dict with annotator-specific fields:

Pipeline Dedup Strategies

NERPipeline and AsyncNERPipeline accept a dedup_strategy argument:

pipe = create_pipeline(["currency", "numbers"], dedup_strategy="keep_longest")

Locale / i18n System

Annotators load language-specific patterns from simple_NER/locale/<lang>/:

All loaders fall back to en-us when no language-specific file exists. intent_to_regex("{amount} dollars") converts an intent template to a compiled re.Pattern.

Adding a new language: create simple_NER/locale/<lang>/ and place .rx, .intent, or .txt files that override the en-us defaults. Only the files you add are used. Everything else falls back automatically. Inside a BaseAnnotator subclass, self._load_rx("name") and self._load_intents("name") resolve to self.lang automatically.

Existing locale data: en-us (phone, email, url, hashtag, currency, organization, date_months), de-de (currency, organization, date_months), es/fr/it/nl/pt (date_months).

Async Batch Processing

import asyncio
from simple_NER.annotators.async_pipeline import AsyncNERPipeline

pipe = AsyncNERPipeline(dedup_strategy="keep_longest")
pipe.add_annotator(...)

async def run():
    results = await pipe.process_batch_async(sentences, max_concurrency=10)

asyncio.run(run())

OVOS Plugin

simple_NER ships an intent-transformer plugin for the OpenVoiceOS / OVOS ecosystem. Entry-point group: opm.transformer.intent, key: simple-ner-transformer, priority 50, class: SimpleNERIntentTransformer.

{
  "intent_transformers": {
    "simple-ner-transformer": {
      "annotators": ["email", "phone", "temporal", "currency"],
      "confidence_threshold": 0.6,
      "lang": "en-us"
    }
  }
}

The transformer runs the configured pipeline on every utterance and injects recognized entities into match_data before intent handling proceeds.

Documentation

New to simple_NER? Start here:

• Getting Started: installation, first pipeline, common patterns
• FAQ & Troubleshooting: answers to common questions

Need details?

• API Reference: class and method documentation
• Complete Architecture: design, all annotators, advanced topics
• Tutorials: step-by-step guides for specific use cases

Learn by example:

• examples/README.md: 15+ runnable scripts (quick start, all annotators, async, custom types, OVOS plugin, etc.)

Project info:

• GitHub: source code, issues, discussions
• CHANGELOG.md: version history
• AUDIT.md: known issues and technical debt