Release Notes
Version 2.0.0
API Reference documentation
This website now includes a dedicated API Reference section, generated from the PyXAI source docstrings. It covers the main modules and classes:
- Learning — the learning module (dataset loading, model training, instance selection)
- Explaining — the explainer module (initialisation, explanation computation)
- Builder — hand-crafting tree models
- Class references: Explainer, Learner, DecisionTree, RandomForest, and more.
Docstrings fully rewritten
All public docstrings have been rewritten with a consistent format (Parameters, Returns, Raises, Notes, Examples sections).
Updated API signatures
Several method signatures and module-level names were renamed as part of a broader refactoring to support non-tabular datasets (images, time series, etc.) stored in JSON format via the NonTabularPreprocessor class.
Imports
The Explainer entry point has been renamed Explaining:
| Old | New |
|---|---|
from pyxai import Learning, Explainer | from pyxai import Learning, Explaining |
Explainer.initialize(model, instance) | Explaining.initialize(model, instance) |
Learner.__init__()
| Old parameter | New parameter |
|---|---|
learner_type | problem_type |
Learner.evaluate()
| Old parameter | New parameter |
|---|---|
method | splitting_method |
output | model_type |
**learner_options | model_parameters={} |
test_size, n_models (positional) | moved into splitting_parameters={} |
Hyperparameters passed via model_parameters now use the same parameter names as the underlying ML library (scikit-learn, XGBoost, LightGBM). For example, model_parameters={'n_estimators': 100, 'max_depth': 4} maps directly to scikit-learn’s RandomForestClassifier(n_estimators=100, max_depth=4). There is no longer any PyXAI-specific naming for model hyperparameters.
Learner.get_instances()
| Old parameter | New parameter |
|---|---|
correct | is_correct |
Constants in the Learning module
| Old constant | New constant |
|---|---|
Learning.TRAINING | Learning.TRAIN |
Learning.MIXED | Learning.TRAIN_IN_PRIORITY |
Save and load
| Old API | New API |
|---|---|
Learning.save(model, directory) | Learning.ModelIO.save(model, directory) |
Learning.load(directory) | Learning.ModelIO.load(directory) |
XGBoost compatibility
PyXAI is now compatible with the latest versions of XGBoost (previously limited to version 1.7.3).
Recent XGBoost releases changed how the base_score parameter is stored internally. The base_score is the initial bias added to all predictions before the trees are applied. Its handling differs by task:
- Binary classification — the base score is logit-transformed before being added to the sum of tree outputs.
- Multi-class classification — the base score is added to each class score before the softmax normalisation.
- Regression — the base score is a direct additive offset.
PyXAI now correctly extracts and applies base_score in all three cases, both for prediction and for computing formal explanations via the C++ backend. This fixes incorrect predictions and explanations that occurred with XGBoost versions newer than 1.7.3.
Refactoring and internal improvements
ModelIO utility class — save, load, and import operations have been extracted from the Learner class into a dedicated ModelIO static class. This makes the API cleaner and the import workflow consistent across all supported libraries (Scikit-learn, XGBoost, LightGBM):
from pyxai import Learning
learner, model = Learning.import_models(saved_model)
Preprocessors split into two classes:
TabularPreprocessor— for standard CSV / DataFrame datasets.NonTabularPreprocessor— for non-tabular datasets (e.g. image datasets loaded from directories).
Private method naming — internal methods in data structure classes (BoostedTrees, DecisionTree, RandomForest) have been prefixed with _ to clearly distinguish the public API from implementation details.
Bug fixes:
- Fixed incorrect handling of discrete feature values in LightGBM models.
- Fixed XGBoost prediction errors introduced by the
base_scoreAPI change. - Fixed a memory issue in the Builder where
learner_informationwas incorrectly shared between instances.
Version 1.1.1
This release addresses bugs in formal explainers, as documented in the paper:
Uncovering Bugs in Formal Explainers: A Case Study with PyXAI. CoRR abs/2511.03169 (2025).
See the dedicated page for a full explanation.
Version 1.1.0
- Rectification for Decision Tree (DT) and Random Forest (RF) models dedicated to binary classification.
- Visualization displayed in a notebook or on screen, and now also for time series problems.
- Enhanced compatibility with Mac OS and Windows.
Version 1.0.0
- Regression for Boosted Trees with XGBoost or LightGBM.
- Theories (encoding knowledge about the dataset to avoid impossible explanations).
- Easier model import with automatic detection of model types.
- Graphical User Interface (GUI): displaying, loading and saving explanations.
- Support for multiple image formats for image datasets.
- Data pre-processing tools for preparing and cleaning datasets.
- Unit tests with the
unittestmodule.