architecture.md

# Architecture

How InsectNet integrates with BirdNET-Pi and why it's designed this way.

## BirdNET-Pi Model

BirdNET-Pi uses a **socket-based client-server architecture** for audio analysis:

```
arecord (15s WAV → StreamData/)
  └→ birdnet_analysis.sh (shell loop)
       └→ analyze.py (socket client on port 5050)
            └→ BirdNET-Lite server loads WAV, runs TFLite, returns CSV
                 └→ detection: WAV → Extracted/By_Date/{species}/
                 └→ no detection: WAV deleted
```

Key design patterns InsectNet mirrors:
- **Binary WAV lifecycle** — every WAV is processed once. Keep or delete, no middle state.
- **Detection-only persistence** — non-detections produce zero artifacts.
- **Shell-based orchestration** — each service is an independent systemd unit.

## InsectNet's Role

InsectNet is a **read-only sidecar**. It never touches BirdNET-Pi's files — it
reads StreamData/ via inotify and copies WAVs to its own directory before
BirdNET-Pi deletes them.

```
StreamData/ (new WAV)
  │
  ├──→ BirdNET-Lite (port 5050) → CSV → keep/delete
  │
  └──→ InsectNet inotify → copy WAV → librosa → TFLite → logits → sklearn → keep/delete
                                                                              │
                                                          captures/{class}/{ts}_{cls}_{conf}.wav
                                                          detections.jsonl (append)
```

## Why BirdNET Logits

InsectNet classifiers train on BirdNET's **6,522-dim logit space**, not raw
audio. This is possible because BirdNET v2.4 has 31 Orthoptera species in its
label set — field crickets, tree crickets, conehead katydids, ground crickets,
and meadow katydids. The logit space already encodes insect acoustic structure.

Cicadas are absent from BirdNET's labels, but their acoustic features still
produce distinguishable patterns in the logit space (confirmed by field
validation with cosine similarity against training centroids).

## Classifier Architecture

All production InsectNet classifiers use:

```
StandardScaler → OneVsRest(LogisticRegression(C=0.1, class_weight='balanced'))
```

- **StandardScaler** normalizes the 6,522-dim logit vectors
- **OneVsRest** trains one binary classifier per class (sigmoid output)
- **LogisticRegression** with L2 regularization (C=0.1), balanced class weights

This is the same architecture BirdNET uses internally without the softmax —
sigmoid-per-class allows multi-label predictions (one clip can be both
"cicada_drone" and "frog").

## Multi-Label Training

Training data format: clips are labeled with lists of active classes, not a
single category. A clip containing overlapping frog and cricket calls is
labeled `["frog", "cricket_katydid"]`.

`MultiLabelBinarizer` converts to an indicator matrix. Per-class
F1-optimized thresholds are swept 0.1-0.95 during evaluation. Each class gets
its own decision threshold.

## Background Training Data

Background clips come from two sources:
1. **BirdNET bird clips** — every labeled bird clip is confirmed non-insect
   audio from the same microphone and environment.
2. **Public datasets** (ESC-50 for environmental noise, iNatSounds for
   labeled insect audio).

## Two-Tier System

InsectNet operates at two levels:

| Layer | Runs On | Backbone | Purpose |
|-------|---------|----------|---------|
| **Sidecar** | BirdNET-Pi (Pi 4) | BirdNET TFLite logits | Real-time capture, keeps WAVs |
| **Archive** | Workstation | Perch 2.0 embeddings | Offline enrichment, multi-taxa discovery |

The sidecar is the edge capture system. The archive (separate repo) is the
analysis layer that pulls captures, embeds them with Perch 2.0, and enables
multi-taxa classification. They are complementary.

## BirdNET Species Coverage

BirdNET v2.4 has 6,522 species labels. Insect-relevant coverage:

| Group | In BirdNET? | Notes |
|-------|-------------|-------|
| 31 Orthoptera (crickets, katydids) | ✅ | Field crickets, tree crickets, coneheads, ground crickets, meadow katydids |
| 0 Cicada species | ❌ | Zero cicada labels — relies on general acoustic features |
| 0 Bee species | ❌ | Zero Hymenoptera labels |
| 0 Grasshopper species | ❌ | Though some Acrididae may trigger Orthoptera channels |

This means 31 logit channels carry insect-class information directly; the
other 6,491 channels may carry incidental insect structure.

## BirdNET-Pi Access

Default credentials:
- **Host:** 192.168.1.223
- **User:** birdnetpi / birdnetpi
- **Python:** `/home/birdnetpi/BirdNET-Pi/birdnet/bin/python3`
- **Model:** `/home/birdnetpi/BirdNET-Pi/model/BirdNET_GLOBAL_6K_V2.4_Model_FP16.tflite`
- **StreamData:** `/home/birdnetpi/BirdSongs/StreamData/`

The sidecar expects the TFLite model at `DEFAULT_BIRDNET_MODEL` and StreamData
at `DEFAULT_STREAMDATA` (both configurable via CLI args).