BioSentinel AI 🌿

AI-powered Wildlife Conservation Platform Built with Flask · Gemini Vision · YOLOv8 · MySQL · Docker

---

🎯 What Is BioSentinel AI?

BioSentinel AI is a production-grade, AI-powered platform for wildlife conservation researchers and field rangers. Upload a wildlife image and within seconds the platform:

1. Identifies species using Google Gemini Vision
2. Draws bounding boxes and counts animals using YOLOv8
3. Retrieves IUCN conservation status (Endangered, Vulnerable, etc.)
4. Generates a scene summary and expert conservation recommendations
5. Produces PDF, CSV, Excel, and AI-enhanced conservation reports
6. Visualises everything in a beautiful dark-mode dashboard with Chart.js

The backend REST API is designed from the ground up to power both the web dashboard and a future Flutter mobile app.

---

🏗️ Architecture

Browser / Flutter App
        ↓
   Nginx (reverse proxy + static files)
        ↓
   Flask (Gunicorn) — REST API
        ↓
   Services Layer (business logic)
   ├── auth_service.py
   ├── upload_service.py
   ├── ai_service.py       ← Gemini Vision + YOLO
   ├── dashboard_service.py
   ├── history_service.py
   └── report_service.py   ← PDF / CSV / Excel
        ↓
   MySQL 8 (connection pool)

Principles:

• Routes = thin controllers (no business logic)
• Services = all logic (testable, reusable)
• database.py = all DB access via connection pool
• JWT stateless authentication
• Every API response follows { success, message, data } envelope

---

🚀 Quick Start

1. Prerequisites

• Python 3.11+
• MySQL 8.0+
• (Optional) Docker + Docker Compose

2. Clone & Setup

git clone https://github.com/divyamc1803/BioSentinelAI.git
cd BioSentinelAI

# Create virtual environment
python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

# Install dependencies
pip install -r requirements.txt

3. Configure Environment

cp .env.example .env
# Edit .env and fill in:
#   SECRET_KEY, JWT_SECRET_KEY
#   DB_HOST, DB_USER, DB_PASSWORD, DB_NAME
#   GEMINI_API_KEY  ← get from https://aistudio.google.com

4. Create Database

mysql -u root -p < database.sql

5. Run (Development)

python app.py

Open → http://localhost:5001 API Docs → http://localhost:5001/api/docs/

---

🐳 Docker

# Copy and configure .env
cp .env.example .env

# Build and start all services
docker-compose up --build

# Open
# App   → http://localhost
# MySQL → localhost:3306

---

📡 REST API

Method	Endpoint	Auth	Description
POST	/api/auth/register	—	Create account
POST	/api/auth/login	—	Login, get JWT
GET	/api/auth/profile	✅	Get user profile
POST	/api/auth/logout	✅	Logout
POST	/api/upload	✅	Upload wildlife image
GET	/api/uploads	✅	List uploads (paginated)
GET	/api/uploads/<id>	✅	Single upload detail
POST	/api/analyze/<upload_id>	✅	Trigger AI analysis
GET	/api/analysis/<id>	✅	Get analysis result
GET	/api/dashboard/stats	✅	KPI counters
GET	/api/dashboard/recent	✅	Recent activity
GET	/api/dashboard/charts	✅	Chart datasets
GET	/api/history	✅	Paginated history
GET	/api/history/<id>	✅	Analysis detail
GET	/api/reports/<id>/pdf	✅	Download PDF report
GET	/api/reports/<id>/csv	✅	Download CSV report
GET	/api/reports/<id>/excel	✅	Download Excel report
GET	/api/reports/<id>/conservation	✅	Download conservation PDF

Full Swagger docs: /api/docs/

---

🧠 AI Stack

Gemini Vision (Primary)

• Model: gemini-1.5-flash
• Returns: species name, scientific name, count, confidence, IUCN status, scene summary, recommendations
• Strict JSON output via system prompt

YOLOv8 (Secondary)

• Model: yolov8n.pt (auto-downloaded on first run)
• Returns: bounding boxes [x1,y1,x2,y2], class labels, confidence
• YOLO boxes are merged into Gemini species results

---

📊 Reports

Format	Contents
PDF	Full analysis report with species table, statistics
CSV	Tabular data for data analysis tools
Excel (.xlsx)	Styled workbook with formatted species table
Conservation PDF	AI-enhanced report with IUCN threat colour coding

---

🗄️ Database Schema

users               — user accounts (auth)
uploads             — image upload metadata
analyses            — AI analysis results (1:1 with uploads)
detected_animals    — per-species detections (many:1 with analyses)
reports             — generated report file metadata

---

🧪 Tests

pytest tests/ -v

Test coverage:

• Auth (register, login, profile, logout)
• Upload (validation, listing, detail)
• AI (Gemini mock, YOLO mock, orchestrator)
• Dashboard (stats, recent, charts)

---

📁 Project Structure

BioSentinelAI/
├── app.py                  # Flask application factory
├── config.py               # All configuration
├── database.py             # Connection pool + helpers
├── database.sql            # Full MySQL schema
├── requirements.txt
├── Dockerfile              # Multi-stage Docker build
├── docker-compose.yml      # Flask + MySQL + Nginx
│
├── routes/                 # Thin controllers (Blueprint)
│   ├── auth.py
│   ├── upload.py
│   ├── ai.py
│   ├── dashboard.py
│   ├── history.py
│   └── reports.py
│
├── services/               # Business logic
│   ├── auth_service.py
│   ├── upload_service.py
│   ├── ai_service.py
│   ├── dashboard_service.py
│   ├── history_service.py
│   └── report_service.py
│
├── templates/              # Jinja2 HTML templates
│   ├── base.html
│   ├── index.html          # Login / Register
│   ├── dashboard.html
│   ├── upload.html
│   ├── analysis.html
│   ├── history.html
│   └── reports.html
│
├── static/
│   ├── css/main.css        # Design system
│   └── js/
│       ├── app.js          # Core (WG namespace)
│       ├── dashboard.js    # Chart.js charts
│       ├── upload.js       # Drag & drop + progress
│       └── analysis.js     # Bounding box canvas
│
├── nginx/nginx.conf        # Nginx reverse proxy
├── .github/workflows/ci.yml # GitHub Actions CI/CD
│
├── tests/
│   ├── conftest.py
│   ├── test_auth.py
│   ├── test_upload.py
│   ├── test_ai.py
│   └── test_dashboard.py
│
├── uploads/                # Uploaded images (gitignored)
└── reports/                # Generated reports (gitignored)

---

🗺️ Roadmap

Version	Features
v1 ✅	Species ID, conservation status, scene summary, reports, dashboard
v2 🔜	Injury detection, behaviour, habitat, poaching risk, danger level
v3 🔜	GPS mapping, heatmaps, monthly reports, species trends
v4 🔜	Natural language search ("Show all tiger sightings from July")
v5 🔜	Camera trap batch processing, automatic reports
Future	Bird audio recognition, RAG over wildlife papers, Flutter app

---

📄 License

MIT License — see LICENSE

---

Built with 💚 for wildlife conservation. Every line of code helps protect our planet's biodiversity.