Metadata-Version: 2.4
Name: binaml
Version: 0.1.0a1
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: numpy>=1.24
Requires-Dist: seaborn>=0.13 ; extra == 'benchmarks'
Requires-Dist: scikit-learn>=1.5 ; extra == 'benchmarks'
Provides-Extra: benchmarks
License-File: LICENSE
Summary: Online regression with layered boolean-function learning
Keywords: boolean-functions,machine-learning,online-learning,streaming
Author: Romain Zimmer
Requires-Python: >=3.13
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/binaml/binaml
Project-URL: Issues, https://github.com/binaml/binaml/issues
Project-URL: Repository, https://github.com/binaml/binaml

![Binaml](assets/banner/binaml-banner.svg)

Binaml focuses on continual learning models over streams of binary features
subject to data drift.
Binary features provide a task-agnostic representation and enable models
optimized for memory, latency, and energy efficiency.

## Core concepts

Binaml starts with input bits and builds richer features by composing pairs of
Boolean features. Each composition is one of the 16 Boolean functions of arity
two, represented as a four-bit truth table. Repeated composition forms layered,
inspectable Boolean feature graphs.

A linear model combines the resulting features and adapts online to drift.
`BRegressor` is the current Binaml model, combining online SGD with
residual-learned composed Boolean features.

See the [Binaml paper](papers/binaml/) for the model specification.

The supported Python API is `binaml.BRegressor`. The supported Rust API is
`binaml_core::BRegressor`. `binaml._core` is a private implementation detail.

## Quick start: Python

Install the alpha package with uv:

```bash
uv add "binaml==0.1.0a1"
```

To run from a checkout, install Python 3.13+, a Rust toolchain, and the project
dependencies:

```bash
uv sync
```

```python
import numpy as np
from binaml import BRegressor

model = BRegressor(n_features=2)

for features, target in [
    (np.array([0, 1], dtype=np.uint8), 1.0),
    (np.array([1, 0], dtype=np.uint8), 0.0),
]:
    prediction = model.predict(features)
    model.observe(features, target)
```

Each `predict(features)` call must be followed by `observe(features, target)`.

## Quick start: Rust

Add `binaml-core` to your `Cargo.toml`:

```toml
[dependencies]
binaml-core = "0.1.0-alpha.1"
```

```rust
use binaml_core::{BRegressor, BRegressorError};

fn main() -> Result<(), BRegressorError> {
    let mut model = BRegressor::with_hyperparameters(
        2, 0.03, 1e-4, 32, 3, 8, 32, 32, 2,
    )?;

    for (features, target) in [([false, true], 1.0), ([true, false], 0.0)] {
        let prediction = model.predict(&features)?;
        model.observe(&features, target)?;
        println!("{prediction}");
    }

    Ok(())
}
```

## Benchmarks

The included synthetic streaming-regression environment and prequential
evaluation protocol compare `BRegressor` with `SGDLinearRegressor`, a Python
SGD baseline with L2 weight decay. See the
[synthetic drifting regression paper](papers/synthetic-drifting-regression/)
for the benchmark specification. Plotting support is optional:

```bash
uv run --extra benchmarks python -m binaml.benchmarks.synthetic_streaming_regression.cli \
  --scenario python/binaml/benchmarks/synthetic_streaming_regression/scenarios/default.json
```

## Citation

If you use Binaml, cite the software metadata in
[CITATION.cff](CITATION.cff). Cite [our papers](papers/) separately when their model or
benchmark specification informs your work.

## License

Source code is licensed under [Apache-2.0](LICENSE).

