certifi-learn 0.2.0__tar.gz

certifi_learn-0.2.0/.github/workflows/wheels.yml

@@ -0,0 +1,81 @@
+# Builds wheels (one abi3 wheel per platform covers Python >= 3.9), runs the tests,
+# and publishes to PyPI when a version tag (v*) is pushed.
+name: Wheels
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: ${{ matrix.os }} ${{ matrix.target }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, target: x86_64, test: true }
+          - { os: ubuntu-latest, target: aarch64, test: false }
+          - { os: macos-15-intel, target: x86_64, test: true }
+          - { os: macos-latest, target: aarch64, test: true }
+          - { os: windows-latest, target: x64, test: true }
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Build wheel
+        uses: PyO3/maturin-action@v1
+        with:
+          target: ${{ matrix.target }}
+          args: --release --out dist
+          manylinux: auto
+      - name: Test wheel
+        if: ${{ matrix.test }}
+        shell: bash
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install "$(ls dist/*.whl)[highs,test]"
+          python -m pytest tests -q
+      - uses: actions/upload-artifact@v6
+        with:
+          name: wheels-${{ matrix.os }}-${{ matrix.target }}
+          path: dist
+
+  sdist:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build sdist
+        uses: PyO3/maturin-action@v1
+        with:
+          command: sdist
+          args: --out dist
+      - uses: actions/upload-artifact@v6
+        with:
+          name: sdist
+          path: dist
+
+  publish:
+    name: Publish to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build, sdist]
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/certifi-learn
+    permissions:
+      id-token: write  # trusted publishing, no API token needed
+    steps:
+      - uses: actions/download-artifact@v7
+        with:
+          pattern: "*"
+          merge-multiple: true
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1

certifi_learn-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ipynb_checkpoints/
+.venv/
+
+# Rust / maturin build
+/target
+/dist
+*.so
+*.pyd
+
+# Data downloaded by folktables
+data/
+
+# Local working material (paper experiments, results); see tag neurips2026
+outputs/
+multirun/
+batch_out/
+batch_from_cluster/
+plots/
+NeurIPS_rebuttal/
+bias_analysis/
+maxviol/
+maxviol_package_1.zip
+bias_detect_maxviol.py
+experiment_eval_maxviol.py
+bias_detect_cluster.py
+msd.py
+spsf_mio.py
+NN_fair_classifier.py
+NN_plot.py
+eval_plot.py
+train_plot.py
+plot_gap.py
+parse_eval.py
+.claude/
+paper.pdf
+*.png
+*.pdf

certifi_learn-0.2.0/Cargo.lock

@@ -0,0 +1,228 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "autocfg"
+version = "1.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
+
+[[package]]
+name = "certifi_learn"
+version = "0.2.0"
+dependencies = [
+ "numpy",
+ "pyo3",
+]
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "libc"
+version = "0.2.191"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
+
+[[package]]
+name = "matrixmultiply"
+version = "0.3.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
+dependencies = [
+ "autocfg",
+ "rawpointer",
+]
+
+[[package]]
+name = "ndarray"
+version = "0.17.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
+dependencies = [
+ "matrixmultiply",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "portable-atomic",
+ "portable-atomic-util",
+ "rawpointer",
+]
+
+[[package]]
+name = "num-complex"
+version = "0.4.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-integer"
+version = "0.1.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "numpy"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a5b15d63a5ff39e378daed0e1340d3a5964703ea9712eb09a0dc66fade996f4"
+dependencies = [
+ "libc",
+ "ndarray",
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "pyo3",
+ "pyo3-build-config",
+ "rustc-hash",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
+
+[[package]]
+name = "portable-atomic"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
+
+[[package]]
+name = "portable-atomic-util"
+version = "0.2.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
+dependencies = [
+ "portable-atomic",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "pyo3"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "700d18fa267b73b9b521fd7e13580e2f446916f176cacee1ab63fcc8191f1655"
+dependencies = [
+ "libc",
+ "once_cell",
+ "portable-atomic",
+ "pyo3-build-config",
+ "pyo3-ffi",
+ "pyo3-macros",
+]
+
+[[package]]
+name = "pyo3-build-config"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7b3fc0c4d08f6bb10e71fe39dfb9e2f59c6eb6854e22ec8092f50c69a4499adb"
+dependencies = [
+ "target-lexicon",
+]
+
+[[package]]
+name = "pyo3-ffi"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfc0b8e19df29aad7086cf977bb0c2a2f143e30567eb113e9cf72b62ca698330"
+dependencies = [
+ "libc",
+ "pyo3-build-config",
+]
+
+[[package]]
+name = "pyo3-macros"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6100e8a4b5eba53afaa5ed078364851a0b2499c553a44c31026b929049b49dc6"
+dependencies = [
+ "proc-macro2",
+ "pyo3-macros-backend",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "pyo3-macros-backend"
+version = "0.29.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6143877a16e82b5a727b7127ff4cd86858a24a28d745d72f43e6f227c7b1bdb3"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "rawpointer"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
+
+[[package]]
+name = "syn"
+version = "2.0.119"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "target-lexicon"
+version = "0.13.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"

certifi_learn-0.2.0/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "certifi_learn"
+version = "0.2.0"
+edition = "2021"
+license = "MIT"
+readme = "README.md"
+
+[lib]
+name = "_core"
+crate-type = ["cdylib"]
+
+[dependencies]
+pyo3 = { version = "0.29", features = ["extension-module", "abi3-py39"] }
+numpy = "0.29"
+
+[profile.release]
+opt-level = 3
+lto = true

certifi_learn-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jiří Němeček, Mark Kozdoba, Illia Kryvoviaz, Tomáš Pevný, Jakub Mareček
+
+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.

certifi_learn-0.2.0/PKG-INFO

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: certifi-learn
+Version: 0.2.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas
+Requires-Dist: scikit-learn
+Requires-Dist: folktables ; extra == 'examples'
+Requires-Dist: pyomo>=6.7 ; extra == 'gurobi'
+Requires-Dist: gurobipy ; extra == 'gurobi'
+Requires-Dist: pyomo>=6.7 ; extra == 'highs'
+Requires-Dist: highspy ; extra == 'highs'
+Requires-Dist: pyomo>=6.7 ; extra == 'mio'
+Requires-Dist: pytest ; extra == 'test'
+Provides-Extra: examples
+Provides-Extra: gurobi
+Provides-Extra: highs
+Provides-Extra: mio
+Provides-Extra: test
+License-File: LICENSE
+Summary: Certifiably Intersectionally Fair & Interpretable models: detection of the most biased subgroup and training of fair interpretable classifiers
+Author: Jiří Němeček
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/Epanemu/CertIFI
+
+# CertIFI: Certifiably Intersectionally Fair & Interpretable models
+
+`certifi-learn` finds the **most biased subgroup** in data or in a model's predictions,
+and trains **interpretable classifiers** (linear models and rule sets) that are
+**certifiably fair** on all intersectional subgroups, for example all combinations
+of sex, race and age group.
+
+> [!NOTE]
+> This library extends the NeurIPS 2026 paper
+> *Intersectional Fairness via Mixed-Integer Optimization* (see [Citation](#citation)).
+> Notably, it adds an exact branch-and-bound subgroup search (implemented in Rust)
+> that replaces the Mixed-Integer Optimization (MIO) search for conjunction
+> subgroups by default. The code used for the experiments in the paper is available
+> at the tag [`neurips2026`](https://github.com/Epanemu/CertIFI/tree/neurips2026).
+
+## Features
+
+- **Bias detection.** Find the subgroup with the largest violation of
+  - Subgroup Discrepancy / MSD,
+  - Statistical Parity Subgroup Fairness (SPSF),
+  - False Positive Subgroup Fairness (FPSF).
+
+  Subgroups can be
+  - **conjunctions** of protected attribute values (e.g. `SEX = Female AND RAC1P = Black`). The exact search is fast, needs no solver, and its result is proven optimal.
+  - **linear threshold functions** of the protected attributes, found by MIO.
+- **Fair training.** Linear classifiers and DNFs (rule sets), trained to optimality
+  under the constraint that *every* subgroup has bias at most γ. Fairness
+  constraints are generated lazily: only the subgroups that are actually violated
+  are added, so there's no need to enumerate the exponentially many subgroups.
+- A scikit-learn-style API that works with pandas DataFrames. Categorical
+  features are encoded automatically.
+
+## Installation
+
+```bash
+pip install "certifi-learn[gurobi]"
+```
+
+Prebuilt wheels are available for Linux, macOS and Windows (Python 3.9+). To install
+the latest version from GitHub instead, you need a [Rust toolchain](https://rustup.rs/):
+
+```bash
+pip install "certifi-learn[gurobi] @ git+https://github.com/Epanemu/CertIFI"
+```
+
+Optional dependencies (extras):
+
+| Extra | Needed for |
+|---|---|
+| `gurobi` | Training classifiers (Gurobi lazy-constraint callbacks) and MIO detection. Requires a [Gurobi license](https://www.gurobi.com/academia/academic-program-and-licenses/), free for academic use. |
+| `highs` | MIO detection with the open-source [HiGHS](https://highs.dev/) solver, an alternative to Gurobi |
+| `mio` | Pyomo only, if you bring your own solver installation |
+| `examples` | The folktables example |
+
+Bias detection on conjunction subgroups needs no extras.
+
+## Quickstart
+
+### Finding the most biased subgroup
+
+```python
+from certifi_learn import find_subgroup
+from certifi_learn.encoding import TabularEncoder
+
+# protected: DataFrame of protected attributes, y: binary labels, y_pred: model predictions
+enc = TabularEncoder(protected)                 # binarizes into literals like "SEX = Female"
+P = enc.binary(protected, negations=False)
+names = enc.binary_names(negations=False)
+
+# bias in the data: subgroup whose share differs most between positive and negative labels
+sg = find_subgroup(P, y, measure="msd")
+print(f"MSD = {sg.value:.3f}, proven optimal: {sg.optimal}")
+print(sg.describe(names))
+# e.g., on ACS Income (examples/detect_and_train.py):
+#   MSD = 0.194, proven optimal: True
+#   AGEP between [17, 24.2)
+
+# certify that no subgroup has bias above a threshold
+sg = find_subgroup(P, y, measure="msd", gamma=0.25)   # None: no subgroup has MSD > 0.25
+
+# bias of a classifier
+sg = find_subgroup(P, y_pred, measure="fpsf", y_true=y)
+
+# also allow negated literals, e.g. "NOT RAC1P = White"
+sg = find_subgroup(P, y_pred, measure="spsf", negations=True)
+
+# linear subgroups (MIO, requires a solver)
+sg = find_subgroup(P, y_pred, measure="spsf", subgroups="linear", solver="highs", time_limit=300)
+```
+
+`find_subgroup` returns a `DetectedSubgroup` with **the violation `value`** (of the
+chosen measure, on the given data), the membership `mask`, `optimal` (whether the subgroup is proven to be the most biased),
+and `describe()` / `contains(X_new)`. If you pass `gamma=...`, it returns a subgroup
+only if one violates the threshold, and `None` otherwise. That `None` certifies
+γ-fairness, unless a warning reports that the search was stopped by the time limit.
+
+### Training a fair classifier
+
+```python
+from certifi_learn import FairLinearClassifier, FairDNFClassifier
+
+clf = FairLinearClassifier(gamma=0.01, measure="fpsf", time_limit=600)
+clf.fit(X, y, X_protected)          # X may include the protected attributes
+y_pred = clf.predict(X_test)
+
+print(clf.n_cuts_)                   # number of subgroups constrained during training
+print(clf.describe_cut_subgroups())  # which ones
+
+rules = FairDNFClassifier(n_terms=3, gamma=0.01, measure="fpsf").fit(X, y, X_protected)
+print(rules.describe())
+```
+
+Common parameters:
+
+| Parameter | Values |
+|---|---|
+| `measure` | `"fpsf"`, `"fpsf_by_sd"` (FPSF constraints, with violating subgroups found by maximizing Subgroup Discrepancy on negative samples), `"spsf"`, `"msd"`, or `None` (no fairness constraint) |
+| `subgroups` | `"conjunction"` or `"linear"` |
+| `subgroup_negations` | Also allow negated literals in conjunction subgroups (e.g. `RAC1P != White`), which constrains a larger set of subgroups. Default `False`. |
+| `gamma` | Fairness threshold. Every subgroup must have bias ≤ γ on the training data. |
+| `detection_backend` | `"exact"` (default) or `"mio"`, for finding violating conjunction subgroups. Linear subgroups always use MIO. |
+| `time_limit` | Solver time limit in seconds. The best solution found so far is returned. |
+
+Model-specific parameters:
+
+| Model | Parameter | Values |
+|---|---|---|
+| `FairLinearClassifier` | `sparsity` | Weight of the penalty on the proportion of non-zero coefficients (default 0) |
+| `FairDNFClassifier` | `n_terms` | Number of terms (rules) of the DNF (default 3) |
+
+γ-fairness is guaranteed on the training data. On new data, the bias can be
+somewhat higher. Audit your model on held-out data with `find_subgroup`.
+
+## Bias measures
+
+For a classifier h and a subgroup S:
+
+| Measure | Definition |
+|---|---|
+| SPSF | P(S) · \|P(h=1) − P(h=1 \| S)\| |
+| FPSF | P(S, y=0) · \|P(h=1 \| y=0) − P(h=1 \| S, y=0)\| |
+| SD / MSD | \|P(S \| y=1) − P(S \| y=0)\|, i.e. how differently S is represented among positive and negative samples. Maximized over conjunctions, this is the [Maximum Subgroup Discrepancy](https://github.com/Epanemu/MSD). |
+
+`certifi_learn.measures` evaluates these for a given subgroup mask.
+`certifi_learn.exact` exposes the Rust search directly (`msd`, `spsf`, `fpsf`), with
+options such as sample weights, negated literals and grouped one-hot columns. See
+[`docs/subgroup_pruning_proof.tex`](docs/subgroup_pruning_proof.tex) for the
+algorithm and its proof of correctness.
+
+## Example
+
+[`examples/detect_and_train.py`](examples/detect_and_train.py) runs end to end on
+the US Census data (ACS Income, via [folktables](https://github.com/socialfoundations/folktables)).
+It finds the most biased subgroup in the data, trains an unconstrained and a fair
+linear model, and audits both on test data:
+
+```bash
+pip install "certifi-learn[gurobi,examples]"
+python examples/detect_and_train.py
+```
+
+## Development
+
+```bash
+pip install -e ".[gurobi,highs,test,examples]"   # builds the Rust extension
+pytest
+```
+
+Tests that need HiGHS or a Gurobi license are skipped if those are not available.
+
+## Citation
+
+```bibtex
+@inproceedings{nemecek2026intersectional,
+ author = {N\v{e}me\v{c}ek, Ji\v{r}\'{\i} and Kozdoba, Mark and Kryvoviaz, Illia and Pevn\'{y}, Tom\'{a}\v{s} and Mare\v{c}ek, Jakub},
+ booktitle = {Advances in Neural Information Processing Systems},
+ title = {Intersectional Fairness via Mixed-Integer Optimization},
+ volume = {39, Main Conference},
+ year = {2026}
+}
+```
+
+## License
+
+[MIT](LICENSE)
+