feat: add optional Rust acceleration, benchmarks, and CI integration

Introduce acceleration layer (gsppy/accelerate.py) that uses a PyO3 Rust extension for support counting and gracefully falls back to pure Python; runtime backend selection via GSPPY_BACKEND (rust/python/auto).
Add bench_support.py (Click CLI) to compare Python vs Rust backends with options like --max_k and --warmup for reproducible micro-benchmarks.
Extend Makefile with Rust helpers: rust-setup, rust-build (idempotent skip when up-to-date by checking the installed .so vs Rust sources), bench-small, and bench-big; update help output with a Rust acceleration section.
Update README.md and CONTRIBUTING.md with instructions to build the Rust extension, choose a backend at runtime, and run benchmarks of various sizes.
CI: update codecov workflow to optionally install Rust and build the extension in tests, and add a dedicated test-rust job that builds the extension, runs tests with GSPPY_BACKEND=rust, and uploads coverage/test results flagged as "rust".
Motivation: improve performance of hot support-counting loops while preserving a zero-dependency Python fallback; provide tooling and CI coverage to ensure stability and reproducibility.

Author: jacksonpradolima

.github/workflows/codecov.yml

@@ -32,7 +32,24 @@ jobs:
                     uv sync --frozen --extra dev
                     uv pip install -e .
 
-            -   name: Run tests with coverage
+            -   name: Install Rust toolchain (optional)
+                continue-on-error: true
+                run: |
+                    curl -Ls https://sh.rustup.rs | bash -s -- -y || true
+                    echo "$HOME/.cargo/bin" >> $GITHUB_PATH || true
+                    source $HOME/.cargo/env || true
+                    rustc --version || true
+
+            -   name: Build Rust extension (optional)
+                continue-on-error: true
+                run: |
+                    source $HOME/.cargo/env || true
+                    uv run --python .venv/bin/python --no-project pip install maturin==1.6.0 || true
+                    cd rust && uv run --python .venv/bin/python --no-project python -m maturin develop --release || true
+
+            -   name: Run tests with coverage (Rust backend)
+                env:
+                    GSPPY_BACKEND: rust
                 run: |
                     uv run pytest --cov --cov-branch --junitxml=junit.xml -o junit_family=legacy
 
@@ -49,3 +66,55 @@ jobs:
                 uses: codecov/test-results-action@v1
                 with:
                     token: ${{ secrets.CODECOV_TOKEN }}
+
+    test-rust:
+        name: Run tests with Rust backend (Python ${{ matrix.python-version }})
+        runs-on: ubuntu-latest
+        strategy:
+            fail-fast: false
+            matrix:
+                python-version: ["3.13"]
+        steps:
+            -   name: Checkout
+                uses: actions/checkout@v5
+                with:
+                    fetch-depth: 0
+
+            -   name: Install uv
+                run: |
+                    curl -Ls https://astral.sh/uv/install.sh | bash
+                    echo "${HOME}/.local/bin" >> $GITHUB_PATH
+
+            -   name: Create venv (Python ${{ matrix.python-version }})
+                run: |
+                    uv python install ${{ matrix.python-version }}
+                    uv venv .venv --python ${{ matrix.python-version }}
+
+            -   name: Install dependencies
+                run: |
+                    uv sync --frozen --extra dev
+                    uv pip install -e .
+
+            -   name: Build Rust extension
+                run: |
+                    make rust-build
+
+            -   name: Run tests with coverage (Rust backend)
+                env:
+                    GSPPY_BACKEND: rust
+                run: |
+                    uv run pytest --cov=gsppy --cov-branch --cov-report=term-missing:skip-covered --cov-report=xml --junitxml=junit-rust.xml -o junit_family=legacy
+
+            -   name: Upload coverage to Codecov (rust)
+                uses: codecov/codecov-action@v5
+                with:
+                    files: coverage.xml
+                    flags: rust
+                    name: codecov-coverage-report-rust
+
+            -   name: Upload test results to Codecov (rust)
+                if: ${{ !cancelled() }}
+                uses: codecov/test-results-action@v1
+                with:
+                    flags: rust
+                    files: junit-rust.xml

CONTRIBUTING.md

@@ -128,6 +128,33 @@ To get familiar with the existing code, follow these steps:
 
    Note: This project integrates the "tox-uv" plugin. When running `tox` locally (or `make tox`), missing Python interpreters can be provisioned automatically via uv, so you don't need to have all versions installed ahead of time.
 
+4. **Optional: Rust Acceleration**
+
+Some hot loops can be accelerated with Rust via PyO3. This is entirely optional: the library will fall back to pure Python if the extension is not present.
+
+- Install Rust and build the extension:
+   ```bash
+   make rust-build
+   ```
+
+- Choose backend at runtime (defaults to auto):
+   ```bash
+   export GSPPY_BACKEND=rust   # or python, or unset for auto
+   ```
+
+- Run a benchmark (small):
+   ```bash
+   make bench-small
+   ```
+
+- Run a larger benchmark (adjust to your machine):
+   ```bash
+   make bench-big
+   # or customize:
+   GSPPY_BACKEND=auto uv run --python .venv/bin/python --no-project \
+      python benchmarks/bench_support.py --n_tx 1000000 --tx_len 8 --vocab 50000 --min_support 0.2 --warmup
+   ```
+
 3. **Explore the Code**:
    The main entry point for the GSP algorithm is in the `gsppy` module. The libraries for support counting, candidate generation, and additional utility functions are also within this module.
 

Makefile

@@ -30,6 +30,11 @@ help:
 	@echo "  check                  - lint + typecheck + test"
 	@echo "\nEnvironment:"
 	@echo "  UV_LINK_MODE=$(UV_LINK_MODE) (default: copy)"
+	@echo "\nRust acceleration:"
+	@echo "  rust-setup             - Install Rust toolchain (rustup)"
+	@echo "  rust-build             - Build and develop-install Rust extension via maturin (skips if up-to-date)"
+	@echo "  bench-small            - Run small benchmark (default sizes)"
+	@echo "  bench-big              - Run large benchmark (e.g., 1M tx; beware memory/CPU)"
 
 # Ensure uv is installed; install if missing
 ensure-uv:
@@ -132,3 +137,57 @@ check: lint typecheck test
 check-precommit: ensure-uv install
 	$(MAKE) test
 	$(MAKE) typecheck
+
+# --- Rust acceleration helpers ---
+.PHONY: rust-setup rust-build bench-small bench-big
+
+rust-setup:
+	@if ! command -v rustc >/dev/null 2>&1; then \
+	  echo "Installing Rust toolchain..."; \
+	  curl -Ls https://sh.rustup.rs | bash -s -- -y; \
+	  source $$HOME/.cargo/env; \
+	  rustc --version; \
+	else \
+	  rustc --version; \
+	fi
+
+rust-build: ensure-uv rust-setup
+	@# Optionally force rebuild: make rust-build FORCE_RUST_BUILD=1
+	@force_build="$(FORCE_RUST_BUILD)"; \
+	 if [ "$$force_build" = "1" ]; then \
+	   echo "FORCE_RUST_BUILD=1 set; rebuilding Rust extension"; \
+	   source $$HOME/.cargo/env; \
+	   $(UV) pip install --python $(PYTHON) --upgrade pip setuptools wheel maturin==1.6.0 >/dev/null; \
+	   $(UV) run --python $(PYTHON) --no-project python -m maturin develop --release -m rust/Cargo.toml; \
+	   exit $$?; \
+	 fi; \
+	 # Determine if extension is already installed and up-to-date (resolve the .so path) \
+	 so_path="$$( \
+	   $(UV) run --python $(PYTHON) --no-project python -c 'import importlib.util as u; s=u.find_spec("_gsppy_rust._gsppy_rust"); print(s.origin if s and s.origin else(""))' \
+	 )"; \
+	 if [ -n "$$so_path" ] && [ -f "$$so_path" ]; then \
+	   up_to_date=1; \
+	   for src in rust/Cargo.toml $$(find rust/src -type f -name '*.rs'); do \
+	     if [ "$$src" -nt "$$so_path" ]; then up_to_date=0; break; fi; \
+	   done; \
+	   if [ "$$up_to_date" -eq 1 ]; then \
+	     echo "Rust extension is up-to-date at $$so_path; skipping build"; \
+	     exit 0; \
+	   else \
+	     echo "Rust sources changed; rebuilding"; \
+	   fi; \
+	 else \
+	   echo "Rust extension missing; building"; \
+	 fi; \
+	 source $$HOME/.cargo/env; \
+	 $(UV) pip install --python $(PYTHON) --upgrade pip setuptools wheel maturin==1.6.0 >/dev/null; \
+	 $(UV) run --python $(PYTHON) --no-project python -m maturin develop --release -m rust/Cargo.toml
+
+bench-small: rust-build
+	@$(UV) run --python $(PYTHON) --no-project pip install -e . >/dev/null; \
+	 GSPPY_BACKEND=auto $(UV) run --python $(PYTHON) --no-project python benchmarks/bench_support.py --n_tx 100000 --tx_len 8 --vocab 10 --min_support 0.2 --warmup
+
+bench-big: rust-build
+	@echo "WARNING: This may take significant memory/CPU. Adjust sizes to your machine."; \
+	 $(UV) run --python $(PYTHON) --no-project pip install -e . >/dev/null; \
+	 GSPPY_BACKEND=auto $(UV) run --python $(PYTHON) --no-project python benchmarks/bench_support.py --n_tx 1000000 --tx_len 8 --vocab 50000 --min_support 0.2

README.md

@@ -115,7 +115,30 @@ uv sync --frozen --extra dev  # uses uv.lock
 uv pip install -e .
 ```
 
-#### 3. Common development tasks
+#### 3. Optional: Enable Rust acceleration
+
+Rust acceleration is optional and provides faster support counting using a PyO3 extension. Python fallback remains available.
+
+Build the extension locally:
+```bash
+make rust-build
+```
+
+Select backend at runtime (auto tries Rust, then falls back to Python):
+```bash
+export GSPPY_BACKEND=rust   # or python, or unset for auto
+```
+
+Run benchmarks (adjust to your machine):
+```bash
+make bench-small
+make bench-big   # may use significant memory/CPU
+# or customize:
+GSPPY_BACKEND=auto uv run --python .venv/bin/python --no-project \
+  python benchmarks/bench_support.py --n_tx 1000000 --tx_len 8 --vocab 50000 --min_support 0.2 --warmup
+```
+
+#### 4. Common development tasks
 After the environment is ready, activate it and run tasks with standard tools:
 
 ```bash
@@ -133,7 +156,7 @@ uv run ruff check .
 uv run pyright
 ```
 
-#### 4. Makefile (shortcuts)
+#### 5. Makefile (shortcuts)
 You can use the Makefile to automate common tasks:
 
 ```bash
@@ -145,6 +168,12 @@ make format              # ruff --fix
 make typecheck           # pyright (and mypy if configured)
 make pre-commit-install  # install the pre-commit hook
 make pre-commit-run      # run pre-commit on all files
+
+# Rust-specific shortcuts
+make rust-setup          # install rustup toolchain
+make rust-build          # build PyO3 extension with maturin
+make bench-small         # run small benchmark
+make bench-big           # run large benchmark
 ```
 
 > [!NOTE]

benchmarks/bench_support.py

@@ -0,0 +1,63 @@
+import os
+import time
+import random
+from typing import List, Optional
+
+import click
+
+from gsppy.gsp import GSP
+
+random.seed(0)
+
+
+def gen_data(n_tx: int, tx_len: int, vocab_size: int) -> List[List[str]]:
+    vocab = [f"I{i}" for i in range(vocab_size)]
+    # Using comprehension keeps it simple; for very large n, consider streaming
+    return [random.sample(vocab, tx_len) for _ in range(n_tx)]
+
+
+def run_once(backend: str, transactions: List[List[str]], min_support: float, max_k: Optional[int]) -> float:
+    os.environ["GSPPY_BACKEND"] = backend
+    t0 = time.perf_counter()
+    GSP(transactions).search(min_support=min_support, max_k=max_k)
+    return time.perf_counter() - t0
+
+
+@click.command()
+@click.option("--n_tx", default=10_000, show_default=True, type=int, help="Number of transactions (e.g., 1_000_000)")
+@click.option("--tx_len", default=8, show_default=True, type=int, help="Items per transaction")
+@click.option("--vocab", default=10_000, show_default=True, type=int, help="Vocabulary size")
+@click.option("--min_support", default=0.2, show_default=True, type=float, help="Minimum fractional support (0,1]")
+@click.option(
+    "--max_k",
+    default=1,
+    show_default=True,
+    type=int,
+    help="Limit maximum sequence length (1 focuses on singleton support)",
+)
+@click.option("--warmup", is_flag=True, help="Do a Python warmup run before timing")
+def main(n_tx: int, tx_len: int, vocab: int, min_support: float, max_k: int, warmup: bool) -> None:
+    click.echo(f"Generating data: n_tx={n_tx:,}, tx_len={tx_len}, vocab={vocab:,}")
+    transactions = gen_data(n_tx=n_tx, tx_len=tx_len, vocab_size=vocab)
+
+    if warmup:
+        try:
+            run_once("python", transactions, min_support, max_k)
+        except Exception:
+            pass
+
+    click.echo("Running Python backend...")
+    t_py = run_once("python", transactions, min_support, max_k)
+
+    click.echo("Running Rust backend...")
+    try:
+        t_rs = run_once("rust", transactions, min_support, max_k)
+        speedup = t_py / t_rs if t_rs > 0 else float("inf")
+        improvement = (t_py - t_rs) / t_py * 100.0
+        click.echo(f"Python: {t_py:.3f}s\nRust:   {t_rs:.3f}s\nSpeedup: {speedup:.2f}x  (+{improvement:.1f}%)")
+    except Exception as e:
+        click.echo(f"Rust backend not available or failed: {e}\nPython time: {t_py:.3f}s")
+
+
+if __name__ == "__main__":
+    main()