README.md

---
license: cc-by-nc-sa-4.0
pipeline_tag: audio-classification
tags:
  - audio-classification
  - bioacoustics
  - perch
  - chickens
  - poultry
  - edge-ai
  - research
  - non-commercial
---

# ChickenNet Research 0.2.0 — Perch 2

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

This repository contains only the ChickenNet model family. It shares the frozen Perch 2 feature contract with other field heads and does not use BirdNET logits.

> **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 `chickennet-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: chickennet-research-0.2.0-perch2
Runtime slug:   chickennet-dev2-field-probe
Bundle ID:      d81cd5aee82176065f79abe4ae19db69f5c52c0ca4818d43fd981bf7781dcc41
Source artifact SHA-256: d1595cc65a484ea963172dcc3c8d4b20e0fb6fbc0771883b40105b77668d6686
Logical dataset hash:    eae3953337fa2014596d5e95f0c63387421366196fed38888a5723da01f33935
Manifest JSONL SHA-256:  afe315fcb4f6f8a096ea45a0cc20c6b86256b868b7f5e5589257aec8a228d1d5
```

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 ChickenNet | one 1,536-dimensional Perch 2 embedding |
| Output | uncalibrated ranking score for `chicken_vocalization_present` |
| Research evaluation threshold | `0.47` |
| Deployed review-routing threshold | `0.9999` |
| 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 | 2,000 | 80 | 1,920 | 0 | 2,000 | 1,524 | `research_noncommercial`: 2000 |
| laying-hen-control-first | 96 | 96 | 0 | 0 | 32 | 4 | `core_releasable`: 96 |
| poultry-health-first | 79 | 54 | 0 | 25 | 30 | 30 | `core_releasable`: 79 |
| ross308 | 317 | 258 | 59 | 0 | 26 | 14 | `core_releasable`: 317 |
| smartears-full | 3,000 | 2,000 | 1,000 | 0 | 3,000 | 65 | `core_releasable`: 3000 |

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 iNaturalist weak-positive challenge | 31 / 42 broad-head activations at research threshold `0.47` |
| Locked dog negative challenge | 9 / 26 activations at research threshold `0.47` |
| Generic private frog-domain diagnostic | 23 / 1,308 activations at research threshold `0.47`; this lane is not a reviewed chicken-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.9999`:

| Lane | Activations |
|---|---:|
| iNaturalist weak-positive challenge | 9 / 42 |
| Dog negative challenge | 1 / 26 |
| Generic private frog-domain diagnostic | 1 / 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 individual birds, call meaning, behavior, welfare, health, sex, or age.
- The iNaturalist challenge is taxon-associated weak-positive evidence, not exact-span ground truth for every window.
- The strict field threshold intentionally sacrifices recall to bound review burden.
- No formal prevalence-adjusted field precision or recall estimate exists.
- 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/chickennet](https://github.com/vortexpjeff/chickennet)
- Tagged release tree: [chickennet-research-0.2.0-perch2](https://github.com/vortexpjeff/chickennet/tree/chickennet-research-0.2.0-perch2)
- Older public research ancestor: [TheVortexProject/chickennet-research-0.1.0-perch2](https://huggingface.co/TheVortexProject/chickennet-research-0.1.0-perch2)
## Load the checked deployed bundle

```python
from pathlib import Path
from chickennet.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.