Publish sanitized InsectNet v0.1.0 archival release

.gitattributes

@@ -1,35 +1 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
 *.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

PROVENANCE.md

@@ -0,0 +1,47 @@
+# Data and model provenance
+
+## Preserved claim
+
+This repository preserves one v0.1 classifier artifact with an independently verified SHA-256. The artifact consumes 6,522-dimensional output logits from the declared BirdNET v2.4 FP16 TFLite backbone.
+
+The exact original per-record training snapshot no longer survives. Therefore this release does not claim to be independently reproducible from raw source media.
+
+## Surviving source-family record
+
+| Source family | Surviving license information | Release treatment |
+|---|---|---|
+| InsectSet459 | Dataset card states CC BY 4.0; source material may also be CC0 | Named as a source family; media not redistributed |
+| ESC-50 | CC BY-NC 3.0 | Named as a source family; media not redistributed |
+| iNaturalist audio | License varies by individual recording | No blanket license asserted; media not redistributed |
+| Private field negatives | Private research evidence | Not redistributed and location omitted |
+| BirdNET backbone | Separate upstream model terms apply | Backbone is not redistributed here |
+
+## Missing evidence
+
+The following v0.1 records are unavailable:
+
+- exact source-file list and per-record licenses;
+- exact normalized window manifest;
+- grouped train/evaluation split;
+- threshold-selection report;
+- complete field-review ledger linked to this exact artifact;
+- original environment lockfile.
+
+These gaps are recorded rather than reconstructed from later experimental branches.
+
+## Release rule
+
+A future model version must include:
+
+1. artifact SHA-256 and byte size;
+2. feature extractor identity and checksum;
+3. ordered classes and independent thresholds;
+4. source/window manifest digest;
+5. per-record source and license provenance;
+6. grouped split policy and seed;
+7. scoped metrics and known false positives;
+8. code commit and runtime source checksum;
+9. deployment target and rollback artifact;
+10. privacy-reviewed public documentation.
+
+Model outputs remain assertions for review. They do not become confirmed observations without human validation.

README.md

@@ -0,0 +1,134 @@
+---
+license: cc-by-nc-sa-4.0
+library_name: sklearn
+tags:
+  - bioacoustics
+  - audio-classification
+  - birdnet
+  - edge-ai
+  - research
+  - non-commercial
+datasets:
+  - academic-datasets/InsectSet459
+  - ESC-50
+---
+
+# InsectNet v0.1.0
+
+InsectNet v0.1.0 is a preserved research classifier for scoring insect- and amphibian-related acoustic classes from frozen BirdNET v2.4 output logits.
+
+This Hugging Face repository is the model-release mirror. The canonical source, tests, package, and GitHub Release are at [github.com/vortexpjeff/insectnet](https://github.com/vortexpjeff/insectnet).
+
+This repository intentionally contains one model artifact and one release identity. It does **not** publish live sensor addresses, deployment credentials, exact collection locations, private media, or an unattended capture service.
+
+## Release identity
+
+```text
+Release:  insectnet-v0.1.0
+Artifact: classifier.joblib
+SHA-256: 5e6ecfc68d78a2cf2e9e9e47da5cb58d696e8de354fd620cfcccc5db9da48702
+Bytes:    474,892
+Status:   historical research reference
+```
+
+The artifact is byte-for-byte preserved from the original v0.1 field prototype.
+
+## Model contract
+
+```text
+Audio window:       3.0 seconds
+Sample rate:        48,000 Hz mono
+Backbone:           BirdNET v2.4 FP16 TFLite
+Feature space:      6,522 BirdNET output logits
+Classifier:         StandardScaler → OneVsRest LogisticRegression
+Serialization:      scikit-learn 1.8.0
+Output semantics:   independent per-class probabilities
+```
+
+Class order:
+
+1. `background`
+2. `bee`
+3. `cicada_drone`
+4. `cricket_katydid`
+5. `frog`
+6. `grasshopper`
+
+The model file does not embed thresholds, a version number, or its original training snapshot. Those omissions are part of the preserved v0.1 record rather than silently reconstructed metadata.
+
+## What is included
+
+- the exact v0.1 model artifact;
+- a machine-readable release manifest;
+- artifact and feature-contract verification;
+- offline scoring for precomputed BirdNET logit vectors;
+- tests that enforce the model checksum, class order, feature dimension, and public privacy boundary;
+- documented provenance and limitations.
+
+## What is not included
+
+- live capture or sensor-watching code;
+- deployment scripts;
+- device addresses or credentials;
+- exact collection locations;
+- raw or private field audio;
+- later experimental model candidates;
+- claims of production readiness.
+
+The original live sidecar diverged from the public v0.1 source during field experiments. That runtime is not republished here until it can be recovered, tested, and released under a separate reviewed version.
+
+## Verify the preserved artifact
+
+From a source checkout:
+
+```bash
+uv run insectnet verify
+```
+
+Expected SHA-256:
+
+```text
+5e6ecfc68d78a2cf2e9e9e47da5cb58d696e8de354fd620cfcccc5db9da48702
+```
+
+## Score precomputed logits
+
+InsectNet v0.1 expects one finite NumPy vector with shape `(6522,)` extracted from the declared BirdNET backbone:
+
+```bash
+uv run insectnet score logits.npy
+```
+
+The command returns one probability per declared class. These scores are model assertions for review, not confirmed biological observations.
+
+> **Joblib safety:** joblib artifacts use Python pickle internally. Load only the artifact whose checksum matches the release manifest.
+
+## Known limitations
+
+- Later audits found high false-positive rates on some bird vocalizations.
+- Bee and grasshopper had limited training coverage.
+- The surviving metrics came from limited public-data evaluation and one private field site; they do not establish general production performance.
+- Exact reproduction is blocked because the original per-record training snapshot is unavailable.
+- The classifier relies on BirdNET logits and cannot score raw audio by itself.
+- There is no validated automated-decision threshold policy in this release.
+
+## Provenance
+
+The surviving records identify these source families:
+
+- **InsectSet459:** current dataset card states CC BY 4.0, with some source material CC0.
+- **ESC-50:** CC BY-NC 3.0.
+- **iNaturalist audio:** licenses vary per recording; the original per-record manifest is unavailable.
+- **Private field negatives:** not redistributed.
+
+See [`PROVENANCE.md`](PROVENANCE.md) and the release manifest for the exact surviving claims and gaps.
+
+## Privacy and security
+
+The public release intentionally omits exact collection location, network topology, account names, credentials, private paths, and raw evidence. See [`SECURITY_AND_PRIVACY.md`](SECURITY_AND_PRIVACY.md).
+
+## License
+
+The repository and preserved release are distributed under CC BY-NC-SA 4.0, subject to the licenses and terms of the upstream backbone and source media. Source-media rights vary; users are responsible for reviewing those upstream terms for their use case.
+
+This provenance statement is not legal advice.

SECURITY_AND_PRIVACY.md

@@ -0,0 +1,50 @@
+# Security and privacy boundary
+
+## Public release boundary
+
+This repository must not contain:
+
+- exact collection coordinates or street addresses;
+- private site names or fine-grained regional identifiers;
+- device network addresses or topology;
+- account names, passwords, API keys, tokens, or credential helpers;
+- private workstation or device paths;
+- raw private audio;
+- source filenames that reveal private deployment details;
+- unattended deployment commands without a separately reviewed operations plan.
+
+The test suite scans public text files for known historical location and access strings.
+
+## Artifact safety
+
+The model is serialized with joblib, which relies on Python pickle. A malicious artifact can execute code when loaded. Verify the model SHA-256 against the packaged `v0.1.0.manifest.json` before loading it. The verifier stops before deserialization if byte size or SHA-256 differs.
+
+The release verifier checks:
+
+- repository-relative artifact path;
+- exact SHA-256;
+- exact byte size;
+- required joblib keys;
+- ordered classes;
+- 6,522-feature contract;
+- classifier estimator count.
+
+## Operational boundary
+
+This v0.1 release does not provide live capture or deployment automation. Any future edge deployment must be released separately with:
+
+- no embedded credentials;
+- explicit destination supplied by the operator;
+- immutable backup before replacement;
+- checksum and model-load preflight;
+- source syntax checks;
+- single-instance control;
+- bounded resource use;
+- disk guard and retention policy;
+- rollback procedure;
+- post-change health verification;
+- no changes to the upstream monitoring system without separate approval.
+
+## Reporting
+
+Public performance reports must generalize location and describe the evaluation set, review authority, thresholds, and limitations. Confidence values alone are not validation.

classifier.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5e6ecfc68d78a2cf2e9e9e47da5cb58d696e8de354fd620cfcccc5db9da48702
+size 474892

requirements.txt

@@ -0,0 +1,3 @@
+joblib>=1.3
+numpy>=1.24
+scikit-learn==1.8.0

v0.1.0.manifest.json

@@ -0,0 +1,64 @@
+{
+  "artifact": {
+    "bytes": 474892,
+    "format": "joblib",
+    "path": "classifier.joblib",
+    "sha256": "5e6ecfc68d78a2cf2e9e9e47da5cb58d696e8de354fd620cfcccc5db9da48702"
+  },
+  "known_limitations": [
+    "The artifact does not embed its own version, thresholds, backbone hash, or training manifest.",
+    "Later audits found a high false-positive rate on some bird vocalizations.",
+    "Bee and grasshopper classes were data-limited in the surviving evaluation notes.",
+    "Published metrics came from limited public-data evaluation and one private field site; they are not evidence of general production performance.",
+    "Outputs are model assertions for human review, not confirmed biological observations."
+  ],
+  "model_contract": {
+    "backbone": {
+      "artifact": "BirdNET_GLOBAL_6K_V2.4_Model_FP16.tflite",
+      "sha256": "5c64ba3ffab264ccbfafe784896392051a86be63b0cc507e7683db7df114546b"
+    },
+    "classes": [
+      "background",
+      "bee",
+      "cicada_drone",
+      "cricket_katydid",
+      "frog",
+      "grasshopper"
+    ],
+    "feature_dimension": 6522,
+    "feature_space": "birdnet_v2.4_logits",
+    "output_semantics": "independent one-vs-rest probabilities",
+    "sample_rate_hz": 48000,
+    "serialization_runtime": {
+      "scikit_learn": "1.8.0"
+    },
+    "window_seconds": 3.0
+  },
+  "provenance": {
+    "code_license": "CC-BY-NC-SA-4.0",
+    "field_site": "one private field site; location intentionally omitted",
+    "source_families": [
+      {
+        "license": "CC-BY-4.0 or CC0 according to source metadata",
+        "name": "InsectSet459"
+      },
+      {
+        "license": "CC-BY-NC-3.0",
+        "name": "ESC-50"
+      },
+      {
+        "license": "varies by individual recording; original per-record manifest unavailable",
+        "name": "iNaturalist audio"
+      },
+      {
+        "license": "private research evidence; not redistributed",
+        "name": "private field negatives"
+      }
+    ],
+    "training_snapshot": "unavailable",
+    "warning": "The missing per-record training snapshot prevents a complete independent rebuild of this exact artifact."
+  },
+  "release_id": "insectnet-v0.1.0",
+  "schema_version": 1,
+  "status": "historical_research_reference"
+}