Metadata-Version: 2.4
Name: agba-engine
Version: 5.0.8
Summary: A multi-modal, diacritic-preserving cultural heritage retrieval engine.
Author: Aruna Olanrewaju Kabiru
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch
Requires-Dist: huggingface_hub
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 🏛️ Agba Engine (`agba-engine`)

**Version:** 5.0.8  
**Author & Lead Architect:** Aruna Olanrewaju Kabiru  
**License:** RAIL-Cultural-Heritage-v1.0 (Prohibits unauthorized commodification & identity distortion)

Agba Engine is a multi-modal, diacritic-preserving retrieval framework designed for indexing global heritage assets, indigenous scripts, and tonal orthographies without semantic stripping.

---

## 📦 Installation

```bash
pip install agba-engine==5.0.8
```

---

## 🚀 Quickstart & Usage Examples

### Example 1: Diacritic-Preserving Text Indexing
Standard LLM tokenizers flatten tonal marks. Agba Engine maintains parallel canonical and ASCII representation vectors.

```python
from agba_engine.core.engine import AgbaSearchEngine

engine = AgbaSearchEngine()
query_text = "Fìlà Gọbi"
results = engine.search_by_text(query_text, top_k=3)

for res in results:
    print(f"ID: {res['id']} | Score: {res['score']:.4f}")
```

---

### Example 2: Cross-Modal Visual Retrieval
Perform similarity search across physical heritage artifacts using vision feature tensors.

```python
import torch
from agba_engine.core.engine import AgbaSearchEngine

engine = AgbaSearchEngine()
image_tensor = torch.randn(1, 512)
matches = engine.search_by_vision(image_tensor, top_k=3)

print(f"Top Match: {matches[0]['id']} ({matches[0]['category']})")
```

---

### Example 3: Normalizing & Sanitizing Cultural Labels
Process raw dataset strings into clean, user-facing native orthography.

```python
from agba_engine.utils.sanitizer import sanitize_cultural_label

raw_identifier = "Fìlà_Gọbi_02_Spoken"
clean_label = sanitize_cultural_label(raw_identifier)
print(clean_label)  # Output: "Fìlà Gọbi"
```

---

## 🛠️ API Reference & Key Functions

| Method / Property | Return Type | Description |
| :--- | :--- | :--- |
| `AgbaSearchEngine()` | `Object` | Initializes core engine & fetches remote weights if missing locally. |
| `.search_by_text(query, top_k=5)` | `List[Dict]` | Executes text retrieval across canonical tonal scripts and ASCII fallbacks. |
| `.search_by_vision(tensor, top_k=5)` | `List[Dict]` | Queries the visual vector space using a 512-dim image embedding. |
| `.version` | `str` | Returns active engine build version (`5.0.8`). |
| `.ethical_license` | `str` | Returns active governance framework parameters. |

---

## 🌐 Enterprise & Quad-Vector Audio Alignment
The open-source core provides tri-vector functionality (Canonical Text, ASCII, and Vision).

For high-density **Quad-Vector Audio Integration** (including **Gangan pitch-contour mapping** and spoken native vocalization models for archives and museums), visit our [Hugging Face Space](https://huggingface.co/spaces/OcculusPanther/Agba-engine-demo) or contact the author.
