Skip to content

About

AI-powered agricultural pest detection portfolio project using Laravel, FastAPI, MySQL, and a custom YOLO object detector.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

LeafGuard

AI-Powered Agricultural Pest Detection with Laravel, FastAPI, and YOLO

LeafGuard is a portfolio project that combines a Laravel web application with a Python FastAPI inference service and a custom YOLO object detector to identify five agricultural pest categories from uploaded plant images.

Overview

This public package is organized as two local services:

  • web/ — Laravel web application
  • ai/ — FastAPI inference service

LeafGuard accepts a plant image upload, sends it from Laravel to FastAPI, runs a custom YOLO model, stores the result, and presents it back in a responsive web interface with dashboard, result, and history views.

This project is a portfolio and learning prototype. It is not presented as a production agricultural diagnosis system.

Features

  • Laravel UI for dashboard, upload, results, and history
  • FastAPI inference service for computer-vision prediction
  • Custom YOLO model for five pest categories
  • Annotated result image generation
  • Human-readable pest labels and confidence display
  • no_detection handling when no supported pest is found
  • Safe failed handling when the AI service is unavailable or returns invalid data
  • Retry flow for failed detections
  • Detection history with status filtering and pagination
  • Missing-image fallback in dashboard, history, and detail views
  • Responsive Blade-based UI with shared layout

Demo / Screenshots

Main screenshots:

Dashboard Detection Result History

Additional screenshots:

More screenshot and demo notes:

Supported Pest Classes

Class ID Slug Display Label
0 wereng_coklat Wereng Coklat
1 penggerek_batang_padi_asia Penggerek Batang Padi Asia
2 ulat_grayak Ulat Grayak
3 kutu_daun Kutu Daun
4 kutu_kebul_rumah_kaca Kutu Kebul Rumah Kaca

System Architecture

flowchart LR
    U[User Browser]
    L[Laravel Web Application]
    DB[(MySQL)]
    ST[Laravel Public Storage]
    A[FastAPI AI Service]
    Y[YOLO Model]

    U --> L
    L --> DB
    L --> ST
    L -->|Multipart image request| A
    A --> Y
    Y --> A
    A -->|JSON detections + annotated image| L
    L --> DB
    L --> ST
    L --> U
Loading

See the full architecture notes in docs/portfolio/ARCHITECTURE.md.

Detection Flow

flowchart TD
    U[User uploads image] --> V[Laravel validates file]
    V --> S[Original image stored in public storage]
    S --> P[Detection row created as pending]
    P --> R[Laravel sends image to FastAPI /predict]
    R --> I[YOLO inference runs]
    I --> J[FastAPI returns detections and annotated image]
    J --> T{Any target detections?}
    T -- No --> N[Update status to no_detection]
    T -- Yes --> B[Select highest-confidence detection for top-level record]
    B --> A[Store annotated image]
    A --> C[Update status to completed]
    N --> U2[Redirect user to detail page]
    C --> U2
Loading

Tech Stack

Web application:

  • Laravel 13.25.0
  • PHP 8.4
  • Blade templates
  • MySQL
  • Laravel HTTP Client

AI service:

  • Python 3.14.6
  • FastAPI 0.141.1
  • Uvicorn 0.52.2
  • Ultralytics YOLO 8.4.118
  • Pillow 12.3.0
  • PyTorch 2.13.0

Frontend tooling present in the Laravel project:

  • Vite
  • Tailwind CSS 4

Project Structure

LeafGuard_Portfolio/
├── web/
│   ├── app/
│   ├── config/
│   ├── database/
│   ├── resources/views/
│   ├── routes/
│   └── tests/
├── ai/
│   ├── evaluation_external/
│   ├── models/
│   ├── scripts/
│   ├── main.py
│   └── requirements.txt
├── docs/
│   ├── portfolio/
│   └── testing/
├── README.md
├── SETUP.md
└── DEMO.md

AI Model

Production model identity:

  • Name: LeafGuard YOLO v1
  • Location: ai/models/best.pt
  • SHA-256: dc4758142f40b1a0dc89fddfbd7895e475c41a8c04584c04b674ea59bfce7df2

Model Evaluation

The project documents two different evaluation views:

  1. Internal frozen test split evaluation on IP102-based data
  2. External image-level generalization evaluation on a separately sourced image set

Internal Test Evaluation

Metric Value
Precision ≈ 0.8376
Recall ≈ 0.8839
mAP50 ≈ 0.8645
mAP50-95 ≈ 0.5231

These values are internal, in-distribution metrics on a frozen IP102-based test split.

External Generalization Evaluation

External Evaluation Set v1:

  • 30 images total
  • 25 target images
  • 5 non-target images
  • provenance and licenses documented
  • exact duplicate overlap with the internal dataset checked as zero before inference

External image-level metrics:

Metric Value
Target top-1 correctness 12 / 25 = 48.0%
Target detection rate 84.0%
Average confidence on correct target predictions 71.31%
Non-target false positive rate 3 / 5 = 60.0%

Important note:

  • the external set did not include full bounding-box ground truth for formal object-detection scoring
  • external mAP / IoU was therefore not calculated
  • 48.0% is an image-level top-1 correctness figure, not mAP and not a generic object-detection accuracy claim

See docs/portfolio/MODEL_EVALUATION.md for the full write-up.

Limitations

  • There is a visible generalization gap between internal frozen-test results and the external evaluation set.
  • kutu_kebul_rumah_kaca (greenhouse whitefly) performed poorly on the external set.
  • Non-target false positives remain high on the small external benchmark.
  • The external evaluation set is small at 30 images.
  • The application only supports five pest classes.
  • no_detection does not mean the plant is healthy.
  • This is a portfolio and learning prototype, not a production diagnosis tool.

Functional Testing

  • Laravel automated tests: 27 tests, 107 assertions, PASS
  • Formal black-box testing: 24 / 24 PASS
  • Oversized upload regression (BB-006) was initially found to fail with an HTTP 500, then fixed and re-tested successfully

Important distinction:

  • 24 / 24 PASS refers to application functional behavior
  • it does not mean the AI model is perfectly accurate

See docs/portfolio/TESTING.md.

Running Locally

See SETUP.md.

Short version:

Start the AI service first:

cd ai
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python -m uvicorn main:app --host 127.0.0.1 --port 8001

Start Laravel:

cd web
composer install
copy .env.example .env
php artisan key:generate
php artisan migrate
php artisan storage:link
php artisan serve --host=127.0.0.1 --port=8000

Configuration

Example Laravel environment values:

APP_URL=http://127.0.0.1:8000
LEAFGUARD_AI_URL=http://127.0.0.1:8001
DB_DATABASE=leafguard
DB_USERNAME=your_mysql_username
DB_PASSWORD=your_mysql_password

Do not commit real credentials.

API

FastAPI endpoints used by the application:

  • GET /
  • GET /health
  • POST /predict

Data / Model Notes

High-level detection record fields:

  • image_path
  • pest_name
  • confidence
  • status
  • description
  • timestamps

Statuses:

  • pending
  • completed
  • no_detection
  • failed

Future Improvements

Model Improvement v2 was investigated but deferred because there was not enough independently sourced, clearly licensed, correctly annotated new training data to justify a rigorous final retraining cycle.

License / Attribution

Repository license has not yet been selected.

The package includes evaluation reports and attribution-supporting metadata. Full external evaluation source images are not bundled here.

Disclaimer

LeafGuard is a portfolio project for demonstrating full-stack integration, computer-vision inference wiring, testing, and documentation. It should not be used as a standalone agricultural diagnosis system.

Additional Documentation

About

AI-powered agricultural pest detection portfolio project using Laravel, FastAPI, MySQL, and a custom YOLO object detector.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages