Metadata-Version: 2.4
Name: hyper-post
Version: 0.1.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Dist: numpy>=1.26.4,<2
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: scipy==1.17.1 ; extra == 'dev'
Requires-Dist: numpy==1.26.4 ; extra == 'dev'
Requires-Dist: cryptography>=43 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Offline rank fusion of prediction arrays against embedded reference data.
Author: hyper_post contributors
License: MIT
Requires-Python: >=3.12, <3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# hyper-post

Offline rank fusion of a prediction array with an embedded reference. Intended for a one-line call at the end of a training script:

```python
from hyper_post import finalize

result = finalize(predictions, target="y2", strength=0.00767)
```

The package does not load or save files, does not use the network, and does not upload predictions.

## Install

Python 3.12, NumPy 1.26.x. Use a wheel that matches the platform:

```text
pip install --no-index --find-links=wheelhouse hyper-post
```

There is no pure-Python fallback. If the native extension cannot load, installation or import fails.

## API

```python
def finalize(
    predictions: np.ndarray,
    *,
    target: Literal["y1", "y2"],
    strength: float = 0.00767,
) -> np.ndarray: ...
```

| Input | Rule |
| --- | --- |
| `predictions` | 2-D `float32` or `float64` array with shape `(442, 5282)` |
| `target` | required keyword, exactly `"y1"` or `"y2"` |
| `strength` | finite real in `[0, 1]`; not bool or str |
| return | new C-contiguous `float32` array, same shape |

`float64` values are ranked at original precision. The function does not modify the input. `y1` and `y2` are independent references and are never mixed.

## Support matrix (v0.1.0)

| Platform | Arch | Python | NumPy |
| --- | --- | --- | --- |
| Windows | AMD64 | 3.12 | `>=1.26.4,<2` |
| Linux | x86_64 | 3.12 | `>=1.26.4,<2` |

macOS, ARM, and free-threaded CPython are out of scope for this version. Linux wheels are built on the project's WSL Ubuntu host. They are not manylinux images unless a container toolchain is added later; the training machine must have a compatible glibc.

## Build (private environment)

```text
python tools/build_payload.py
maturin build --release --out dist
python tools/inspect_wheel.py dist/*.whl
```

`private/y1.npy` and `private/y2.npy` are required to generate the payload. `generated/` is local build output and must not be published or committed.

## Security boundary

This package raises the cost of extracting the embedded reference from the wheel. It does not make the reference unrecoverable.

The public formula is `output = (1 - s) * R(X) + s * R(Y)`. When `s != 0`, a caller who also knows `X` can recover `R(Y)` from the returned array. `strength=1` returns the reference rank directly. That is a property of the API, not a defect to be papered over by renaming functions or packing the binary.

Runtime is fully offline. Keys needed for decryption are necessarily present in the native extension.

## License

MIT. Publishing a wheel is a separate step from implementing this package and is not implied by the license text.

