Prepare version 0.1

.github/workflows/checks.yaml

@@ -0,0 +1,44 @@
+name: Checks
+on:
+  workflow_dispatch:
+  pull_request:
+
+# Cancel any ongoing run of this workflow on the same PR or ref
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+      - name: Run pre-commit
+        run: uv run pre-commit
+  tests:
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.11', '3.12', '3.13', '3.14']
+        os: ['ubuntu-latest', 'windows-latest', 'macos-latest']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Set up Python
+        run: uv python install
+      - name: Install Miniforge
+        uses: conda-incubator/setup-miniconda@v3
+        with:
+          auto-update-conda: true
+          miniforge-version: latest
+          conda-remove-defaults: true
+      - name: Install khiops
+        run: conda install --quiet --yes --name test khiops-core=11.0.0b.0
+      - name: Run tests
+        run: conda run --name test uv run pytest src/tests

.github/workflows/docs.yaml

@@ -0,0 +1,43 @@
+name: Docs
+on:
+  workflow_dispatch:
+
+# Cancel any ongoing run of this workflow on the same PR or ref
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# Required permissions to deploy in GH pages
+permissions:
+  id-token: write
+  pages: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v6
+      - name: Setup Python
+        run: uv python install
+      - name: Setup Just
+        uses: extractions/setup-just@v3
+      - name: Build docs
+        run: |
+          mkdir docs/_static
+          just docs
+      - name: Upload the package as an artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: ./docs/_build/html
+  publish:
+    if: github.ref_type == 'tag'
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.pre-commit-config.yaml

@@ -1,7 +1,19 @@
 repos:
-- repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.12.4
-  hooks:
-    - id: ruff-check
-      args: [ --fix ]
-    - id: ruff-format
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.12.4
+    hooks:
+      - id: ruff-check
+        args: [ --fix ]
+      - id: ruff-format
+  - repo: https://github.com/mwouts/jupytext
+    rev: v1.17.3
+    hooks:
+    - id: jupytext
+      args: [--update, --from,  py:percent, --to, notebook]
+      files: docs/quickstart.py
+  - repo: https://github.com/rhysd/actionlint
+    rev: v1.7.8
+    hooks:
+      - id: actionlint
+        name: actionlint
+

CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## [0.1] - 2025-10-17
+### Added
+- `KhalibClassifier` class
+- `calibration_error` function
+- `build_reliability_diagram` function
+
+[Unreleased]: https://github.com/yourusername/yourproject/compare/0.1...HEAD
+[1.0.0]: https://github.com/yourusername/yourproject/releases/tag/0.1

LICENSE.md

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2025 The khalib contributors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,6 +1,44 @@
-# khalib: Classifier Calibration with Khiops
-khalib is a classifier calibration method based on the [Khiops][khiops-org] supervised
-discretization algorithm (MODL).
+<!-- start-summary -->
+# khalib
+`khalib` is a classifier probability calibration package powered by the [Khiops][khiops-org] AutoML
+suite.
+
+
+## Features
+- `KhalibClassifier`: A scikit-learn estimator to calibrate classifiers with a similar interface
+  fashion as [CalibratedClassifierCV][sk-calclf].
+- `calibration_error` : A function to estimate the Estimated Calibration Error (ECE).
+- `build_reliability_diagram` : A function that builds a reliability diagram.
+
+These features are based on Khiops's non-parametric supervised histograms, so there is no need to
+specify the number and width of the bins, as they are automatically estimated from data.
+
+<!-- end-summary -->
+
+See the [documentation][khalib-docs] for more information.
+
+<!-- start-install -->
+## Installation
+
+*Note: We'll improve this installation procedure soon!*
+
+- Make sure you have installed [Khiops 11 Beta][khiops11-setup]
+- Execute
+
+```bash
+pip install https://github.com/KhiopsLab/khalib/archive/refs/tags/0.1.zip
+```
+
+<!-- end-install -->
+
+
+## Documentation
+
+See https://khiopslab.github.io/khalib/
 
 
 [khiops-org]: https://khiops.org
+[khiops11-setup]: https://khiops.org/11.0.0-b.0/setup/
+[sk-calclf]: https://scikit-learn.org/stable/modules/generated/sklearn.calibration.CalibratedClassifierCV.html
+[khalib-docs]: https://khiopslab.github.io/khalib
+

docs/api.rst

@@ -0,0 +1,32 @@
+API Reference
+=============
+
+.. currentmodule:: khalib
+
+.. autoclass:: KhalibClassifier
+   :members:
+   :inherited-members:
+   :exclude-members: set_score_request
+   :member-order: bysource
+
+
+.. autofunction:: calibration_error
+
+.. autofunction:: build_reliability_diagram
+
+.. autoclass:: Histogram
+   :members:
+   :member-order: bysource
+
+
+.. autofunction:: calibrate_binary
+
+
+
+
+.. rubric:: References
+
+.. [RCSM22] Roelofs, R., Cain, N., Shlens, J. & Mozer, M.C.. (2022).  Mitigating Bias
+   in Calibration Error Estimation . <i>Proceedings of The 25th International Conference on
+   Artificial Intelligence and Statistics</i>, in <i>Proceedings of Machine Learning Research</i>
+   151:4036-4054 Available from https://proceedings.mlr.press/v151/roelofs22a.html.

docs/conf.py

@@ -0,0 +1,54 @@
+project = "khalib"
+author = "Felipe Olmos"
+release = "0.1"
+
+extensions = [
+    "myst_nb",  # activates myst_parser as well
+    "numpydoc",
+    "sphinx.ext.autodoc",
+    "sphinx_copybutton",
+    "sphinx_paramlinks",
+    "sphinx.ext.intersphinx",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_title = f"<h6><center>{project} {release}</center></h6>"
+default_role = "obj"
+
+# Extensions configs
+
+## autosummary
+autosummary_generate = True
+autosummary_ignore_module_all = False
+
+## autodoc
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": False,
+    "private-members": False,
+    "show-inheritance": True,
+    "special-members": False,
+}
+
+
+## myst_nb
+nb_execution_allow_errors = False  # Enable this to debug notebooks
+nb_execution_show_tb: True
+
+
+## numpydoc
+numpydoc_show_class_members = False
+
+
+## intersphinx
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
+    "sklearn": ("https://scikit-learn.org/stable", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+}

docs/index.md

@@ -0,0 +1,44 @@
+```{include} ../README.md
+:start-after: <!-- start-summary -->
+:end-before:  <!-- end-summary -->
+```
+
+```{include} ../README.md
+:start-after: <!-- start-install -->
+:end-before:  <!-- end-install -->
+```
+
+## How does it work
+
+`khalib` proposes histogram-based calibration and its error estimation. Its differentiating factor
+is that uses [Khiops][khiops-org] to construct the histogram in which {math}`P(Y = 1 | S)` is
+estimated. These histograms have the following properties:
+- They balance class purity, model complexity and data fitness.
+- They are non-parametric: The optimal histogram is searched without constraint in number of bins or
+  bin width. This implies that the user doesn't need to set a number of bins nor their widths.
+
+
+[khiops-org]: https://khiops.org
+[khiops11-setup]: https://khiops.org/11.0.0-b.0/setup/
+[sk-calclf]: https://scikit-learn.org/stable/modules/generated/sklearn.calibration.CalibratedClassifierCV.html
+[khalib-docs]: https://khiopsml.github.io/khalib
+
+
+See the [Quickstart](quickstart) and [API reference](api) to learn how to use the library.
+
+
+```{toctree}
+:hidden:
+
+Home <self>
+Quickstart <quickstart>
+API Reference <api>
+```
+
+```{toctree}
+:caption: See Also
+:hidden:
+
+Khiops <https://www.khiops.org>
+```
+