# 🌴 Palm Oil FFB Management System (YOLO26)
> **⚠️ PROTOTYPE / PROOF OF CONCEPT (PoC)** > This system is developed strictly for demonstration purposes to potential clients and is **not intended for production use** in its current state.

A high-fidelity AI prototype for detecting the ripeness of Palm Oil Fresh Fruit Bunches (FFB) according to MPOB standards. Built on a custom-trained **YOLO26** model (utilizing the latest high-performance architecture via `ultralytics`) with a **triple-engine inference backend** and a specialized 5-tab operations dashboard.

LINK for GOOGLE DOC: https://docs.google.com/document/d/1bbdGuLCGHdnHj_iCQIreh9DlYwu12PDUEPpA2eCsR-M/edit?usp=sharing
---

## 🚀 Project Overview

| Component | Technology | Purpose |
| :--- | :--- | :--- |
| **Primary Engine** | YOLO26 (Latest SOTA Backbone) | High-accuracy FFB Ripeness Detection. |
| **ONNX Runtime** | `onnxruntime` + `best.onnx` | Ultra-fast edge inference simulation (~39ms). |
| **PyTorch Runtime** | `ultralytics` + `best.pt` | High-resolution auditing and verification. |
| **Benchmark Engine** | YOLOv8-Sawit (`sawit_tbs.pt`) | Competitive baseline comparison. |
| **Inference Server** | FastAPI (Python) | REST API for multi-client orchestration. |
| **Local Audit Log** | SQLite (`palm_history.db`) | **Primary** offline-first data persistence. |
| **Operations UI** | Streamlit (`demo_app.py`) | 5-tab industrial management dashboard. |

---

## 🛠️ Triple-Engine Inference Logic
The system demonstrates three distinct AI pathways to showcase deployment flexibility:

1.  **YOLO26 (ONNX)**: Optimized for zero-latency scenarios. It utilizes normalized coordinates ($0.0$ to $1.0$) mapped back to original resolution via a custom scaling handler.
2.  **YOLO26 (PyTorch)**: The native "Ground Truth" engine. It provides absolute pixel coordinates and serves as the benchmark for high-resolution audits.
3.  **YOLOv8-Sawit (Benchmark)**: A third-party model implementation. It allows clients to see how the custom YOLO26 architecture performs against standard industry baselines.

---

## 🖥️ Demonstration Features (Streamlit)

* **Tab 1: Single Analysis**: Drag-and-drop detection with interactive Plotly overlays and a "Manager's Dashboard" for OER (Oil Extraction Rate) yield-loss insights.
* **Tab 2: Batch Processing**: Simulates a full harvest day by processing multiple images under a specific metadata context (Estate, Block, Harvester) and generating an **Executive PDF Report**.
* **Tab 3: Similarity Search (KIV)**: *Keep In View.* Currently staged for future integration. Designed for visual and natural language search via Vertex AI.
* **Tab 4: History Vault**: A local audit log showing every analysis performed. It displays archived images alongside their raw mathematical tensors.
* **Tab 5: Batch Reviewer**: An auditor's tool to browse `manifest.json` data contracts and verify resolution-agnostic `norm_box` coordinates.

---

## 🚧 Status & Future Roadmap (KIV)
The following features are currently **KIV (Keep In View)** and are disabled in the current prototype due to cloud service constraints:

* **Cloud Archival**: Automatic vectorization of detections to MongoDB Atlas.
* **Semantic Search**: Visual similarity and Natural Language search via Vertex AI Multi-modal embeddings.
* **Vertex AI Integration**: Currently experiencing issues; the system gracefully degrades to **Local-Only Mode** for stable demonstrations.

---

## 🔌 Running the Demonstration

### 1. Start the FastAPI Backend
The API server must be running to provide the NMS-Free inference logic.
```powershell
python main.py
```

### 2. Launch the Operations Dashboard
In a separate terminal, run the Streamlit UI:
```powershell
streamlit run demo_app.py
```

### 3. Local Data Contract
Every batch job generates a `manifest.json` in `batch_outputs/`. This file demonstrates the "Subscriber Payload"—a clean JSON structure ready for hand-off to corporate ERP systems or future vector databases.

---

## 🏗️ Architecture (DDD)
The prototype follows **Domain-Driven Design** to ensure that while this is a PoC, the underlying logic is built on a scalable enterprise foundation:
* `src/api/`: Model orchestration and API endpoints.
* `src/application/`: Industrial use cases (Batch, Analysis).
* `src/domain/`: Core `PalmOilBunch` business entities.
* `src/infrastructure/`: Repository logic and AI Service wrappers.