RiskLabAI · hamid-arian · Jun 16, 2026 · Jun 16, 2026 · Jun 16, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -52,17 +52,28 @@ jobs:
               print('ok:', sub)
           "
 
+  format:
+    name: black
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install black
+      - run: black --check RiskLabAI test
+
   lint:
-    name: ruff + black (advisory until format pass lands)
+    name: ruff (advisory until cleanup lands)
     runs-on: ubuntu-latest
-    # Non-blocking until the mechanical black/ruff formatting commit lands;
-    # then remove continue-on-error to make style CI-enforced.
+    # Advisory until the dedicated ruff-cleanup pass lands (Dict->dict
+    # modernization, star-import removal, unused-import pruning); then remove
+    # continue-on-error to enforce.
     continue-on-error: true
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-      - run: pip install ruff black
+      - run: pip install ruff
       - run: ruff check RiskLabAI test
-      - run: black --check RiskLabAI test
diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md
diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -1,58 +1,65 @@
-### 1\. Create the New Environment
+# Installation & Development Setup
 
-Open your terminal or Anaconda Prompt. This command will create a new, empty environment named `risklab` using a stable Python version (e.g., 3.10).
+## Install (users)
 
 ```bash
-conda create -n risklab python=3.10 -y
+pip install RiskLabAI
 ```
 
-### 2\. Activate the Environment
-
-You must activate the environment to install packages into it and use it.
+Optional extras pull in heavier dependencies only when you need them:
 
 ```bash
-conda activate risklab
+pip install "RiskLabAI[pde]"     # torch — the Deep-BSDE PDE solver
+pip install "RiskLabAI[plot]"    # matplotlib / seaborn / plotly — plotting helpers
+pip install "RiskLabAI[synth]"   # quantecon — synthetic-data utilities
+pip install "RiskLabAI[all]"     # everything above
 ```
 
-Your terminal prompt should now change to show `(risklab)` at the beginning.
+The base install is intentionally lightweight: `import RiskLabAI` does not pull
+in torch or plotting libraries — sub-packages that need them are imported lazily.
 
-### 3\. Install Your Project's Dependencies
+## Development setup (contributors)
 
-Navigate to the root directory of your `RiskLabAI.py` project (the one containing `requirements.txt`). This command will read your `requirements.txt` file and install all the necessary packages.
+### 1. Create and activate an environment
 
 ```bash
-# Navigate to your project folder first
-cd /path/to/your/RiskLabAI.py
-
-# Install all packages from your requirements file
-pip install -r requirements.txt
+conda create -n risklab python=3.11 -y
+conda activate risklab
 ```
 
-### 4\. Install Your Library in "Editable" Mode
+(Any Python 3.9–3.12 works; a venv is fine too.)
 
-This is a crucial step for development and testing. It links your `RiskLabAI` source code to the environment, which allows your test suite to import your library as if it were officially installed.
+### 2. Install in editable mode with all extras and test tooling
 
-From the same root directory (where your `pyproject.toml` is), run:
+Dependencies are declared in `pyproject.toml` (there is **no** `requirements.txt`).
+From the repository root:
 
 ```bash
-pip install -e .
+pip install -e ".[all]" pytest black ruff
 ```
 
-### 5\. Run Your Tests
+The editable install (`-e`) links the package to your source tree so the test
+suite imports your local code.
 
-Now you are all set. The standard way to run your test suite is by using `pytest`. If `pytest` wasn't included in your `requirements.txt`, you can install it:
+> On some setuptools versions the plain editable install does not expose all
+> sub-modules. If `import RiskLabAI.backtest.bet_sizing` fails, reinstall with
+> the compatibility mode:
+> ```bash
+> pip install -e . --config-settings editable_mode=compat
+> ```
+
+### 3. Run the tests
 
 ```bash
-pip install pytest
+pytest -q --ignore=test/pde
 ```
 
-Then, simply run the following command from your project's root directory:
+`test/pde` is skipped unless you have a working `torch` runtime (install the
+`[pde]` extra to include it).
 
-```bash
-pytest
-```
-If you want to be fast, you can tell `pytest` to ignore that specific directory when you run your tests:
+### 4. Lint and format before committing
 
 ```bash
-pytest --ignore=RiskLabAI/pde
-```
+black RiskLabAI test
+ruff check RiskLabAI test
+```
diff --git a/README.md b/README.md
@@ -1,20 +1,113 @@
 # RiskLabAI.py
+
 [![PyPI version](https://badge.fury.io/py/RiskLabAI.svg)](https://badge.fury.io/py/RiskLabAI)
+[![CI](https://github.com/RiskLabAI/RiskLabAI.py/actions/workflows/ci.yml/badge.svg)](https://github.com/RiskLabAI/RiskLabAI.py/actions/workflows/ci.yml)
+
+A Python library for quantitative finance and financial machine learning,
+implementing core methods from Marcos López de Prado's *Advances in Financial
+Machine Learning* and *Machine Learning for Asset Managers*.
 
-A Python library for quantitative finance and financial AI, implementing core concepts from Marcos López de Prado's books, "Advances in Financial Machine Learning" and "Machine Learning for Asset Managers."
+The library provides implementations for:
 
-This library provides production-ready implementations for:
-* Advanced Financial Data Structures (Tick, Volume, Dollar, Imbalance, and Run Bars)
-* Fractional Differentiation (FFD)
-* The Triple-Barrier Method and Meta-Labeling
-* Advanced Cross-Validation (Purged K-Fold, Combinatorial Purged CV)
-* Feature Importance (MDI, MDA, SFI) and Clustered Feature Importance
-* Portfolio Optimization (HRP, NCO)
-* And many more...
+- **Financial data structures** — tick, volume, dollar, imbalance, and run bars
+- **Labeling** — the triple-barrier method, meta-labeling, trend-scanning
+- **Fractional differentiation** — standard and fixed-width window (FFD)
+- **Sample weights**, **denoising** (Marčenko–Pastur), **distance metrics**
+- **Cross-validation** — Purged K-Fold, Combinatorial Purged CV (+ adaptive/bagged), walk-forward
+- **Feature importance** — MDI, MDA, SFI, and clustered variants
+- **Portfolio optimization** — HRP, NCO, hedging
+- **Backtest statistics** — PSR/DSR, PBO, strategy risk
+- **Microstructure & entropy features**, **structural breaks**, and a Deep-BSDE PDE solver
 
-## 📦 Installation
+There is a companion Julia package,
+[RiskLabAI.jl](https://github.com/RiskLabAI/RiskLabAI.jl), which mirrors this
+API.
 
-Install the library directly from PyPI:
+## Installation
 
 ```bash
-pip install RiskLabAI
+pip install RiskLabAI
+```
+
+The base install is lightweight. Heavier, optional capabilities are available as
+extras:
+
+| Extra | Installs | Enables |
+|---|---|---|
+| `RiskLabAI[pde]` | `torch` | the Deep-BSDE PDE solver (`RiskLabAI.pde`) |
+| `RiskLabAI[plot]` | `matplotlib`, `seaborn`, `plotly` | plotting helpers |
+| `RiskLabAI[synth]` | `quantecon` | synthetic-data utilities |
+| `RiskLabAI[all]` | all of the above | everything |
+
+```bash
+pip install "RiskLabAI[all]"
+```
+
+For development (editable install + tests), see
+[`INSTALLATION.md`](INSTALLATION.md).
+
+## Quickstart
+
+Sample dollar/volume/tick bars from raw ticks:
+
+```python
+from RiskLabAI.data.structures.standard_bars import StandardBars
+from RiskLabAI.utils.constants import CUMULATIVE_DOLLAR
+
+# ticks: an iterable of (datetime, price, volume)
+ticks = [
+    ("2020-01-01 10:00:00", 100.0, 10),
+    ("2020-01-01 10:00:01", 101.0, 5),
+    ("2020-01-01 10:00:02", 100.0, 20),
+]
+
+bars = StandardBars(bar_type=CUMULATIVE_DOLLAR, threshold=3000)
+bar_list = bars.construct_bars_from_data(ticks)
+# each bar: [date_time, idx, open, high, low, close, volume,
+#            buy_volume, sell_volume, ticks, dollar, threshold]
+```
+
+Discover and construct components by name through the extension registry:
+
+```python
+import RiskLabAI.core as core
+
+core.list_components()                       # {family: [available keys]}
+cv = core.CROSS_VALIDATORS.create("purgedkfold", n_splits=5, times=event_times)
+```
+
+## Logging
+
+RiskLabAI logs under the `"RiskLabAI"` logger and is silent by default. To see
+progress and diagnostics, configure logging in your application:
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+## Extending the library
+
+RiskLabAI is built to be extended with new models. The `RiskLabAI.core` layer
+provides a component registry and base interfaces so a new bar type, labeler,
+cross-validator, etc. can be registered and discovered without editing central
+code. See [`EXTENDING.md`](EXTENDING.md) for a step-by-step guide with worked
+examples.
+
+## Contributing
+
+Contributions are welcome. The project uses `pytest` for tests and
+`black` + `ruff` for formatting/linting (run before opening a PR):
+
+```bash
+pip install -e ".[all]" pytest black ruff
+pytest -q --ignore=test/pde
+black RiskLabAI test
+ruff check RiskLabAI test
+```
+
+Please branch from `main`, keep changes focused, and update `CHANGELOG.md`.
+
+## License
+
+See [`LICENSE.txt`](LICENSE.txt).
diff --git a/RiskLabAI/__init__.py b/RiskLabAI/__init__.py
@@ -52,19 +52,21 @@
 # and stays silent unless the application opts in by configuring logging.
 _logging.getLogger(__name__).addHandler(_logging.NullHandler())
 
-_SUBMODULES = frozenset({
-    "backtest",
-    "cluster",
-    "controller",
-    "core",
-    "data",
-    "ensemble",
-    "features",
-    "hpc",
-    "optimization",
-    "pde",
-    "utils",
-})
+_SUBMODULES = frozenset(
+    {
+        "backtest",
+        "cluster",
+        "controller",
+        "core",
+        "data",
+        "ensemble",
+        "features",
+        "hpc",
+        "optimization",
+        "pde",
+        "utils",
+    }
+)
 
 # Single source of truth for the version is pyproject.toml.
 try:

diff --git a/RiskLabAI/backtest/__init__.py b/RiskLabAI/backtest/__init__.py
@@ -139,4 +139,4 @@
     "measure_cpcv_scalability",
     "get_cpu_info",
     "format_cpu_info",
-]
+]