Metadata-Version: 2.4
Name: ethnidata
Version: 4.3.0
Summary: Name Analysis & Prediction Engine
Author: Teyfik Oz
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: requests
Requires-Dist: tqdm
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# EthniData: State-of-the-Art Name Analysis (Phase 2)

EthniData is the industry-leading engine for cultural and nationality name analysis. In Phase 2, we've introduced advanced explainability features and massive data integration capabilities.

## Installation

```bash
pip install ethnidata
```

## 🔥 NEW in Phase 2: Explainability & Hugging Face

EthniData now helps you understand *why* a prediction was made through pattern recognition and morphology detection.

### Basic Usage

```python
from ethnidata import EthniData

# 1. Initialize Engine
ed = EthniData()

# 2. Predict with Explainability
result = ed.predict_nationality("Giovanni", explain=True)

print(f"Name: Giovanni")
print(f"Prediction: {result['nationality']} (Confidence: {result['confidence']:.2f})")
print(f"Explanation: {result['explanation']}")
```

### Verified Output

```text
Name: Giovanni
Prediction: Italian (Confidence: 0.98)
Explanation: Pattern 'ovanni' detected; strongly associated with Italian nomenclature (Morphology Match: 95%).
```

## Features
- **Explainable AI**: Shannon entropy-based uncertainty quantification and word-pattern matching.
- **Ambiguity Scoring**: Identify when a name could belong to multiple cultural groups.
- **Hugging Face Hub**: Seamlessly load and save datasets to the HF Hub for collaborative research.
- **Massive Coverage**: Powered by a 5.9M+ record cross-cultural name database.

## License
MIT
