Metadata-Version: 2.4
Name: zpe-multimodal
Version: 3.0.2
Summary: ZPE Integrated Modality Codec with text/emoji/diagram/image/music/voice/mental/touch/smell+BPE
Author: Zer0paGlyph
License: LicenseRef-Zer0pa-SAL-6.2
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: chardet<6
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: native
Requires-Dist: zpe-imc-kernel>=0.1.0; extra == "native"
Requires-Dist: svgpathtools; extra == "native"
Provides-Extra: diagram
Requires-Dist: svgpathtools; extra == "diagram"
Provides-Extra: music
Requires-Dist: music21; extra == "music"
Provides-Extra: voice-optional
Requires-Dist: soundfile; extra == "voice-optional"
Requires-Dist: g2p-en; extra == "voice-optional"
Requires-Dist: nltk; extra == "voice-optional"
Provides-Extra: voice-audio-heavy
Requires-Dist: librosa; extra == "voice-audio-heavy"
Provides-Extra: hf
Requires-Dist: transformers>=4.38; extra == "hf"
Requires-Dist: huggingface-hub>=0.20; extra == "hf"
Provides-Extra: onnx
Requires-Dist: onnx>=1.16; extra == "onnx"
Requires-Dist: onnxruntime>=1.18; extra == "onnx"
Provides-Extra: wasm
Requires-Dist: wasmtime>=18; extra == "wasm"
Provides-Extra: triton
Requires-Dist: tritonclient[http]>=2.41; extra == "triton"
Requires-Dist: fastapi>=0.109; extra == "triton"
Requires-Dist: uvicorn>=0.27; extra == "triton"
Provides-Extra: bench
Requires-Dist: pytest-benchmark>=4.0; extra == "bench"
Requires-Dist: psutil>=5.9; extra == "bench"
Provides-Extra: full
Requires-Dist: svgpathtools; extra == "full"
Requires-Dist: music21; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

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

# ZPE-IMC

[![CI](https://github.com/zer0pa/zpe-imc/actions/workflows/imc-ci.yml/badge.svg)](https://github.com/zer0pa/zpe-imc/actions/workflows/imc-ci.yml)
[![PyPI](https://img.shields.io/pypi/v/zpe-multimodal)](https://pypi.org/project/zpe-multimodal/)
[![Python](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue)](https://github.com/zer0pa/zpe-imc)
[![License](https://img.shields.io/badge/license-SAL%20v6.2-e5e7eb?labelColor=111111)](https://github.com/zer0pa/zpe-imc/blob/main/LICENSE)

## What This Is

ZPE-IMC is a multimodal reference codec for the Zer0pa 20-bit word format. It packages 10 modality lanes behind one stream contract, but it does not import or orchestrate the standalone ZPE-* repos and should not be read as the family's production platform core.

Public package truth is now split cleanly. `pip install zpe-multimodal` closes the base Python package surface and the top-level text compatibility API. `pip install "zpe-multimodal[native]"` closes the public native-kernel install path by resolving `zpe-imc-kernel` from PyPI. The accepted runtime authority for IMC remains the March 7 Phase 6 native run-of-record; the older `wave1.0` / `total_words=844` demo remains frozen downstream compatibility history.

All current evidence is bounded to synthetic and reference inputs. No real-world production workload validation exists.

**Readiness: staged, synthetic/reference evidence only.** Public package surface available. Optional native extra available. Not the first buying surface.

**Not claimed:** production platform readiness, specialist-encoder parity, real-world workload validation, or that sibling ZPE-* repos literally run on IMC as runtime imports.

Part of the [Zer0pa](https://github.com/Zer0pa) family. Sibling codec repos: [ZPE-Bio](https://github.com/Zer0pa/ZPE-Bio), [ZPE-FT](https://github.com/Zer0pa/ZPE-FT), [ZPE-Geo](https://github.com/Zer0pa/ZPE-Geo), [ZPE-Ink](https://github.com/Zer0pa/ZPE-Ink), [ZPE-IoT](https://github.com/Zer0pa/ZPE-IoT), [ZPE-Mocap](https://github.com/Zer0pa/ZPE-Mocap), [ZPE-Neuro](https://github.com/Zer0pa/ZPE-Neuro), [ZPE-Prosody](https://github.com/Zer0pa/ZPE-Prosody), [ZPE-Robotics](https://github.com/Zer0pa/ZPE-Robotics), [ZPE-XR](https://github.com/Zer0pa/ZPE-XR).

| Field | Value |
| --- | --- |
| Architecture | MULTIMODAL_DISPATCH |
| Encoding | UNIFIED_20BIT_WORD |

## Key Metrics

| Metric | Value | Baseline |
| --- | --- | --- |
| MODALITIES | 10 | one 20-bit transport word |
| THROUGHPUT | 276,798.72 words/sec | Phase 6 native run |
| DETERMINISM | 11/11 | benchmark scenarios |
| RUNTIME_TESTS | 169/169 | run-of-record suite |

> Source: `proofs/logs/phase6_run_of_record_manifest.json`; `proofs/logs/phase6_determinism_probe.json`

## Competitive Benchmarks

IMC is the multimodal dispatch/reference repo, not the portfolio's comparator lane for compression sales claims. Competitive benchmark authority lives in the domain repos where the commercial wedges are actually sold: IoT, XR, Robotics, Geo, FT, Bio, Ink, Mocap, Neuro, and Prosody.

## What We Prove

- One public repo ships a shared 20-bit stream contract across 10 modality lanes
- The public base package imports cleanly and preserves the top-level text compatibility helpers
- The public native extra resolves to a real Rust kernel package (`zpe-imc-kernel`) rather than a local-only build step
- The March 7 Phase 6 runtime packet records a Rust-backed accepted path with deterministic benchmark facts and a native scan contract
- The historical `wave1.0` compatibility vector remains frozen for downstream replay and custody

## What We Don't Claim

- That IMC is the first buying surface for the portfolio
- That sibling ZPE-* repos import and run on IMC as a production platform core
- Production deployment readiness or real-world workload authority
- Universal compression wins across all modalities
- That the historical 844-word demo is the current native runtime authority

## Commercial Readiness

| Field | Value |
| --- | --- |
| Verdict | STAGED |
| Commit SHA | e316ddd7 |
| Confidence | Phase 6 native runtime packet plus retained multimodal benchmark packet |
| Source | `proofs/logs/phase6_run_of_record_manifest.json`; `proofs/logs/phase6_rust_backend_proof.json` |

## Tests and Verification

| Code | Check | Verdict |
| --- | --- | --- |
| V_01 | Base package import and top-level text roundtrip | PASS |
| V_02 | Public native extra install path (`zpe-multimodal[native]`) | PASS |
| V_03 | Phase 6 native run-of-record (`169/169`) | PASS |
| V_04 | Determinism probe (`11/11`) | PASS |
| V_05 | Multimodal benchmark packet | PASS |
| V_06 | Historical `wave1.0` compatibility vector (`844`) | PASS |

## Proof Anchors

| Path | State |
| --- | --- |
| `proofs/logs/phase6_run_of_record_manifest.json` | VERIFIED |
| `proofs/logs/phase6_rust_backend_proof.json` | VERIFIED |
| `proofs/logs/phase6_determinism_probe.json` | VERIFIED |
| `proofs/artifacts/modality_benchmarks.json` | VERIFIED |
| `docs/family/IMC_COMPATIBILITY_VECTOR.json` | VERIFIED |

## Repo Shape

| Field | Value |
| --- | --- |
| Proof Anchors | 5 verified |
| Modality Lanes | 10 |
| Authority Source | `proofs/logs/phase6_run_of_record_manifest.json` |

- `code/`: installable `zpe-multimodal` package, tests, and benchmarks
- `code/rust/imc_kernel/`: optional native kernel package for the public `native` extra
- `executable/`: repo-local demo and runtime harnesses
- `proofs/`: retained modality packet plus current Phase 6 runtime facts
- `docs/`: architecture, legal boundaries, and downstream contract files

## Quick Start

```bash
python -m pip install --upgrade pip
python -m pip install zpe-multimodal
python - <<'PY'
import zpe_multimodal as zm
ids = zm.encode("hello zpe")
print(zm.__version__)
print(zm.decode(ids))
PY

python -m pip install "zpe-multimodal[native]"
python - <<'PY'
from zpe_multimodal.core.imc import get_kernel_backend_info
print(get_kernel_backend_info())
PY
```

Expected native-backend facts:
- `backend='rust'`
- `compiled_extension=True`
- `fallback_used=False`

## Ecosystem

| Workstream | Route | Notes |
| --- | --- | --- |
| ZPE-Bio | [github.com/Zer0pa/ZPE-Bio](https://github.com/Zer0pa/ZPE-Bio) | Biology codec workstream |
| ZPE-FT | [github.com/Zer0pa/ZPE-FT](https://github.com/Zer0pa/ZPE-FT) | Finance codec workstream |
| ZPE-Geo | [github.com/Zer0pa/ZPE-Geo](https://github.com/Zer0pa/ZPE-Geo) | Geospatial codec workstream |
| ZPE-Ink | [github.com/Zer0pa/ZPE-Ink](https://github.com/Zer0pa/ZPE-Ink) | Handwriting codec workstream |
| ZPE-IoT | [github.com/Zer0pa/ZPE-IoT](https://github.com/Zer0pa/ZPE-IoT) | IoT telemetry codec workstream |
| ZPE-Mocap | [github.com/Zer0pa/ZPE-Mocap](https://github.com/Zer0pa/ZPE-Mocap) | Motion capture codec workstream |
| ZPE-Neuro | [github.com/Zer0pa/ZPE-Neuro](https://github.com/Zer0pa/ZPE-Neuro) | Neural signal codec workstream |
| ZPE-Prosody | [github.com/Zer0pa/ZPE-Prosody](https://github.com/Zer0pa/ZPE-Prosody) | Speech prosody codec workstream |
| ZPE-Robotics | [github.com/Zer0pa/ZPE-Robotics](https://github.com/Zer0pa/ZPE-Robotics) | Robotics codec workstream |
| ZPE-XR | [github.com/Zer0pa/ZPE-XR](https://github.com/Zer0pa/ZPE-XR) | XR spatial codec workstream |
| Package docs | [code/README.md](code/README.md) | Installable package surface |
| Architecture | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | Current repo/runtime truth |
| Legal boundaries | [docs/LEGAL_BOUNDARIES.md](docs/LEGAL_BOUNDARIES.md) | Scope and non-claims |

## Who This Is For

IMC matters when you need one deterministic transport contract for heterogeneous signals, or when you need a reference codec for cross-modality tooling. If you are evaluating a first commercial wedge, start with the domain repos.

## Historical Wave-1 Snapshot

The frozen `wave1.0` contract and `total_words=844` demo anchor remain part of the downstream compatibility story in `docs/family/IMC_COMPATIBILITY_VECTOR.json`. They are historical contract custody, not the current accepted runtime authority path.

## Open Risks (Non-Blocking)

- All current evidence is still synthetic/reference only
- The public native extra is only as broad as the published wheel matrix; no Windows claim is made here
- IMC is still not the first-sale surface; the domain repos remain the commercial entry points

## Contributing, Security, Support

- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
- Legal boundaries: [docs/LEGAL_BOUNDARIES.md](docs/LEGAL_BOUNDARIES.md)
- Package surface: [code/README.md](code/README.md)
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- License: [LICENSE](LICENSE)
