Metadata-Version: 2.4
Name: rbp-engine
Version: 1.2.4
Summary: Relevance-Based Prediction (RBP) for Python — NumPy-friendly bindings to the RBP math engine.
Author: Cambridge Sports Analytics
License: Proprietary
Keywords: numpy,prediction,rbp,statistics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# rbp-engine

Relevance-Based Prediction (RBP) Engine for Python: NumPy-friendly bindings to the RBP
prediction engine from [Cambridge Sports Analytics](https://www.csanalytics.io).

Relevance-based prediction (RBP) is a model-free prediction routine that forms a prediction
as a weighted average of observed outcomes in which the weights are based on a statistic
called relevance. Relevance is composed of similarity and informativeness which are both
measured as Mahalanobis distances. RBP serves as a favorable alternative to conventional
prediction methods such as linear regression analysis because it addresses complex
dynamics that are beyond the reach of linear regression analysis. It also serves as a favorable
alternative to AI models because RBP can extract as much information from complex
datasets as AI models but more efficiently and with full transparency.

```bash
pip install rbp-engine
```

## Quick start

```python
import numpy as np
from rbp_engine import predict_grid, GridOptions, relevance, similarity, info_x, info_theta, relevance_metrics

# y: outcomes (N,)
# X: attributes (N, K)
# theta: circumstances (K,) — the single case you want a prediction for
out = predict_grid(y, X, theta, GridOptions())
print(float(out.yhat[0]))   # fit-weighted composite across attribute × observation calibrations

# Relevance-based scores without a full prediction
r = relevance(X, theta)       # relevance of each training row to the circumstances
s = similarity(X, theta)      # similarity (Mahalanobis) of each row to theta
ix = info_x(X)                # informativeness of each row vs the sample mean
it = info_theta(X, theta)     # informativeness of the circumstances vs the sample mean

# Or, all four in one native pass:
m = relevance_metrics(X, theta)
m.relevance, m.similarity, m.info_x, m.info_theta
```

For most analysis work, start with `predict_grid`. It evaluates combinations of attributes
and observation subsets, then forms one composite prediction (`yhat` of length 1) weighted by
adjusted fit.

Use `relevance`, `similarity`, `info_x`, and `info_theta` when you need scores without
running a full prediction.

Built-in help includes paste-ready examples:

```python
help(predict_grid)
help(GridOptions)
help(PredictionResults)
```

## Core functions

| Symbol | Role |
|--------|------|
| `predict_grid` / `GridOptions` | **Recommended default.** Grid prediction uses combinations of attributes and observation subsets evaluate cell predictions by adjusted fit into one optimal composite (`yhat`, length 1), with rich insights |
| `predict_maxfit` / `MaxFitOptions` | For a fixed attribute set, evaluate across thresholds (and optionally both censor types) and solve for the max fit / adjusted-fit / k-fit result |
| `predict` / `PredictOptions` | Partial-sample regression using relevance-weighted average of outcomes at one or more chosen thresholds; MaxFit and Grid prediction wraps this |
| `relevance` | Relevance scores of each observation to circumstances (`theta`); as a function of similarity and informativeness |
| `similarity` | Similarity scores of each observation to circumstances |
| `info_x`, `info_theta` | Informativeness: how unusual each observation (`info_x`) or the circumstances (`info_theta`) are relative to the sample mean |
| `relevance_metrics` | All four scores above in one call (one native pass) |
| `PredictionResults` | NumPy snapshot: nested groups mirror Rust (`insights`, `prediction_weights`, `solo_distribution`, `grid_*`, …); core fields on root |

## Supported platforms

Installs with `pip` on Python 3.10+. Nothing to compile, no extra system libraries.

| Supported Platform | Notes |
|---|---|
| macOS 11+ (Apple Silicon) | Preferred platform; uses Apple Accelerate |
| Linux (Intel/AMD) | glibc 2.34+ (RHEL 9 / Alma / Rocky / Amazon Linux 2023 / Ubuntu 22.04+) |
| Linux (Arm) | same glibc floor |
| Windows (Intel/AMD) | Supported; Apple Silicon macOS preferred when you have a choice |

If your platform isn't listed, `pip` will report that no matching distribution
was found.

Requires `numpy>=1.24`.

## License

`rbp-engine` is commercial software and requires a license from Cambridge Sports
Analytics. Contact [prediction@csanalytics.io](mailto:prediction@csanalytics.io)
to get started.

After install, `rbp-license-info` is available in the same environment
(activate your virtual environment if you use one):

```bash
rbp-license-info                             # request code, or status if already licensed
rbp-license-info --setlicense 'RBP-LIC-1:…'  # install the token you receive
rbp-license-info --viewlicense               # always show license status
```

For site or server deployments, contact Cambridge Sports Analytics, setup
differs from the workstation flow above.

(c) 2026 Cambridge Prediction Analytics, LLC. All rights reserved.
