Metadata-Version: 2.4
Name: r3alai
Version: 0.1.3
Summary: A Python library for Random Set Neural Networks with uncertainty estimation
Home-page: https://github.com/R3AL-AI/package
Author: Arshia
Author-email: Arshia <arshia@r3al.ai>
License-Expression: MIT
Project-URL: Homepage, https://github.com/R3AL-AI/package
Project-URL: Documentation, https://github.com/R3AL-AI/package#readme
Project-URL: Issues, https://github.com/R3AL-AI/package/issues
Project-URL: Source, https://github.com/R3AL-AI/package
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: torch>=1.12.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scikit-learn>=1.0.0
Provides-Extra: yolo
Requires-Dist: ultralytics>=8.1.0; extra == "yolo"
Provides-Extra: vision
Requires-Dist: torchvision>=0.13.0; extra == "vision"
Requires-Dist: Pillow>=9.0.0; extra == "vision"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# R3ALAI

Python SDK for Random Set Neural Networks (RSNN): uncertainty estimation, conformal prediction, and active learning. Built to add RSNN benefits (sample efficiency, robustness, reliability) to ML workflows.

## Install
- Base: `pip install r3alai`
- With vision backbones: `pip install 'r3alai[vision]'`
- With YOLO: `pip install 'r3alai[yolo]'`

Requires Python 3.8+ and PyTorch.

## What it provides
- `r3alai.models`: `RSNNClassifier` — RSNN head on a backbone (torchvision or custom `nn.Module`).
- `r3alai.conformal`: `ConformalPredictor` — confidence sets with distribution-free coverage after calibration.
- `r3alai.active_learning`: `ActiveLearner` — entropy/credal querying and simple disagreement mode.
- `r3alai.utils`: `RSNNYOLOWrapper`, `YOLOFeatureExtractor` — plug RSNN uncertainty into YOLOv8.

## How to use (high-level)
1) Create an RSNN model
- Pick a backbone: `"resnet50"`, `"mobilenet_v2"`, `"efficientnet_b0"`, or use a custom backbone.
- Set `n_classes` (one-hot labels expected). Optional `alpha`/`beta` regularization.

2) Train
- Call `fit(X, y, ...)` with tensors/ndarrays; early stopping and LR scheduling are included.

3) Predict with uncertainty
- Call `predict(..., return_uncertainty=True)` to get predictions, pignistic entropy, and credal width.

## Conformal prediction
1) Wrap a trained RSNN with `ConformalPredictor(confidence_level=0.9/0.95)`.
2) Calibrate on a held-out split (features and one-hot labels).
3) Use `predict` for confidence sets; `get_coverage` to measure empirical coverage.

## Active learning
1) Construct `ActiveLearner(model, uncertainty_measure="entropy"|"credal")`.
2) Provide an unlabeled pool to `query` to select samples and indices for annotation.

## YOLO integration (optional)
1) Install extras: `r3alai[yolo]`.
2) Initialize `RSNNYOLOWrapper(yolo_model_path, n_classes)`.
3) Train with your DataLoaders; optionally calibrate conformal and then predict with uncertainty or confidence sets.

## Custom backbones and frameworks
- Custom `nn.Module`: set `base_model="custom"`, assign your module to `rsnn_model.base_model`, then call `set_belief_layer(feature_dim)`.
- Hugging Face models: adapt outputs to a 512-dim feature vector and connect as a custom backbone.

## Tips
- Keep a small calibration split to enable conformal coverage.
- Start active learning with entropy querying; try disagreement for harder pools.
- For detection, first freeze the YOLO backbone and train only the RSNN head.

## Support
- See docstrings on `RSNNClassifier`, `ConformalPredictor`, `ActiveLearner`, and `RSNNYOLOWrapper`.
- Report issues and requests on GitHub Issues.

## License
MIT
