Metadata-Version: 2.4
Name: zpe-ink
Version: 0.1.1
Summary: ZPE Ink Wave-1 codec and falsification harness
Author-email: "Zer0pa (Pty) Ltd" <architects@zer0pa.ai>
License-Expression: LicenseRef-Zer0pa-SAL-7.0
Project-URL: Homepage, https://github.com/Zer0pa/ZPE-Ink
Project-URL: Documentation, https://github.com/Zer0pa/ZPE-Ink#readme
Project-URL: Repository, https://github.com/Zer0pa/ZPE-Ink
Project-URL: Issues, https://github.com/Zer0pa/ZPE-Ink/issues
Project-URL: Changelog, https://github.com/Zer0pa/ZPE-Ink/blob/main/CHANGELOG.md
Keywords: digital-ink,stroke-codec,pen-input,cross-runtime,wasm,pyo3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build<2,>=1.2.2; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Provides-Extra: telemetry
Requires-Dist: comet-ml<4,>=3.49; extra == "telemetry"
Dynamic: license-file

# ZPE-Ink

ZPE-Ink is an always-in-beta `.zpink` digital-ink codec — one of 17 independent encoding products in the Zer0pa portfolio. Every claim in this README is anchored to a committed proof artifact or CI test in this repository.

License: see `LICENSE`.

## What This Is

ZPE-Ink encodes and decodes deterministic `.zpink` stroke packets in Python, with 0.0 Hausdorff error on all measured datasets and bit-exact roundtrip fidelity backed by committed benchmark artifacts. The public proof surface covers:

- lossless encode/decode roundtrip for generated stroke fixtures
- CRC and truncated-payload rejection
- optional pressure, tilt, and azimuth channel handling
- static binding-contract consistency across the Python, PyO3, WASM, Swift, and C# surfaces

The committed public benchmark artifacts are in `proofs/` and their compression-ratio results are surfaced below. CI does not rerun those external corpora; the benchmark rows are static committed artifacts.

## Encoding Contract

| Claim | Proof artifact | CI test |
|---|---|---|
| `.zpink` lossless roundtrip is bit-exact for generated fixtures | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_lossless_roundtrip_bit_exact` |
| Corrupted or truncated payloads are rejected | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_crc_tamper_detection`, `code/tests/test_codec_roundtrip.py::test_reject_truncated_payload` |
| zero-valued optional channels can be omitted without changing decoded strokes | `proofs/logs/20260321_technical_alignment_pytest.txt` | `code/tests/test_codec_roundtrip.py::test_zero_optional_channels_are_omitted_by_default` |
| binding headers and package version are contract-consistent | `proofs/logs/20260321_technical_alignment_binding_contracts.json` | `code/tests/test_binding_contracts.py::test_repo_binding_contracts_pass` |
| CLI demo and roundtrip entry points execute | `proofs/logs/20260321_technical_alignment_wheel_install.txt` | `code/tests/test_cli.py` |

## Public Benchmark Results

These rows are committed static artifacts. The codec ran `encode → decode → verify` on each dataset using the repo-local lossless path. CI does not rerun these external corpora; results are bounded to the sample sizes shown.

| Dataset | Samples | Compression ratio | Max Hausdorff (px) | Roundtrip fidelity | Proof artifact |
|---|---:|---:|---:|---|---|
| UJI Pen Characters | 1,364 | **1.6111×** | 0.0 | exact | `proofs/reruns/phase3_public_benchmarks/phase3_public_benchmarks.json` |
| CROHME (ICFHR package) | 90 | **1.4360×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| DigiLeTs | 180 | **1.0891×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| MathWriting excerpt | 70 | **1.1870×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| QuickDraw (cat) | 256 | **1.0181×** | 0.0 | exact | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| IAM On-Line | — | — | — | skipped: registration-gated | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |
| UNIPEN | — | — | — | skipped: host unavailable | `proofs/artifacts/public_benchmarks/dataset_matrix.json` |

Baseline: raw little-endian float32 x/y pairs per point. Hausdorff = 0.0 on all measured datasets means decoded coordinates match the source integers exactly.

**Zero-channel suppression improvement (committed):** auto-suppressing zero tilt/azimuth streams raised CROHME mean compression from 1.52× to 1.76× (max 3.34×) and MathWriting mean from 1.06× to 1.15×. This change is captured in `proofs/artifacts/mathwriting_analysis/comparison.json` and exercised by `code/tests/test_codec_roundtrip.py::test_zero_optional_channels_are_omitted_by_default`.

Encode latency on the measured corpora: median 0.02–0.10 ms/stroke (single-core Python, macOS; QuickDraw low end 0.026 ms/stroke, MathWriting high end 0.099 ms/stroke). Source: `proofs/artifacts/public_benchmarks/dataset_matrix.json` (`median_ms_per_stroke` field).

These results do not constitute a hard-corpus pass, release-readiness claim, or competitive superiority claim. See `proofs/artifacts/public_benchmarks/README.md` for full methodology notes.

## Commercial Readiness

| Field | Value |
|---|---|
| Verdict | `STAGED` |
| Posture | No release-readiness or hard-corpus authority claim is made. Public benchmark rows are lossless-path results against raw float32 baseline only; no named external codec comparison is claimed. |
| Release validation | `proofs/release_validation/README.md` |

## What We Do Not Claim

- No claim of release readiness
- No claim of blind-clone closure
- No claim of hard-corpus pass
- No claim of general digital-ink dominance
- No claim that the public benchmark rows close release readiness or hard-corpus authority
- No claim that local binding-contract checks prove full runtime parity for every downstream environment
- No claim that committed compression ratios on the above datasets constitute superiority over general-purpose codecs on those corpora

## Quick Start

Development install:

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e './code[dev]'
python -m pytest code/tests -q
python -m zpe_ink demo
python -m zpe_ink verify-roundtrip
```

Package build:

```bash
python -m build
```

## Repository Links

| Field | Value |
|---|---|
| Repository | `https://github.com/Zer0pa/ZPE-Ink` |
| Issues | `https://github.com/Zer0pa/ZPE-Ink/issues` |
| License | SAL v7.0 — see `LICENSE` |
| Contact | `architects@zer0pa.ai` |
