ethnidata 4.3.1

Name Analysis & Prediction Engine

🌍 Ethnidata: Ethical & Demographic Intelligence

Ethnidata is a specialized library for ethical demographic analysis, name-based ethnic classification, and socioeconomic profiling. It is designed to help researchers and developers understand global diversity while maintaining strict ethical standards and explainability.

---

🌟 Vision

To provide a transparent and robust framework for demographic intelligence, enabling unbiased analysis and inclusive product development through Explainable AI (XAI).

🚀 Key Features

• 🧬 Advanced Classification: High-accuracy ethnic and regional classification based on global naming patterns.
• 🔍 Explainable AI (XAI): Integral Explainer class that breaks down WHY a classification was made, citing linguistic markers.
• 📊 Demographic Synthesis: Generate privacy-safe synthetic demographic profiles for testing and simulation.
• 📉 Bias Detection: Tools to identify and mitigate representation bias in your datasets.
• 🌍 Global Coverage: Support for over 150 ethnic groups and regional clusters.

---

📦 Installation

pip install ethnidata

---

🛠️ Premium Usage

1. Unified Facade Access

The EthniData facade provides a streamlined interface for classification and explainability.

from ethnidata import EthniData

# Initialize the intelligence engine
ed = EthniData()

# 1. Classify a name with explainability
result = ed.classify("Kazuo Ishiguro", explain=True)

print(f"Name: {result.name}")
print(f"Primary Ethnicity: {result.ethnicity}")
print(f"Confidence: {result.confidence:.2f}")

# 2. Access XAI Insights
explanation = result.explanation
print("\n--- XAI Breakdown ---")
for marker in explanation.linguistic_markers:
    print(f"- Marker: {marker.token} | Strength: {marker.weight:.2f} | Origin: {marker.region}")

✅ Verified Output

Name: Kazuo Ishiguro
Primary Ethnicity: Japanese
Confidence: 0.98

--- XAI Breakdown ---
- Marker: Kazuo | Strength: 0.85 | Origin: East Asia (Japan)
- Marker: Ishiguro | Strength: 0.92 | Origin: East Asia (Japan)

2. Synthetic Profile Generation

Create high-fidelity, privacy-safe demographic data for system testing.

from ethnidata import ProfileGenerator, Region

generator = ProfileGenerator()

# Generate a batch of synthetic profiles for the Mediterranean region
profiles = generator.generate_batch(region=Region.MEDITERRANEAN, count=5)

for profile in profiles:
    print(f"Profile: {profile.name} | Age: {profile.age} | Occupation: {profile.estimated_occupation}")

✅ Verified Output

Profile: Marco Rossi | Age: 34 | Occupation: Software Engineer
Profile: Elena Papadopoulos | Age: 28 | Occupation: Architect
...

---

📊 API Reference

EthniData (Facade)

• classify(name: str, explain: bool = False) -> ClassificationResult: The primary entry point for classification.
• batch_classify(names: list, ...) -> List[ClassificationResult]: Process large datasets efficiently.
• get_explainer() -> ExplainabilityEngine: Access the raw XAI engine.

Modules

• ExplainabilityEngine: Linguistic marker analysis and evidence weighing.
• ProfileGenerator: Synthetic data engine with region-specific constraints.
• BiasAnalyzer: Statistical tools for measuring group representation.

---

🛡️ Ethics & Privacy

Ethnidata is built with a Privacy-First approach. It does not store personal data and focuses on aggregate-level linguistic patterns. We strongly recommend using this library only for research and inclusive design purposes.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.