Metadata-Version: 2.4
Name: agba-engine
Version: 5.0.9
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
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: huggingface-hub
Requires-Dist: pillow
Requires-Dist: numpy
Dynamic: license-file

# 👑 Agba Engine: Open-Source Heritage Search Engine

**Agba Engine** is a cross-modal Vision-Language Model (VLM) architecture designed for zero-shot heritage artifact retrieval. By mapping raw visual feature representations and authentic cultural metadata into a shared 256-dimensional Interlingua space, Agba Engine bridges high-dimensional spatial geometry and globally underrepresented heritage regalia.

---

## 🌟 Key Architectural Features

* **Dual Projection Translators:** Fine-tuned linear projection heads mapped on top of OpenCLIP (`ViT-B-32`).
* **InfoNCE Contrastive Calibration:** Trained via `AdamW` optimizer, driving alignment loss from `1.9409` down to `0.0003`.
* **Zero-Shot Cultural Search:** Query tangible artifacts using free-form natural language strings.
* **Cognitive Spatial Discrimination:** Evaluates visual clarity, geometry, and occlusion over simple label memorization.

---

## 📊 Performance & Zero-Shot Validation

### Training Loss Convergence (Epochs 1 ──► 50)
* **Initial InfoNCE Baseline:** `1.9409`
* **Final Converged Loss:** `0.0003`
* **Optimizer:** `AdamW` (`lr = 5e-4`, `weight_decay = 1e-2`)

### Zero-Shot Retrieval Benchmark Results
| Search Query | Top Match Anchor | Indigenous Nomenclature | Match Confidence |
| :--- | :--- | :--- | :---: |
| `"Royal Wrist Beads"` | `wrist_frame_01.jpg` | **Ìlẹ̀kẹ̀ Ọwọ́** | **67.74%** 🎯 |
| `"Royal Leg Beads"` | `leg_frame_31.jpg` | **Ìlẹ̀kẹ̀ Ẹsẹ̀ (Macro-Left)** | **61.39%** 🎯 |

---

## 🛡️ License

Distributed under the **MIT License**. See `LICENSE` for more details.
