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.
This public package is organized as two local services:
web/— Laravel web applicationai/— 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.
- 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_detectionhandling when no supported pest is found- Safe
failedhandling 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
Main screenshots:
Additional screenshots:
More screenshot and demo notes:
| 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 |
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
See the full architecture notes in docs/portfolio/ARCHITECTURE.md.
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
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
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
Production model identity:
- Name:
LeafGuard YOLO v1 - Location:
ai/models/best.pt - SHA-256:
dc4758142f40b1a0dc89fddfbd7895e475c41a8c04584c04b674ea59bfce7df2
The project documents two different evaluation views:
- Internal frozen test split evaluation on IP102-based data
- External image-level generalization evaluation on a separately sourced image set
| 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 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.
- 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_detectiondoes not mean the plant is healthy.- This is a portfolio and learning prototype, not a production diagnosis tool.
- 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 PASSrefers to application functional behavior- it does not mean the AI model is perfectly accurate
See docs/portfolio/TESTING.md.
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 8001Start 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=8000Example 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_passwordDo not commit real credentials.
FastAPI endpoints used by the application:
GET /GET /healthPOST /predict
High-level detection record fields:
image_pathpest_nameconfidencestatusdescription- timestamps
Statuses:
pendingcompletedno_detectionfailed
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.
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.
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.


