PalmOilRipenessDetection-Python

🌴 Palm Oil Ripeness Agent (n8n + YOLOv8)

This project uses a custom-trained YOLOv8 model to detect the ripeness of Palm Oil Fresh Fruit Bunches (FFB). It features a local Python FastAPI server and a Streamlit Dashboard, both architected with Domain-Driven Design (DDD) for maximum flexibility and scalability in an agentic n8n workflow.

🚀 Project Overview

1. Vision Engine: YOLOv8 Nano (Custom-trained on MPOB-standard datasets).
2. Inference Server: FastAPI (Python) for n8n integration.
3. Visual Fingerprinting: Vertex AI Multimodal Embedding (multimodalembedding@001).
4. Archival & Reasoning: MongoDB Atlas Vector Search for similarity-based reasoning.
5. Demo Dashboard: Streamlit UI for drag-and-drop batch testing.

---

🛠 Prerequisites

• Python 3.10+
• n8n (Desktop or Self-hosted)
• MongoDB Atlas Account
• Google Cloud Platform (Vertex AI API enabled)

---

📦 Setup Instructions

1. Environment Setup

# Clone and enter the repository
git clone <your-repo-url>
cd palm-oil-ai

# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Configuration (.env)

Ensure your .env file is populated with the following keys:

• MONGO_URI: Your MongoDB Atlas connection string.
• PROJECT_ID: Your Google Cloud Project ID.
• LOCATION: Vertex AI location (e.g., us-central1).
• DB_NAME: MongoDB database name.
• COLLECTION_NAME: MongoDB collection name.
• GOOGLE_APPLICATION_CREDENTIALS: Path to your GCP service account JSON key.

---

🚦 How to Run

Running the API Server

The API acts as the bridge for n8n or mobile integrations. You can start it using the root wrapper:

# Start the FastAPI server
python main.py

Alternatively, run as a module: python -m src.api.main

Running the Streamlit Dashboard

For manual testing and visual analysis:

# Start the Streamlit app
streamlit run demo_app.py

---

🔌 API Endpoints

Endpoint	Method	Description
/detect	POST	Fast Inference: Returns YOLO detection results (JSON).
/analyze	POST	Full Process: Detection + Vertex AI Vectorization + MongoDB Archival.
/get_confidence	GET	Retrieve the current AI confidence threshold.
/set_confidence	POST	Update the AI confidence threshold globally.

---

📂 Repository Structure (DDD)

├── src/
│   ├── api/                # FastAPI entry points & route handlers
│   ├── application/        # Use Cases & Orchestration logic
│   ├── domain/             # Business Logic, Entities, & Core models
│   └── infrastructure/     # External integrations (MongoDB, VertexAI)
├── datasets/               # Labeled images (Train/Valid/Test)
├── runs/                   # YOLO training logs and output weights
├── best.pt                 # THE BRAIN: Trained model weights
├── requirements.txt        # Python dependencies
├── .env                    # Configuration state
├── LICENSE                 # MIT License
└── README.md               # You are here

📜 License

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