Metadata-Version: 2.4
Name: field_entity_analyzer
Version: 0.3.0
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, organizing, and classifying entity types from raw text strings and multi-line OCR document scans (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).
- **Disorganized Multi-Line Document Parsing:** Automatically cleans, parses, merges split addresses, and groups disorganized multi-line inputs into structured entity buckets.
- **Multi-Engine Cascading Architecture:**
  1. **OCR Pre-processing & Noise Repair Engine:** Strips boundary scan noise (`===`, `~~~`, `|___`), normalizes whitespace, and repairs character swaps (`O` $\leftrightarrow$ `0`, `I` $\leftrightarrow$ `1`, `S` $\leftrightarrow$ `5`, `Z` $\leftrightarrow$ `2`).
  2. **Pattern & Algorithmic Rule Engine:** Regex matching and checksum validation (e.g. Luhn algorithm for Credit Cards, SSN/PAN/Aadhaar formats).
  3. **Contextual Heuristic & Token Parser:** Structural layout analysis, address indicator tokens, key-value anchors (`Name:`, `Address:`, `Email:`), title prefixes, name patterns.
  4. **Lightweight Embedded Classifier:** Fast, pre-trained character and token feature classifier asset embedded inside the package.

## Supported Entity Types

- `EMAIL`
- `PHONE`
- `POSTAL_CODE`
- `CREDIT_CARD`
- `GOVERNMENT_ID`
- `ADDRESS`
- `NAME`
- `UNKNOWN`

## Installation

```bash
pip install field_entity_analyzer
```

## Quick Start & Disorganized Multi-Line Demo

Even if your input text is completely scrambled or disorganized (e.g., Name $\rightarrow$ Email $\rightarrow$ Phone $\rightarrow$ Name $\rightarrow$ Address $\rightarrow$ Government ID), `analyze_document()` automatically cleans the noise, repairs OCR swaps, merges split address lines, and organizes the entities into clean categorized buckets (`grouped_entities`).

```python
from field_entity_analyzer import EntityAnalyzer, analyze_entity

# Initialize analyzer
analyzer = EntityAnalyzer()

# Disorganized & Noisy Multi-line Input String (Scrambled Order + OCR Noise)
disorganized_ocr_text = """
=========================================================
|___ CONFIDENTIAL DOCUMENT SCAN ___|
~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~ ~~~
Name: J0hn D0e
sarah.connor @ sky.net
Phone: +1 (S55) O19-2834
Alexander Hamilton
Flat 4B, Bldg 12
Baker Road, Sector 5
Springfield Pincode 90210
ID No: SSN-123-45-6789
Card No: 4532 O151 1283 S366
=========================================================
"""

# Analyze multi-line text
result = analyzer.analyze_document(disorganized_ocr_text)

# 1. Organized Entity Buckets (Grouped by Category)
print("=== ORGANIZED ENTITIES ===")
for entity_type, items in result["grouped_entities"].items():
    if items:
        print(f"{entity_type}: {items}")

# 2. Extracted Key-Value Label Anchors
print("\n=== ANCHORED FIELDS ===")
print(result["anchored_fields"])

# 3. Merged Multi-line Address Blocks
print("\n=== MERGED ADDRESSES ===")
print(result["aggregated_addresses"])
```

### Expected Output

```text
=== ORGANIZED ENTITIES ===
EMAIL: ['sarah.connor@sky.net']
PHONE: ['+1 (555) 019-2834']
CREDIT_CARD: ['4532 0151 1283 5366']
GOVERNMENT_ID: ['SSN-123-45-6789']
ADDRESS: ['Flat 4B, Bldg 12, Baker Road, Sector 5, Springfield Pincode 90210']
NAME: ['J0hn D0e', 'Alexander Hamilton']

=== ANCHORED FIELDS ===
{'name': 'J0hn D0e', 'phone': '+1 (S55) O19-2834', 'card_number': '4532 O151 1283 S366', 'id_number': 'SSN-123-45-6789'}

=== MERGED ADDRESSES ===
['Flat 4B, Bldg 12, Baker Road, Sector 5, Springfield Pincode 90210']
```

## Single String Usage

```python
# Analyze a single string value
res = analyze_entity("john.doe@example.com")
print(res.entity_type) # EntityType.EMAIL
print(res.confidence)  # 1.0
print(res.engine)      # "rules"
```

## License

MIT License.
