Metadata-Version: 2.4
Name: zpe-neuro
Version: 0.1.1
Summary: Deterministic spike-event extraction codec for electrophysiology signals; Python; Gate C/D PASS on bounded DANDI 000034
Author-email: "Zer0pa (Pty) Ltd" <architects@zer0pa.ai>
License-Expression: LicenseRef-Zer0pa-SAL-7.0
Project-URL: Homepage, https://github.com/Zer0pa/ZPE-Neuro
Project-URL: Documentation, https://github.com/Zer0pa/ZPE-Neuro#readme
Project-URL: Repository, https://github.com/Zer0pa/ZPE-Neuro
Project-URL: Issues, https://github.com/Zer0pa/ZPE-Neuro/issues
Project-URL: Changelog, https://github.com/Zer0pa/ZPE-Neuro/blob/main/CHANGELOG.md
Keywords: neuroscience,extracellular recording,spike-event encoding,nwb,dandi,ibl
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Development Status :: 4 - Beta
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Provides-Extra: gate
Requires-Dist: pynwb>=2.8; extra == "gate"
Requires-Dist: scikit-learn>=1.6; extra == "gate"
Requires-Dist: spikeinterface>=0.103.2; extra == "gate"
Provides-Extra: public
Requires-Dist: dandi>=0.69; extra == "public"
Requires-Dist: h5py>=3.10; extra == "public"
Requires-Dist: pynwb>=2.8; extra == "public"
Requires-Dist: remfile>=0.1.13; extra == "public"
Requires-Dist: scikit-learn>=1.6; extra == "public"
Requires-Dist: spikeinterface>=0.103.2; extra == "public"
Provides-Extra: proof
Requires-Dist: dandi>=0.69; extra == "proof"
Requires-Dist: h5py>=3.10; extra == "proof"
Requires-Dist: pynwb>=2.8; extra == "proof"
Requires-Dist: remfile>=0.1.13; extra == "proof"
Requires-Dist: scikit-learn>=1.6; extra == "proof"
Requires-Dist: spikeinterface>=0.103.2; extra == "proof"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

<h1 align="center">ZPE-Neuro</h1>

<p align="center">
  <img src=".github/assets/readme/zpe-masthead.gif" alt="ZPE-Neuro Masthead" width="100%">
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-SAL%20v7.0-e5e7eb?labelColor=111111" alt="License: SAL v7.0"></a>
  <a href="proofs/manifests/CURRENT_AUTHORITY_PACKET.md"><img src="https://img.shields.io/badge/authority-2026--04--24%20repo%20snapshot-e5e7eb?labelColor=111111" alt="Authority: 2026-04-24 repo snapshot"></a>
  <a href="docs/RELEASE_STATUS.md"><img src="https://img.shields.io/badge/release-private%20staged-e5e7eb?labelColor=111111" alt="Release: private staged"></a>
  <a href="docs/LEGAL_BOUNDARIES.md"><img src="https://img.shields.io/badge/lane-extracellular%20recording-e5e7eb?labelColor=111111" alt="Lane: extracellular recording"></a>
</p>

## What This Is

ZPE-Neuro is the extracellular recording lane of the [Zer0pa](https://github.com/Zer0pa) 17-lane encoding portfolio — a bounded spike-event extraction codec for electrophysiology signals. It is independent of other portfolio lanes and speaks only for its own domain.

The strongest CI-anchored result to date: deterministic encode-decode round-trip on DANDI `000034` with a **401x event ratio**, **78.44 µV RMSE**, and Gate C + Gate D both `PASS` on blind-clone replay from the current `origin/main` snapshot. No comparison baseline exists for this lane; the numbers stand on their own terms.

This front door promotes only claims backed by a tracked proof artifact and exercised in CI. Treat [CURRENT_AUTHORITY_PACKET.md](proofs/manifests/CURRENT_AUTHORITY_PACKET.md) as the April 24 routing layer; the full proof archive goes deeper.

## Current Verified Surface

| Claim | Proof artifact | CI coverage |
|-------|----------------|-------------|
| DANDI `000034` remains the positive public anchor with `41` events, `401.04x` event ratio, and `78.44 uV` RMSE. | [`public_corpus_eval_dandi_000034_mouse412804_ecephys.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_eval_dandi_000034_mouse412804_ecephys.json) | `tests/test_dandi_offline.py` |
| Blind-clone replay from current repo truth closed with Gate C and Gate D both `PASS`. | [`verification_summary.md`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/verification_summary.md), [`gate_c_summary.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/gate_c_summary.json), [`gate_d_summary.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/gate_d_summary.json) | `Verify Package Surface / proof-import-smoke`, `gate-slice`, `tests/test_roundtrip.py`, `tests/test_wave1_determinism.py` |
| Breadth adjudication records IBL as the counted second extracellular target and does not count the Tier 1 DANDI anchor as breadth closure. | [`public_corpus_summary.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_summary.json), [`public_corpus_ibl_waveform_eval.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_ibl_waveform_eval.json) | `tests/test_breadth_adjudication.py` |
| DANDI `000003` was executed as the first next-family DANDI breadth probe and recorded `FAIL`. | [`public_corpus_eval_dandi_000003_yutamouse20_ecephys.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_eval_dandi_000003_yutamouse20_ecephys.json), [`dandi000003_decision.md`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/dandi000003_decision.md) | `tests/test_breadth_adjudication.py` |
| AJILE12 remains explicitly out of family and is excluded from counted breadth. | [`ajile12_family_boundary_decision.md`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/ajile12_family_boundary_decision.md), [`public_corpus_summary.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_summary.json) | `tests/test_breadth_adjudication.py` |

## Current Metrics

### DANDI `000034` Tier-1 Authority Anchor

| Metric | Value | Proof artifact | CI test |
|--------|-------|----------------|---------|
| Event ratio (window-scoped) | 401x | [`benchmark_summary.json`](proofs/artifacts/dandi000034_benchmark/benchmark_summary.json) | `tests/test_dandi_offline.py::test_fixture_reproduces_benchmark_metrics` |
| RMSE | 78.44 uV | [`benchmark_summary.json`](proofs/artifacts/dandi000034_benchmark/benchmark_summary.json) | `tests/test_dandi_offline.py::test_fixture_reproduces_benchmark_metrics` |
| Encode latency (mean / max) | 0.089 ms / 0.208 ms | [`benchmark_summary.json`](proofs/artifacts/dandi000034_benchmark/benchmark_summary.json) | artifact only — no pytest bound asserted |
| Decode latency (mean / max) | 0.474 ms / 0.686 ms | [`benchmark_summary.json`](proofs/artifacts/dandi000034_benchmark/benchmark_summary.json) | artifact only — no pytest bound asserted |

These are window-scoped metrics (6000-sample, 8-channel window at 30 kHz). They are not whole-recording compression results.

### IBL Second-Target (Tier-2 Breadth, Counted PASS)

| Metric | Value | Proof artifact | CI test |
|--------|-------|----------------|---------|
| Event ratio (window-scoped) | 224x | [`public_corpus_ibl_waveform_eval.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_ibl_waveform_eval.json) | artifact only — `tests/test_breadth_adjudication.py` tests logic, not this metric value |
| RMSE | 38.16 uV | [`public_corpus_ibl_waveform_eval.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_dandi000003_breadth/public_corpus_ibl_waveform_eval.json) | artifact only — `tests/test_breadth_adjudication.py` tests logic, not this metric value |

### Gate D: Embedded Latency and Drift Resilience

| Metric | Value | Proof artifact | CI test |
|--------|-------|----------------|---------|
| Modeled latency (mean / p99) | 612.5 ns / 850 ns | [`neuro_embedded_latency.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/neuro_embedded_latency.json) | CI `gate-slice` |
| Latency threshold | < 900 ns | [`neuro_embedded_latency.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/neuro_embedded_latency.json) | CI `gate-slice` |
| Drift accuracy at 0–15 µm | 100% | [`neuro_drift_resilience.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/neuro_drift_resilience.json) | CI `gate-slice` |
| Drift cliff | at 20 µm | [`neuro_drift_resilience.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/neuro_drift_resilience.json) | CI `gate-slice` |

Embedded latency uses a hardware-proxy cycle model at 80 MHz ARM-class clock plus Python reference timing. It is not a measured on-silicon result.

### Determinism

| Metric | Value | Proof artifact | CI test |
|--------|-------|----------------|---------|
| Identical-hash runs | 5 / 5 seeds | [`determinism_replay_results.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/determinism_replay_results.json) | `tests/test_wave1_determinism.py`, `tests/test_roundtrip.py` |
| NWB roundtrip SHA256 | bit-consistent | [`neuro_nwb_roundtrip.json`](proofs/selected_artifacts/2026-04-24_zpe_neuro_blind_clone_replay/neuro_nwb_roundtrip.json) | `tests/test_roundtrip.py` |

## What We Don't Claim

- No claim of lossless signal reconstruction.
- No claim that the window-scoped event-encoding ratios are whole-recording compression results.
- No claim that DANDI `000003` closed new breadth.
- No claim of commercialization-safe closure or tagged public release.
- No claim beyond the bounded extracellular lane.

## Repo Shape

| Field | Value |
|-------|-------|
| Proof Anchors | 5 |
| Modality Lanes | 1 |
| Authority Source | `proofs/manifests/CURRENT_AUTHORITY_PACKET.md` |

- `src/zpe_neuro/`: installable extractor package.
- `tests/`: repo-local verification slice.
- `tools/`: gate runners and operator scripts.
- `proofs/`: current authority packet plus April 24 replay and breadth packets.
- `docs/`: architecture, legal boundaries, release status, and dataset-scope notes.

## Quick Start

```bash
git clone https://github.com/Zer0pa/ZPE-Neuro.git
cd ZPE-Neuro
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
python -m pytest tests
```

For the bounded gate slice:

```bash
python -m pip install -e '.[gate,proof]'
python tools/run_gate_c.py --artifact-root artifacts/manual_gate_c --seed 20260220
python tools/run_gate_d.py --artifact-root artifacts/manual_gate_d --replay-seeds 20260220,20260221,20260222,20260223,20260224
```

Read [docs/LEGAL_BOUNDARIES.md](docs/LEGAL_BOUNDARIES.md) before widening any claim from this repo state.
