saber-risk 0.2.0__tar.gz

saber_risk-0.2.0/.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

saber_risk-0.2.0/.github/workflows/codeql.yml

@@ -0,0 +1,35 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly on Sunday
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'python' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

saber_risk-0.2.0/.gitignore

@@ -0,0 +1,116 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+.DS_Store
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# IDE pycharm
+.idea/
+
+.pt_description_history
+.git-credentials
+pt_bert/philly
+.vs
+*.pyproj
+*pyc
+/.vscode

saber_risk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

saber_risk-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: saber-risk
+Version: 0.2.0
+Summary: SABER: Scaling-Aware Best-of-N Estimation of Risk for LLM safety evaluation
+Project-URL: Homepage, https://github.com/microsoft/saber
+Project-URL: Documentation, https://github.com/microsoft/saber#readme
+Project-URL: Repository, https://github.com/microsoft/saber
+Author: Xiaodong Liu, Mingqian Feng
+License: MIT
+License-File: LICENSE
+Keywords: adversarial,best-of-n,jailbreak,llm,risk-estimation,safety
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SABER
+
+**S**caling-**A**ware **B**est-of-N **E**stimation of **R**isk
+
+A Python package for predicting large-scale adversarial risk in Large Language Models under Best-of-N sampling.
+
+**Paper**: https://arxiv.org/pdf/2601.22636
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+Standard LLM safety evaluations use single-shot (ASR@1) metrics, but real attackers can exploit parallel sampling to repeatedly probe models. SABER provides a principled statistical framework to:
+
+- **Predict** ASR@N at large budgets from small measurements
+- **Estimate** how many attempts are needed to reach a target success rate  
+- **Quantify** uncertainty in adversarial risk predictions
+
+![SABER Method Overview](https://raw.githubusercontent.com/microsoft/saber/main/figures/saber_method.png)
+
+### Key Insight
+
+Attack success rates scale according to a power law governed by the Beta distribution of per-query vulnerabilities:
+
+```
+ASR@N ≈ 1 - Γ(α+β)/Γ(β) · N^(-α)
+```
+
+The parameter **α** controls how fast risk amplifies with more attempts.
+
+## Installation
+
+```bash
+pip install saber-risk
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/microsoft/saber
+cd saber
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from saber import SABER
+
+# Your jailbreak evaluation data:
+# k[i] = number of successful jailbreaks for query i
+# n[i] = number of attempts for query i
+k = np.array([3, 5, 0, 2, 8, 1, 4, 0, 6, 2])  
+n = 100  # 100 attempts per query
+
+# Fit and predict
+model = SABER()
+model.fit(k, n)
+
+# Predict ASR at N=1000 attempts
+result = model.predict(N=1000)
+print(f"ASR@1000 = {result.asr:.2%}")
+
+# With confidence interval
+result = model.predict(N=1000, confidence=0.95)
+print(f"ASR@1000 = {result.asr:.2%} [{result.ci_lower:.2%}, {result.ci_upper:.2%}]")
+```
+
+## Core Usage
+
+```python
+from saber import SABER
+
+# 1. Collect jailbreak data
+#    Run n attempts per query, count successes k
+k = [...]  # successes per query
+n = 100    # trials per query (or array for heterogeneous budgets)
+
+# 2. Fit the model
+model = SABER()
+model.fit(k, n)
+
+# 3. Predict ASR at target budget
+asr_1000 = model.predict(N=1000).asr
+
+# Budget estimation
+result = model.budget_for_asr(target=0.95)
+print(f"Need {result.budget:.0f} attempts for 95% ASR")
+
+# Fluent API
+asr = SABER().fit(k, n).predict(1000).asr
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` directory. To build:
+
+```bash
+cd docs
+pip install -r requirements.txt
+make html
+```
+
+- **[Quick Start](https://github.com/microsoft/saber/blob/main/docs/quickstart.rst)** - Getting started guide
+- **[API Reference](https://github.com/microsoft/saber/blob/main/docs/api_reference.rst)** - Complete API documentation
+- **[Advanced Usage](https://github.com/microsoft/saber/blob/main/docs/advanced_usage.rst)** - Model selection, scaling curves, low-level API
+
+## Citation
+
+If you use SABER in your research, please cite:
+
+```bibtex
+@misc{feng2026statisticalestimationadversarialrisk,
+      title={Statistical Estimation of Adversarial Risk in Large Language Models under Best-of-N Sampling}, 
+      author={Mingqian Feng and Xiaodong Liu and Weiwei Yang and Chenliang Xu and Christopher White and Jianfeng Gao},
+      year={2026},
+      eprint={2601.22636},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2601.22636}, 
+}
+```
+
+## Contact
+
+For any questions regarding the package or paper, feel free to reach out to:
+
+- **Mingqian Feng** - mfeng7@ur.rochester.edu
+- **Xiaodong Liu** - xiaodl@microsoft.com
+- **Weiwei Yang** - weiwei.yang@microsoft.com
+
+## License
+
+MIT License - see [LICENSE](https://github.com/microsoft/saber/blob/main/LICENSE) for details.

saber_risk-0.2.0/README.md

@@ -0,0 +1,136 @@
+# SABER
+
+**S**caling-**A**ware **B**est-of-N **E**stimation of **R**isk
+
+A Python package for predicting large-scale adversarial risk in Large Language Models under Best-of-N sampling.
+
+**Paper**: https://arxiv.org/pdf/2601.22636
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Overview
+
+Standard LLM safety evaluations use single-shot (ASR@1) metrics, but real attackers can exploit parallel sampling to repeatedly probe models. SABER provides a principled statistical framework to:
+
+- **Predict** ASR@N at large budgets from small measurements
+- **Estimate** how many attempts are needed to reach a target success rate  
+- **Quantify** uncertainty in adversarial risk predictions
+
+![SABER Method Overview](https://raw.githubusercontent.com/microsoft/saber/main/figures/saber_method.png)
+
+### Key Insight
+
+Attack success rates scale according to a power law governed by the Beta distribution of per-query vulnerabilities:
+
+```
+ASR@N ≈ 1 - Γ(α+β)/Γ(β) · N^(-α)
+```
+
+The parameter **α** controls how fast risk amplifies with more attempts.
+
+## Installation
+
+```bash
+pip install saber-risk
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/microsoft/saber
+cd saber
+pip install -e .
+```
+
+## Quick Start
+
+```python
+import numpy as np
+from saber import SABER
+
+# Your jailbreak evaluation data:
+# k[i] = number of successful jailbreaks for query i
+# n[i] = number of attempts for query i
+k = np.array([3, 5, 0, 2, 8, 1, 4, 0, 6, 2])  
+n = 100  # 100 attempts per query
+
+# Fit and predict
+model = SABER()
+model.fit(k, n)
+
+# Predict ASR at N=1000 attempts
+result = model.predict(N=1000)
+print(f"ASR@1000 = {result.asr:.2%}")
+
+# With confidence interval
+result = model.predict(N=1000, confidence=0.95)
+print(f"ASR@1000 = {result.asr:.2%} [{result.ci_lower:.2%}, {result.ci_upper:.2%}]")
+```
+
+## Core Usage
+
+```python
+from saber import SABER
+
+# 1. Collect jailbreak data
+#    Run n attempts per query, count successes k
+k = [...]  # successes per query
+n = 100    # trials per query (or array for heterogeneous budgets)
+
+# 2. Fit the model
+model = SABER()
+model.fit(k, n)
+
+# 3. Predict ASR at target budget
+asr_1000 = model.predict(N=1000).asr
+
+# Budget estimation
+result = model.budget_for_asr(target=0.95)
+print(f"Need {result.budget:.0f} attempts for 95% ASR")
+
+# Fluent API
+asr = SABER().fit(k, n).predict(1000).asr
+```
+
+## Documentation
+
+Full documentation is available in the `docs/` directory. To build:
+
+```bash
+cd docs
+pip install -r requirements.txt
+make html
+```
+
+- **[Quick Start](https://github.com/microsoft/saber/blob/main/docs/quickstart.rst)** - Getting started guide
+- **[API Reference](https://github.com/microsoft/saber/blob/main/docs/api_reference.rst)** - Complete API documentation
+- **[Advanced Usage](https://github.com/microsoft/saber/blob/main/docs/advanced_usage.rst)** - Model selection, scaling curves, low-level API
+
+## Citation
+
+If you use SABER in your research, please cite:
+
+```bibtex
+@misc{feng2026statisticalestimationadversarialrisk,
+      title={Statistical Estimation of Adversarial Risk in Large Language Models under Best-of-N Sampling}, 
+      author={Mingqian Feng and Xiaodong Liu and Weiwei Yang and Chenliang Xu and Christopher White and Jianfeng Gao},
+      year={2026},
+      eprint={2601.22636},
+      archivePrefix={arXiv},
+      primaryClass={cs.AI},
+      url={https://arxiv.org/abs/2601.22636}, 
+}
+```
+
+## Contact
+
+For any questions regarding the package or paper, feel free to reach out to:
+
+- **Mingqian Feng** - mfeng7@ur.rochester.edu
+- **Xiaodong Liu** - xiaodl@microsoft.com
+- **Weiwei Yang** - weiwei.yang@microsoft.com
+
+## License
+
+MIT License - see [LICENSE](https://github.com/microsoft/saber/blob/main/LICENSE) for details.

saber_risk-0.2.0/SECURITY.md

@@ -0,0 +1,14 @@
+<!-- BEGIN MICROSOFT SECURITY.MD V1.0.0 BLOCK -->
+
+## Security
+
+Microsoft takes the security of our software products and services seriously, which
+includes all source code repositories in our GitHub organizations.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+For security reporting information, locations, contact information, and policies,
+please review the latest guidance for Microsoft repositories at
+[https://aka.ms/SECURITY.md](https://aka.ms/SECURITY.md).
+
+<!-- END MICROSOFT SECURITY.MD BLOCK -->

saber_risk-0.2.0/docs/Makefile

@@ -0,0 +1,14 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

saber_risk-0.2.0/docs/advanced_usage.rst

@@ -0,0 +1,124 @@
+Advanced Usage
+==============
+
+Heterogeneous Budgets
+---------------------
+
+SABER supports different trial counts per query:
+
+.. code-block:: python
+
+   import numpy as np
+   from saber import SABER
+
+   k = np.array([3, 5, 0, 2, 8])
+   n = np.array([50, 100, 75, 100, 200])  # Different budgets
+
+   model = SABER()
+   model.fit(k, n)
+
+Model Selection
+---------------
+
+.. code-block:: python
+
+   # SABER-Anchored (default, recommended)
+   model = SABER(method="anchored")
+
+   # SABER-Plugin (uses β directly)
+   model = SABER(method="plugin")
+
+   # Override for specific prediction
+   result = model.predict(N=1000, method="naive")
+   result = model.predict(N=1000, method="combinatorial")   # N must be <= min(n)
+   result = model.predict(N=1000, method="log_linear_curve")  # auto-fits curve if not fitted
+
+   # Small-N Correction
+   result = model.predict(N=1000, method="anchored", correction=True)
+
+Log-Linear Curve Fit
+--------------------
+
+The default fit is always the Beta distribution (α, β). You can additionally fit a log-linear curve:
+
+.. code-block:: python
+
+   # Fit both distribution and curve
+   model = SABER()
+   model.fit(k, n, also_fit_curve=True)
+
+   # Or: fit only distribution; curve will be auto-fitted on first use
+   model.fit(k, n)
+   result = model.predict(N=1000, method="log_linear_curve")
+
+Low-Level API
+-------------
+
+For advanced usage, access the underlying functions directly:
+
+.. code-block:: python
+
+   from saber import fit_beta_binomial, predict_anchored, estimate_budget
+
+   # Fit distribution
+   alpha, beta = fit_beta_binomial(k, n)
+
+   # Predict ASR
+   asr = predict_anchored(N=1000, n=100, asr_at_n=0.73, alpha=alpha)
+
+   # Estimate budget
+   budget = estimate_budget(target_asr=0.95, n=100, asr_at_n=0.73, alpha=alpha)
+
+Scaling Curves
+--------------
+
+Generate data for plotting:
+
+.. code-block:: python
+
+   import matplotlib.pyplot as plt
+
+   curve = model.scaling_curve(
+       include_naive=True,
+       include_combinatorial=True,
+       correction=False
+   )
+
+   plt.figure(figsize=(8, 5))
+   plt.plot(curve['N'], curve['asr_anchored'] * 100, label='SABER-Anchored')
+   plt.plot(curve['N'], curve['asr_plugin'] * 100, label='SABER-Plugin')
+   if 'asr_log_linear_curve' in curve:
+       plt.plot(curve['N'], curve['asr_log_linear_curve'] * 100, label='Log-linear curve')
+   plt.plot(curve['N'], curve['asr_naive'] * 100, '--', label='Naive Baseline')
+   plt.xscale('log')
+   plt.xlabel('Number of Attempts (N)')
+   plt.ylabel('ASR@N (%)')
+   plt.legend()
+   plt.title('ASR Scaling Curve')
+   plt.show()
+
+Estimator Variants
+------------------
+
+.. list-table::
+   :widths: 25 40 35
+   :header-rows: 1
+
+   * - Variant
+     - Equation
+     - Best For
+   * - **SABER-Anchored**
+     - ``1 - (1-ASR@n)·(n/N)^α``
+     - Most cases (default)
+   * - **SABER-Plugin**
+     - ``1 - Γ(α+β)/Γ(β)·N^(-α)``
+     - When ASR@n unavailable
+   * - **SABER-Fitting**
+     - ``exp(-a·N^(-b))``
+     - Alternative scaling model
+   * - **Naive Baseline**
+     - ``(1/K) Σ (1-(1-θ)^N)``
+     - Comparison only
+   * - **Combinatorial**
+     - ``1 - (1/K) Σ (C(n-k,N)/C(n,N))``
+     - N ≤ min(n) only