Metadata-Version: 2.4
Name: field_entity_analyzer
Version: 0.2.2
Summary: Self-contained offline NLP entity and field classification library.
Author: Field Entity Analyzer Team
License: MIT
Keywords: nlp,entity-recognition,field-analyzer,offline-nlp,regex,heuristics,text-classification
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: joblib>=1.0.0
Dynamic: license-file

# 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

```bash
pip install field_entity_analyzer
```

Or install from source:

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

## Quick Start

```python
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.
