Field Entity Analyzer

field_entity_analyzer is a high-performance, 100% offline, self-contained Python library for identifying and classifying entity types from input strings (such as Email, Phone Number, Postal Code, Credit Card, Government ID, Address, and Person Name).

Key Features

• 100% Offline & Private: Zero network requests, zero external web service dependencies.
• Ultra Lightweight: Embedded model weights packaged inside binary wheel (< 1 MB wheel size).
• Multi-Engine Cascading Architecture:
  1. Pattern & Algorithmic Rule Engine: Regex matching and checksum validation (e.g. Luhn algorithm for Credit Cards, SSN/PAN/Aadhaar formats).
  2. Contextual Heuristic & Token Parser: Structural layout analysis, address indicator tokens, title prefixes, name patterns.
  3. Lightweight Embedded Classifier: Fast, pre-trained character and token feature classifier asset embedded inside the package.
• Python 3.8+ Compatibility: Clean, typed, dependency-light package.

Supported Entity Types

• EMAIL
• PHONE
• POSTAL_CODE
• CREDIT_CARD
• GOVERNMENT_ID
• ADDRESS
• NAME
• UNKNOWN

Installation

pip install field_entity_analyzer

Or install from source:

git clone https://github.com/example/field_entity_analyzer.git
cd field_entity_analyzer
pip install .

Quick Start

from field_entity_analyzer import EntityAnalyzer, analyze_entity

# 1. Using top-level convenience function
result = analyze_entity("john.doe@example.com")
print(result.entity_type) # EntityType.EMAIL
print(result.confidence)  # 1.0
print(result.engine)      # "rules"

# 2. Using EntityAnalyzer instance
analyzer = EntityAnalyzer()

samples = [
    "4532 0151 1283 0366",
    "+1 (555) 234-5678",
    "123 Main Street, Apt 4B, Springfield",
    "Dr. Alexander Hamilton",
    "90210",
    "123-45-6789",
]

for text in samples:
    res = analyzer.analyze(text)
    print(f"'{text}' -> {res.entity_type.value} (conf: {res.confidence:.2f}, engine: {res.engine})")

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                       Input String                          │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Engine 1: Pattern & Algorithmic Rule Engine                 │
│ - Compiled Regex for Email, Phone, Postal Code              │
│ - Checksum & Format Validation for ID numbers & Cards       │
└──────────────────────────────┬──────────────────────────────┘
                               │ (If no deterministic match)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Engine 2: Contextual Heuristic & Token Parser               │
│ - Address Suffix & Indicator Matching (Street, Road, Apt)   │
│ - Person Name Structure Analysis (Title Case, Capitalized)  │
└──────────────────────────────┬──────────────────────────────┘
                               │ (Fallback)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Engine 3: Lightweight Embedded Classifier                   │
│ - Pre-trained compressed model file inside package assets   │
│ - Located at `src/field_entity_analyzer/assets/` (< 1 MB)   │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ Output: Classification Result `{entity_type, confidence}`   │
└─────────────────────────────────────────────────────────────┘

License

MIT License.