Metadata-Version: 2.4
Name: zpe-prosody
Version: 0.1.1
Summary: Deterministic contour codec, retrieval, and transfer evaluation surfaces for ZPE Prosody.
Author-email: "Zer0pa (Pty) Ltd" <architects@zer0pa.ai>
License-Expression: LicenseRef-Zer0pa-SAL-7.0
Project-URL: Homepage, https://github.com/Zer0pa/ZPE-Prosody
Project-URL: Documentation, https://github.com/Zer0pa/ZPE-Prosody#readme
Project-URL: Repository, https://github.com/Zer0pa/ZPE-Prosody
Project-URL: Issues, https://github.com/Zer0pa/ZPE-Prosody/issues
Project-URL: Changelog, https://github.com/Zer0pa/ZPE-Prosody/blob/main/CHANGELOG.md
Keywords: prosody,speech,f0-contours,deterministic-replay,retrieval-evaluation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: api
Requires-Dist: fastapi>=0.109; extra == "api"
Requires-Dist: uvicorn>=0.27; extra == "api"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# ZPE-Prosody

Deterministic prosody packet encoding for speech F0, energy, duration, and voiced-mask contour bundles. The `ZPRS/v1` codec compresses prosodic feature arrays to **13.0× on real LibriSpeech speech** with **0.64% voiced-F0 RMSE** and **2.67 ms mean encode latency** — byte-stable, round-trip lossless within CI thresholds, no GPU required.

ZPE-Prosody is one of seventeen independent encoding products in the Zer0pa portfolio; it targets speech-technology and voice-analytics teams that need deterministic, reproducible prosodic feature encoding.

Licensed under the [Zer0pa Source-Available License v7.0](LICENSE).

## Commercial Readiness

| Gate | Verdict | Notes |
|------|---------|-------|
| Core codec (PRO-C001 – PRO-C004) | PASS | Round-trip fidelity, determinism, extraction, and integration contract — all four pass. |
| Transfer closure (PRO-C005) | BLOCKED | Blocked on external dependency; a commercial-safe transfer substitute was not proven in-lane. |
| Posture (PRO-C005) | `PAUSED_EXTERNAL` | Specific posture: `PAUSED_EXTERNAL` — paused on external dependency, not generic-BLOCKED. |
| Retrieval closure (PRO-C006) | FAIL | p@5 = 0.31 vs threshold 0.80 on accepted evidence. |
| **Lane overall** | **FAIL** | Retrieval and transfer gates are not resolved. Codec primitives are sound. |

No lane pass is claimed. No public release tag has been issued. The codec is useful as a deterministic encoding primitive; end-to-end commercial deployment requires resolving the gates above.

## CI-Anchored Claims

| Claim | Proof Artifact | CI Test |
|-------|----------------|---------|
| `ZPRS/v1` packets encode and decode contour bundles without changing frame shape or voiced-mask length. | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/gate_b_roundtrip.json` | `tests/test_packet_format.py::PacketFormatTests::test_encode_decode_shape` |
| Malformed packet magic is rejected through a structured decode error. | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/gate_d_falsification_summary.json` | `tests/test_packet_format.py::PacketFormatTests::test_bad_magic_raises` |
| Round-trip F0 and energy reconstruction stay below the current CI thresholds on generated contour fixtures. | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_f0_fidelity.json`, `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_energy_fidelity.json` | `tests/test_roundtrip.py::RoundTripTests::test_roundtrip_fidelity` |
| Encoding the same contour bundle with the same metadata is byte-stable. | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/determinism_replay_results.json` | `tests/test_roundtrip.py::RoundTripTests::test_deterministic_bytes` |
| The in-process API contract supports encode, decode, transfer, and advertised endpoint capability checks. | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/integration_readiness_contract.json` | `tests/test_api_contract.py` |

## Measured Performance (Proof-Artifact Records)

These metrics come from committed proof-artifact runs, not reasserted per CI push. Each number is anchored to a specific artifact file; the artifact commit is the evidence. CI thresholds are broader than these measured values by design — the proof runs set the floor, CI guards against regression.

**Compression** (baseline: raw float32 arrays for F0, energy, duration, voiced\_mask)

| Dataset | Samples | Mean ratio | p50 ratio | p95 ratio | CI threshold | Artifact |
|---------|---------|-----------|-----------|-----------|--------------|----------|
| LibriSpeech `test-clean` (real speech, OpenSLR) | 100 utterances | **13.0×** | 13.0× | 16.6× | — | `proofs/artifacts/librispeech_benchmark/compression_benchmark.json` |
| Librispeech-like fixtures | 140 | **16.6×** | 16.6× | 20.0× | ≥15× | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_compression_benchmark.json` |

**Fidelity** (round-trip encode → decode)

| Metric | Dataset | Samples | Mean | p95 | CI threshold | Artifact |
|--------|---------|---------|------|-----|--------------|----------|
| Voiced-F0 RMSE | LibriSpeech `test-clean` (real) | 100 | **0.64%** | 1.21% | — | `proofs/artifacts/librispeech_benchmark/f0_fidelity.json` |
| Voiced-F0 RMSE | CMU Arctic-like fixtures | 80 | **0.89%** | 1.01% | 5.0% | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_f0_fidelity.json` |
| Energy RMSE | CMU Arctic-like fixtures | 80 | **2.08%** | 2.18% | 3.0% | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_energy_fidelity.json` |
| Duration (timing) RMSE | LibriSpeech `test-clean` (real) | 100 | **0.000 ms** | 0.000 ms | — | `proofs/artifacts/librispeech_benchmark/timing_fidelity.json` |

**Encode latency** (single-threaded, no GPU)

| Dataset | Samples | Mean | p95 | Artifact |
|---------|---------|------|-----|----------|
| LibriSpeech `test-clean` (real) | 100 | **2.67 ms** | 5.18 ms | `proofs/artifacts/librispeech_benchmark/latency_benchmark.json` |
| Librispeech-like fixtures | 140 | **2.59 ms** | 4.14 ms | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_latency_benchmark.json` |

**Robustness** (malformed-packet falsification campaign)

| Test | Result | Artifact |
|------|--------|----------|
| Malformed packet cases | 4/4 decode errors caught, 0.0 uncaught crash rate | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/gate_d_falsification_summary.json` |
| Determinism replay | 5/5 hash-identical runs | `proofs/artifacts/2026-02-20_zpe_prosody_wave1/determinism_replay_results.json` |

## Non-Promoted Historical Artifacts

The following proof artifacts remain in the repository for audit lineage, but their exact claims are not promoted in this README:

- `proofs/artifacts/2026-02-20_zpe_prosody_wave1/before_after_metrics.json`
- `proofs/artifacts/2026-02-20_zpe_prosody_wave1/prosody_retrieval_eval.json` (PRO-C006: FAIL — p@5=0.31 vs threshold 0.80)
- `proofs/artifacts/2026-02-20_zpe_prosody_wave1/quality_gate_scorecard.json` (overall gate FAIL; PRO-C005 `PAUSED_EXTERNAL` (blocked on external dependency), PRO-C006 FAIL)
- `proofs/artifacts/c006_retrieval_failure_analysis.md`
- `proofs/artifacts/c005_replacement_analysis.md`

## What Is Not Claimed

- No lane pass.
- No retrieval closure above threshold.
- No commercialization-safe transfer closure.
- No public release-readiness claim.
- No speech-codec comparator leadership vs production systems.
- No MOS claim — transfer evaluation was not executed end to end with a commercially safe transfer stack.

## Repo Shape

- `src/zpe_prosody/`: installable codec package.
- `tests/`: CI-backed package, packet, API, and round-trip checks.
- `scripts/verify_release_surface.py`: package surface sanity helper used by `make package-sanity`.
- `proofs/`: historical adjudication artifacts and audit lineage.
- `docs/`: architecture, legal-boundary, market-surface, and family notes.

## Quick Start

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"
make repo-sanity
make package-sanity
make test
```

Optional API wrapper dependency:

```bash
python -m pip install ".[api]"
```

The base wheel ships only `src/zpe_prosody`. No CLI or historical gate harness is packaged as a runtime contract. Read [docs/LEGAL_BOUNDARIES.md](docs/LEGAL_BOUNDARIES.md) before widening any claim from this repo state.
