Metadata-Version: 2.1
Name: verda-ecc
Version: 0.1.0
Summary: Bit-level Reed-Solomon / BCH / CRC error-correcting codes (IT++ wrapper) with bit-vector I/O
Author: Verda AI
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/VerdaAI/verda-ecc
Requires-Python: >=3.8
Requires-Dist: numpy>=1.20
Description-Content-Type: text/markdown

# verda-ecc

Bit-level **Reed-Solomon / BCH / CRC** error-correcting codes with native
bit-vector (`bvec`) I/O, wrapping [IT++](https://itpp.sourceforge.net/) via
pybind11. Built as a self-contained wheel (IT++ + OpenBLAS statically linked) —
no system `libitpp`, no `patchelf`, no per-Python `.so` checked into git.

## Why not a byte-oriented ECC library?

The Verda watermark encodes/decodes on **non-byte-aligned** codeword lengths
(e.g. 31- and 127-bit BCH) and needs **bit-error** correction, not byte-symbol
correction. Mainstream libraries operate on byte symbols: `reedsolo` is
GF(2^8), `bchlib` takes bytearrays, `crcmod` produces byte CRCs. IT++ provides
true bit-vector coding, so we wrap the known-good IT++ implementation rather
than reimplement.

## API

```python
from verda_ecc import ECCHandler

ecc = ECCHandler()
cw  = ecc.bch_encode(bits, n=127, t=6)      # numpy int32 bit-array in/out
msg = ecc.bch_decode(cw, n=127, t=6)
cw  = ecc.rs_encode(bits, m=5, t=7)
crc = ecc.crc_encode(bits, crc_len=16)
```

Composites: `encode_with_crc_and_{bch,rs}` / `decode_with_{bch,rs}_and_crc`.

## Bit-identical guarantee

`tests/golden.json` freezes the deployed IT++ build's exact output for every
parameter set. `tests/test_golden.py` asserts a fresh build reproduces it
**byte-for-byte** (encode + decode round-trips). The wheel does not ship unless
this passes — the acceptance gate against silent build drift.

## License

GPL-3.0-or-later (inherited from IT++). Pure coding theory; no Verda IP.
