README.md

---
license: cc-by-nc-sa-4.0
pipeline_tag: audio-classification
tags:
  - audio-classification
  - bioacoustics
  - perch
  - insects
  - orthoptera
  - cicadas
  - edge-ai
  - research
  - non-commercial
---

# InsectNet Research 0.3.0

A provenance-locked binary `insect_present` specialist head over frozen 1,536-dimensional Google Perch 2 embeddings.

This repository contains only the InsectNet model family. The preserved BirdNET-logit InsectNet v0.1 model is a distinct project at [vortexpjeff/insectnet-legacy](https://github.com/vortexpjeff/insectnet-legacy) and is not an ancestor bundle, embedding source, or runtime dependency of this model.

> **Status: public noncommercial research artifact; these exact checked JSON/NPZ bytes are privately deployed as a review-only field head.** A threshold crossing selects audio for human review. It is not a calibrated probability or a confirmed biological observation.

This repository publishes the exact safe runtime bundle currently used by the `insectnet-dev2-field-probe` field head, plus sanitized aggregate provenance and challenge summaries. It contains no source audio, exact training manifest, coordinates, private observation locations, uploader identities, credentials, private paths, or arbitrary Python serialization.

## Release identity

```text
Public release: insectnet-research-0.3.0-perch2
Runtime slug:   insectnet-dev2-field-probe
Bundle ID:      ff8d28f5e8d0416eb63e7b958b6b950b69dd89a0baca0089f399b20cbc3c529f
Source artifact SHA-256: 9cd5f753db357220a180ead0d13019d46f69d469898b9a88bfdb12ca38fecf14
Logical dataset hash:    825c40602fe65611c3bef36c4fc8f7b120913b62a56728b355ccf8f775e178a5
Manifest JSONL SHA-256:  0904e001b988d03a66c402aee884f7f6a9404240bc7f33c28fc38e2822c650ee
```

The source joblib and exact row-level manifest remain in private scientific custody. The public JSON/NPZ bundle contains only the broad deployed head. `release/training-summary.json` publishes aggregate row, group, rights, split, and label-authority counts plus the exact private-manifest hash.

## Inference contract

| Field | Value |
|---|---|
| Input audio to Perch | 5 seconds, 32 kHz, mono |
| Input to InsectNet | one 1,536-dimensional Perch 2 embedding |
| Output | uncalibrated ranking score for `insect_present` |
| Research evaluation threshold | `0.85` |
| Deployed review-routing threshold | `0.9995` |
| Serialization | checked JSON metadata plus NPZ numeric arrays |
| Perch model-tree SHA-256 | `3fb2d54b3e34534f1130052b25737e54bbb5ebfd340ec040d4510772b64c81ff` |

The Perch weights are not included. This specialist head cannot score raw waveforms by itself.

## Training sources

| Source lane | Rows | Positive | Declared negative | Unknown | Recordings | Groups | Rights lane |
|---|---:|---:|---:|---:|---:|---:|---|
| esc50 | 1,960 | 0 | 1,960 | 0 | 1,960 | 1,498 | `research_noncommercial`: 1960 |
| inat-cat-negatives | 26 | 0 | 26 | 0 | 26 | 26 | `core_releasable`: 26 |
| inat-chicken-negatives | 42 | 0 | 42 | 0 | 42 | 30 | `core_releasable`: 42 |
| insectset459 | 2,096 | 2,096 | 0 | 0 | 2,096 | 334 | `core_releasable`: 2096 |
| oxfordshire-full-train | 1,656 | 1,033 | 623 | 0 | 552 | 76 | `core_releasable`: 1656 |
| ross308-negatives | 317 | 0 | 317 | 0 | 26 | 14 | `core_releasable`: 317 |

All source groups and parent recordings remain within one train/validation/test partition. The exact retained training-window audit found no missing or mismatched source windows. Weak and context-derived labels retain their recorded authority; they are not promoted to ecological truth.

## Research-threshold evidence

| Lane | Result |
|---|---|
| Locked Oxfordshire cross-site windows | 591 windows; broad-head AP 0.9788, precision 0.9914, recall 0.7152 at research threshold `0.85` |
| Locked dog negative challenge | 6 / 26 activations at research threshold `0.85` |
| Generic private frog-domain diagnostic | 1,012 / 1,308 activations at research threshold `0.85`; this lane may contain insects and is not an insect-absence set |

These results were produced by the multi-head source artifact at its research threshold. They do not describe the much stricter deployed event policy.

## Deployed-threshold replay

The retained challenge embeddings were replayed through the exact deployed broad-head bundle at `0.9995`:

| Lane | Activations |
|---|---:|
| Locked Oxfordshire cross-site windows | 204 / 591 |
| Dog negative challenge | 1 / 26 |
| Generic private frog-domain diagnostic | 3 / 1308 |

This replay is descriptive. The operational threshold was selected after these challenge sets had already been examined, so this is not an untouched threshold-selection experiment or a field accuracy estimate.

## Operational relationship

The private field listener computes one Perch embedding per five-second window and scores InsectNet, ChickenNet, and FrogNet independently. BirdNET remains a separate evidence lane. Model assertions, exact spans, thresholds, and later human decisions are preserved separately.

The raw field archive, review ledger, sensor configuration, and operational repository are intentionally not published.

## Verify the package

```bash
sha256sum --check SHA256SUMS
cd bundle && sha256sum --check SHA256SUMS
```

Load `bundle/weights.npz` only with `allow_pickle=False`. The package does not require joblib or pickle.

## Included files

- `bundle/model.json` — exact deployed model metadata and inference contract
- `bundle/weights.npz` — exact deployed numeric arrays
- `bundle/SHA256SUMS` — deployed bundle-member checksums
- `release/release-manifest.json` — identity, rights, and custody boundary
- `release/training-summary.json` — sanitized aggregate training membership and split audit
- `release/challenge-summary.json` — frozen research-threshold challenge summaries
- `release/deployed-threshold-replay.json` — clearly labeled post-selection operational replay
- `SHA256SUMS` — complete public payload inventory

## Known limits

- The broad head does not identify insect species, abundance, individuals, or behavior.
- The Oxfordshire challenge is dominated by annotated insect-positive windows and is not a prevalence-weighted field test.
- Frog-domain audio can contain simultaneous insects; activation on that lane is not automatically a false positive.
- The strict field threshold intentionally sacrifices recall to bound review burden.
- The trainer run recorded a dirty Git worktree. Exact model bytes, data membership, manifests, embeddings, and retained windows survive, but the named clean commit alone does not reconstruct the historical trainer source state.
- Some source families encode DOI/license/member identity at row level rather than through one standardized source sidecar.
- The field bundle's historical key `training_manifest_hash` contains the canonical logical dataset hash. The separate JSONL byte hash is published in the release manifest and training summary.

## Rights and provenance

The training matrix includes public permissive and noncommercial research lanes. Because ESC-50-derived material contributed to fitting, this artifact is distributed under CC BY-NC-SA 4.0 for noncommercial research and field evaluation, subject to all upstream terms. No upstream audio is redistributed and this release grants no rights to source recordings or Perch weights.

## Source

- Source registry and tests: [https://github.com/vortexpjeff/insectnet](https://github.com/vortexpjeff/insectnet)
- Tagged release tree: [insectnet-research-0.3.0-perch2](https://github.com/vortexpjeff/insectnet/tree/insectnet-research-0.3.0-perch2)
- Older public research ancestor: [TheVortexProject/insectnet-research-0.2.0-perch2](https://huggingface.co/TheVortexProject/insectnet-research-0.2.0-perch2)
## Load the checked deployed bundle

```python
from pathlib import Path
from insectnet_perch2.bundle import load_bundle, score_embedding

bundle = load_bundle(Path('bundle'))
raw_score, review_score = score_embedding(bundle, perch2_embedding)
```

The input is one finite 1,536-dimensional Perch 2 embedding. Do not feed BirdNET logits or waveforms directly into this head.