🌲 Project SILVANUS

Acoustic Nervous System for Forest Protection

An AI-powered multi-agent system for real-time forest monitoring and threat detection

About • Features • Quick Start • Architecture • Agent Pipeline • Testing • Contributing

🌐 Language: English • हिन्दी • বাংলা

---

🎯 About

Project SILVANUS is an advanced AI-driven acoustic monitoring system designed to protect forests from illegal activities. Named after the Roman god of forests, SILVANUS acts as a digital guardian for protected wilderness areas.

The system uses a Multi-Agent System (MAS) architecture with:

• Bio-acoustic analysis using CLAP embeddings
• Vector similarity search with Qdrant Cloud
• Large Language Models (Groq/OpenRouter/Ollama) for intelligent reasoning
• Real-time dashboard for monitoring and incident response

The Problem

Illegal logging, poaching, and unauthorized intrusion cause billions in environmental damage annually.

Our Solution

• ✅ 24/7 automated monitoring using acoustic sensors
• ✅ AI-powered threat detection with high accuracy
• ✅ Multi-agent verification to reduce false positives
• ✅ Real-time alerts with GPS coordinates
• ✅ Historical correlation via Supabase for pattern detection

---

✨ Key Features

Feature	Description
🎙️ Real-time Acoustic Analysis	Spectral analysis to classify sounds using librosa
🎯 Threat Detection	Identifies chainsaws, gunshots, vehicles using CLAP embeddings
🤖 Multi-Agent System	Sentinel, Analyst, Validator, Dispatcher agents verify threats
📋 Incident Reporting	Detailed reports with GPS coordinates and severity scores
🖥️ Interactive Dashboard	Next.js web interface for real-time monitoring
🔐 Secure Architecture	API key authentication and role-based access
📊 Historical Pattern Analysis	Queries Supabase for past incidents to detect repeat offenders
🧠 Hybrid Intelligence	Combines rule-based speed with LLM adaptability

---

🚀 Quick Start

# Clone the repository
git clone https://github.com/Nabarup1/Silvanus.git
cd Silvanus

# Install Python dependencies
pip install -r requirements.txt

# Run a simulation
python main.py simulate -n 10 --llm

# Analyze an audio file
python main.py analyze path/to/audio.wav --json

🚀 Start Application (Backend + Frontend)

Option 1: Automatic (Recommended) Double-click start_dev.bat or run it from the terminal:

.\start_dev.bat

This will launch both the Python Backend (Port 8000) and Next.js Frontend (Port 3000) in separate windows.

Option 2: Manual Start

1. Backend: uvicorn api:app --host 0.0.0.0 --port 8000
2. Frontend: cd web && npm run dev

Open http://localhost:3000

---

🏗️ Architecture

SILVANUS integrates advanced bio-acoustics with Agentic AI. The system is divided into three core layers:

1. Sensory Layer (The Ears): Captures audio, extracts spectral features, and generates CLAP embeddings.
2. Cognitive Layer (The Brain): A LangGraph-based Multi-Agent System that reasons about the audio context.
3. Interface Layer (The Face): A Next.js Web Dashboard for real-time monitoring and incident reporting.

🧠 The Cognitive Loop

graph TD
    subgraph SENSORS ["SENSORY LAYER"]
        Audio[Raw Audio] -->|Librosa| Features[Spectral Features]
        Audio -->|CLAP Model| Embed[Vector Embedding]
    end

    subgraph BRAIN ["COGNITIVE LAYER (Python)"]
        Embed -->|Query| Qdrant[(Forest Memory)]
        Qdrant -->|Matches| Sentinel[👮 SENTINEL NODE]
        
        Sentinel -->|Threat Detected?| Analyst[🕵️ ANALYST NODE]
        Sentinel -->|Clear| Safe[✅ Event Cleared]
        
        Analyst -->|Check Registry + Supabase| AuthDB[(Auth + History)]
        Analyst -->|Unauthorized?| Validator[🔬 VALIDATOR NODE]
        Analyst -->|Authorized| Safe
        
        Validator -->|Spectral Analysis| Decision{Threat Confirmed?}
        Decision -->|Yes| Dispatcher[🚨 DISPATCHER NODE]
        Decision -->|No| FalsePos[⚠️ False Positive]
    end

    subgraph WEB ["INTERFACE LAYER (Next.js)"]
        Dispatcher -->|JSON Report| API[Next.js API]
        API -->|Real-time| Dashboard[Web Dashboard]
        Dashboard -->|Alerts| Rangers[Forest Rangers]
    end
    
    style Sentinel fill:#1f2937,stroke:#10b981,color:#fff
    style Analyst fill:#1f2937,stroke:#3b82f6,color:#fff
    style Validator fill:#1f2937,stroke:#8b5cf6,color:#fff
    style Dispatcher fill:#ef4444,stroke:#fff,color:#fff

Loading

🌐 Frontend Data Flow

sequenceDiagram
    participant User as 👤 User
    participant UI as 🖥️ Next.js UI (Client)
    participant API as ⚡ API Route (/api/analyze)
    participant Python as 🐍 Python Core (Backend)
    participant Cloud as ☁️ Qdrant Cloud

    User->>UI: Uploads Audio File / Simulates Event
    UI->>API: POST /api/analyze (FormData)
    
    activate API
    note right of API: Spawns Python Subprocess
    API->>Python: python main.py analyze --json
    
    activate Python
    Python->>Cloud: Query Similarity (Embeddings)
    Cloud-->>Python: Return Top K Matches
    Python->>Python: Agent Loop (Sentinel->Analyst->Validator)
    Python-->>API: Returns JSON Report
    deactivate Python
    
    API-->>UI: Returns Analysis Result
    deactivate API
    
    UI->>User: Displays Evidence & Threat Assessment

Loading

📂 Repository Structure

Silvanus/
├── src/                        # 🐍 PYTHON CORE ENGINE
│   ├── agents/                 # LangGraph Agent Definitions
│   │   ├── graph.py            # Main Cognitive Loop (State Machine)
│   │   ├── state.py            # Pydantic State Models
│   │   └── tools.py            # Agent Tools (Memory/Registry/Supabase)
│   ├── audio/                  # Audio Processing Modules
│   │   ├── embeddings.py       # CLAP Model Integration
│   │   ├── features.py         # Spectral Feature Extractor
│   │   └── processor.py        # Loading & Segmentation
│   ├── memory/                 # Knowledge Base
│   │   ├── qdrant.py           # Vector DB Interface (Cloud/Local)
│   │   └── registry.py         # Authorization Rules
│   └── tools/                  # Utilities
│       ├── download_audioset.py # Bio-acoustic Dataset Downloader
│       └── ingest_audio.py     # Vector Memory Ingestion Script
├── web/                        # ⚛️ NEXT.JS FRONTEND
│   ├── src/app/                # App Router
│   │   ├── api/analyze/        # API Route connecting to Python
│   │   ├── demo/               # Interactive Demo Page
│   │   └── dashboard/          # Monitoring Dashboard
│   └── public/                 # Assets & Images
├── tests/                      # Python Test Suite
├── .github/workflows/          # CI/CD Pipelines
├── main.py                     # CLI Entry Point & Simulator
├── api.py                      # FastAPI Wrapper for Deployment
└── requirements.txt            # Python Dependencies

---

🤖 Agent Pipeline

The cognitive loop processes audio through a sequence of specialized agents:

Step	Component	Description
1	Acoustic Processor	Loads raw audio via librosa, resamples to 48kHz, segments into 5-second chunks
2	CLAP Embedder	Converts audio to 512-dimensional vector using laion/clap-htsat-fused model
3	Sentinel Agent	First responder: queries Qdrant for threat similarity, checks baseline deviation, decides CLEAR or ESCALATE
4	Analyst Agent	Context checker: verifies GPS against authorization registry, queries Supabase for historical incidents
5	Validator Agent	Scientist: performs deep spectral analysis (RMS energy, spectral centroid, ZCR) to confirm MECHANICAL or ORGANIC source
6	Dispatcher Agent	Reporter: compiles final Incident Report (INC-XXXX), assigns severity (1-10), recommends actions
7	Forest Memory	Long-term storage in Qdrant Cloud: threat signatures, baseline sounds, event history

Processing Flow:

Audio File -> CLAP Embed -> Sentinel -> Analyst (+Supabase) -> Validator -> Dispatcher -> Incident Report

---

📦 Installation

Prerequisites

Requirement	Version	Purpose
Python	3.10+	Backend & AI models
Node.js	18+	Web dashboard
Qdrant	Cloud/1.7+	Vector database
Groq	API Key	LLM Reasoning (recommended)

Backend Setup

pip install -r requirements.txt
python src/tools/download_audioset.py
python src/tools/ingest_audio.py data/audioset

Frontend Setup

cd web
npm install
npm run dev

Environment Configuration

Create .env:

# Qdrant Cloud
QDRANT_HOST=your-cluster.cloud.qdrant.io
qdrant_silvanus_key=your_api_key

# LLM Provider (Groq recommended)
USE_GROQ=true
groq_api=your_groq_api_key
groq_model=llama-3.3-70b-versatile

# Supabase (for historical analysis)
supabase_silvanus_url=your_supabase_url
supabase_silvanus_key=your_supabase_key

# API Security
SILVANUS_API_KEY=your_secret_key

---

🧪 Testing

Python Tests

pip install pytest pytest-cov
pytest tests/ -v
pytest tests/ --cov=src

Node.js Tests

cd web
npm test
npm run test:coverage

CI/CD

Workflow	Versions	Status
Python	3.10, 3.11
Node.js	18, 20

---

🤝 Contributing

1. Fork the repository
2. Create feature branch (git checkout -b feature/AmazingFeature)
3. Commit changes (git commit -m 'Add AmazingFeature')
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

---

📄 License

GNU AGPLv3 License - see LICENSE file.

---

Made with 💚 for Forest Conservation