Metadata-Version: 2.4
Name: agba-engine
Version: 5.1.6
Summary: Multi-Modal, Diacritic-Preserving Cultural Heritage Retrieval Framework
Author-email: Aruna Olanrewaju Kabiru <only1mooseylion@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/AgbaVLMengine/Agba-Engine
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers
Requires-Dist: huggingface-hub
Requires-Dist: pillow
Requires-Dist: numpy

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

**Version:** 5.1.6  
**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.1.6
```

---

## 🚀 Quickstart & Usage Examples

### Example 1: Diacritic-Preserving Text Indexing with Rich Metadata
Standard LLM tokenizers flatten tonal marks. Agba Engine maintains parallel canonical and ASCII representation vectors alongside rich cultural descriptions.

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

engine = AgbaSearchEngine()
query_text = 'Fìlà Gọ̀bị́'
results = engine.search_by_text(query_text, top_k=3)

top_match = results[0]
print(f"ID: {top_match['id']}")
print(f"Class: {top_match['classification']}")
print(f"Description: {top_match['description']}")
print(f"Score: {top_match['score']:.4f}")
```

### Example 2: Zero-Shot Cross-Modal Visual Retrieval
Perform zero-shot similarity search across physical heritage artifacts using vision-language representation vectors.

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

engine = AgbaSearchEngine()
image_input = Image.open('sample_artifact.jpg')
matches = engine.search_by_vision(image_input, top_k=3)

print(f"Top Match: {matches[0]['id']} ({matches[0]['classification']})")
print(f"Confidence Score: {matches[0]['score']:.4f}")
```

---

## 🛠️ API Reference & Key Functions

| Method / Property | Return Type | Description |
| :--- | :--- | :--- |
| `AgbaSearchEngine()` | `Object` | Initializes core engine & lazy-loads zero-shot VLM pipeline. |
| `.search_by_text(query, top_k=5)` | `List[Dict]` | Executes diacritic-preserving text retrieval returning canonical scripts, classifications, and rich metadata. |
| `.search_by_vision(image, top_k=5)` | `List[Dict]` | Queries visual vector space returning top-ranked artifact classifications and similarity scores. |
| `.version` | `str` | Returns active engine build version (`5.1.6`). |
| `.ethical_license` | `str` | Returns active RAIL 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 or contact the author.
