v0.2.7 - Stable Release

[0.2.7] - 2025-12-04

Changed

• CatBoost Naming Standardization: Replaced LeafValue with XAddEvidence throughout CatBoost implementation
  • Standardized naming to match XGBoost and LightGBM implementations
  • Updated all CatBoost-related files: catboost_scorecard.py, catboost_wrapper.py, cb_constructor.py
  • Updated all tests and documentation

Fixed

• README Documentation: Corrected CatBoost depth requirement statement
  • Changed from "Only supports depth=1" to "depth=1 is recommended for better interpretability"
  • Code actually supports any tree depth (as long as trees are complete binary)
  • Updated code examples to use XAddEvidence instead of LeafValue

Added

• PyPI Publish Workflow: Added automated PyPI publishing workflow (.github/workflows/publish.yml)
  • Supports both release events and manual workflow dispatch
  • Uses trusted publishing (OpenID Connect) for secure PyPI uploads
  • Automatically uploads distribution files to GitHub releases

Technical Details

• All 106 tests passing
• Version updated from 0.2.7rc2 to 0.2.7 (stable release)
• LightGBM support is now stable (previously release candidate)

[0.2.7rc2] - 2025-11-23 (Release Candidate)

[0.2.7] - 2025-11-06

Changed

• Code Optimization: Simplified get_leafs() and construct_scorecard() methods in XGBScorecardConstructor (PR #6)
  • Removed special-case branching for first iteration
  • Precomputes full leaf index matrix once instead of repeated predictions
  • Eliminates redundant DataFrame concatenations
  • Net reduction of 40 lines of code while maintaining identical functionality

Added

• Comprehensive Regression Tests: Added 13 new tests to verify code refactoring produces identical outputs
• Build System Improvements: Modernized hatchling configuration
  • Simplified version management in __init__.py
  • Removed setuptools legacy configuration
  • Added explicit egg-info exclusion
• Code Quality Tools: Added prek and ty type checker configurations
• Type Stubs Directory: Created typings/ directory for custom type definitions

Fixed

• Improved .gitignore to properly exclude build artifacts and egg-info files

Technical Details

• All 95 tests passing with no regressions
• Leaf indices now stored as float32 (XGBoost's default) but represent whole numbers
• Float precision differences negligible (< 1e-6)
• Performance maintained across all operations

[0.2.6.post1] - 2025-09-30

Changed

• XGBoost Compatibility: Extended dependency range from >=2.0.0,<3.0.0 to >=2.0.0,<4.0.0
• Test Precision: Updated test_extract_model_param to handle XGBoost 3.0.5 precision differences
• CI/CD Enhancement: Added comprehensive XGBoost version matrix testing (2.1.4, 3.0.5, latest)

Added

• New Test Suite: Added test_xgboost_compatibility.py with 8 comprehensive compatibility tests
• Enhanced Workflows: Updated GitHub Actions to test across multiple XGBoost versions
• Better Error Handling: Improved Pylint configuration for virtual environment compatibility

Compatibility

• ✅ Verified compatibility with XGBoost 3.0.5
• ✅ Backward compatible with XGBoost 2.x versions
• ✅ All existing functionality remains unchanged
• ✅ No breaking changes for existing users

Technical Details

• Fixed precision differences in base_score parameter extraction between XGBoost versions
• Enhanced CI pipeline to catch compatibility issues early
• Improved development environment setup with better Pylint integration

[0.2.6] - 2025-08-30

• Added interval scorecard functionality for XGBoost models with max_depth=1
• New methods: construct_scorecard_by_intervals() and create_points_peo_pdo()
• Simplifies complex tree rules into interpretable intervals following industry standards (Siddiqi, 2017)
• Typically achieves 60-80% rule reduction while maintaining accuracy

[0.2.5] - 2025-04-19

• Minor changes in catboost_wrapper.py and cb_constructor.py to improve the scorecard generation.

[0.2.4] - 2025-04-18

• Changed the build distribution in pyproject.toml.

[0.2.3] - 2025-04-18

• Added support for CatBoost classification models and switch to uv for packaging.
• Python version requirement updated to 3.10-3.11.

[0.2.2] - 2024-05-08

• Updates in explainer.py module to improve kwargs handling and minor changes.

[0.2.1] - 2024-05-03

• Updates of dependencies

[0.2.0] - 2024-05-03

• Added tree visualization class (explainer.py)
• Updated the local explanation algorithm for models with a depth > 1 (explainer.py)
• Added a categorical preprocessor (_utils.py)

[0.1.0] - 2024-02-14

v0.2.7rc2 - LightGBM Scorecard Support (RC - Complete)

🧪 Release Candidate: LightGBM Scorecard Support (Complete)

Note: This supersedes v0.2.7rc1 which had an incomplete squash merge.

✨ What's New

• LightGBM Scorecard: Complete implementation of scorecard functionality
  • ✅ create_points() with use_base_score parameter
  • ✅ predict_score() and predict_scores()
  • ✅ Proper base score normalization
• Critical Bug Fix: Fixed leaf ID mapping (55% Gini improvement: 0.40 → 0.90)
• Full Documentation: Examples and getting-started notebook

📊 Performance

• Scorecard Gini: 0.9020
• Model Gini: 0.9021
• All 106 tests passing ✅

📦 Installation

pip install xbooster==0.2.7rc2

🤝 Feedback Welcome!

This is a release candidate - please test and report any issues.

🙏 Contributors

• @RektPunk for the initial LightGBM implementation (PR #8)

---

Full Changelog: v0.2.7a2...v0.2.7rc2

v0.2.7rc1 - LightGBM Scorecard Support (RC)

🧪 Release Candidate: LightGBM Scorecard Support

This is a release candidate for testing and feedback.

✨ What's New

• LightGBM Scorecard: Complete implementation of scorecard functionality for LightGBM models
• Critical Bug Fix: Fixed leaf ID mapping (55% Gini improvement: 0.40 → 0.90)
• Base Score Normalization: Proper handling with use_base_score parameter
• Full Documentation: Examples and getting-started notebook

📊 Performance

• Scorecard Gini: 0.9020
• Model Gini: 0.9021
• All 106 tests passing ✅

📦 Installation

pip install xbooster==0.2.7rc1

🤝 Feedback Welcome!

This is a release candidate - please test and report any issues on GitHub.

🙏 Contributors

• @RektPunk for the initial LightGBM implementation (PR #8)

---

Full Changelog: v0.2.7a2...v0.2.7rc1

v0.2.7a2 - LightGBM Alpha (Updated)

Alpha Release v0.2.7a2

This is an updated alpha release of LightGBM scorecard constructor support, including important CI and type checking fixes.

What's New in v0.2.7a2

• ✅ Fixed CI/CD with missing lightgbm dependency
• ✅ Added LightGBM type stubs for clean type checking
• ✅ Consolidated shell scripts into enhanced Makefile with colored output
• ✅ All 104 tests passing in CI

LightGBM Support (Alpha)

⚠️ Status: Alpha - 2 of 5 core methods implemented

Implemented:

• extract_leaf_weights() - Parse LightGBM tree structure
• get_leafs() - Get leaf indices and margins

Not Yet Implemented:

• construct_scorecard() - WOE/IV calculations
• create_points() - PDO scaling
• predict_score() - Inference

Installation

pip install git+https://github.com/xRiskLab/[email protected]

Example Usage

See examples/lgb_constructor_example.py for a working demonstration.

Developer Improvements

All development tasks now available via make:

• make ci-check - Run all CI checks locally (fast, no Docker)
• make act-local - Run GitHub Actions locally (with Docker)
• make help - See all available commands

Community

This alpha release is a reference implementation for issue #7 requested by @RektPunk. Community contributions welcome!

---

Full Changelog: v0.2.7a1...v0.2.7a2

v0.2.7a1 - LightGBM Support (Alpha)

🚀 Alpha Release: LightGBM Scorecard Constructor

This alpha release provides a reference implementation of LightGBM scorecard constructor as a foundation for community contribution.

✅ Implemented Methods

• extract_leaf_weights(): Parse LightGBM tree structure and extract leaf values
• get_leafs(): Get leaf indices or margins for predictions

🚧 To Be Implemented

The following methods are stubbed and ready for implementation:

• construct_scorecard(): Combine leaf weights with event statistics (WOE/IV)
• create_points(): Apply PDO (Points to Double Odds) scaling
• predict_score(): Score new data using the scorecard
• sql_query: Generate SQL for scorecard deployment

📦 Installation

pip install git+https://github.com/xRiskLab/[email protected]

📚 Resources for Contributors

1. Reference Implementation: xbooster/lgb_constructor.py
2. Working Example: examples/lgb_constructor_example.py
3. Test Suite: tests/test_lgb_constructor.py (9 tests, all passing)
4. XGBoost Pattern: xbooster/xgb_constructor.py (complete implementation to follow)

🧪 Testing

All 104 tests passing:

uv run pytest tests/test_lgb_constructor.py -v

👥 Contributors

Initial request and collaboration: @RektPunk (issue #7)

🔗 Related

• Issue: #7 - LightGBM support request
• Pattern follows: XGBScorecardConstructor methodology

v0.2.6.1 - Bug Fix Release

🐛 Bug Fixes

Fixed ValueError when XGBoost config returns bracket-wrapped parameter values (e.g., '[9.9E-2]').

Changes

• Fixed extract_model_param() to handle both standard and bracket-wrapped formats
• Added comprehensive test coverage for various parameter formats
• All 82 tests passing

Links

• Fixes #5
• Thanks to @RektPunk for reporting and suggesting the fix!

Installation

pip install xbooster==0.2.6.1

Release 0.2.6.post1: XGBoost 3.0.5 Compatibility

🚀 XGBoost 3.0.5 Compatibility Release

✨ What's New

• Full XGBoost 3.0.5 Support: Extended dependency range to >=2.0.0,<4.0.0
• Enhanced Testing: Added comprehensive XGBoost compatibility test suite
• Improved CI/CD: Multi-version testing across XGBoost 2.x and 3.x
• Better Developer Experience: Enhanced Pylint configuration

🔧 Technical Changes

• Fixed precision differences in base_score parameter extraction
• Added 8 new compatibility tests in test_xgboost_compatibility.py
• Updated GitHub Actions workflows for better version testing
• Improved virtual environment integration

✅ Compatibility

• ✅ Backward Compatible: All existing functionality preserved
• ✅ XGBoost 2.x: Fully supported
• ✅ XGBoost 3.x: Fully supported including 3.0.5
• ✅ No Breaking Changes: Seamless upgrade path

📦 Installation

pip install xbooster==0.2.6.post1

🧪 Testing

All 79 tests pass across XGBoost versions 2.1.4 and 3.0.5.

See CHANGELOG.md for detailed changes.

xBooster v0.2.6: Interval Scorecard Functionality

🚀 New Features

Interval Scorecards

This release introduces interval scorecard functionality that transforms complex XGBoost tree rules into simplified, industry-standard intervals.

New Methods:

• construct_scorecard_by_intervals(add_stats=True) - Converts tree rules into intervals like [70.8, 80.5)
• create_points_peo_pdo(peo, pdo, precision_points=0) - Adds Points at Even Odds/Points to Double the Odds

Key Benefits:

• 60-80% Rule Reduction: Simplifies complex scorecards while maintaining accuracy
• Industry Standard: Follows credit scoring best practices (Siddiqi, 2017)
• Easy Integration: Works with existing XGBoost workflows (requires max_depth=1)
• Comprehensive Testing: 10 new tests ensure reliability

Usage Example:

from xbooster.xgb_constructor import XGBScorecardConstructor

# Build standard scorecard
constructor = XGBScorecardConstructor(model, X_train, y_train)
standard_scorecard = constructor.construct_scorecard()
scorecard_with_points = constructor.create_points()

# NEW: Build interval scorecard
interval_scorecard = constructor.construct_scorecard_by_intervals(add_stats=True)

# NEW: Add PEO/PDO points
peo_pdo_scorecard = constructor.create_points_peo_pdo(peo=600, pdo=50)

📋 What's Included:

• ✅ New Methods: Interval scorecard construction and PEO/PDO points
• ✅ Example Notebook: examples/xbooster-scorecard-by-interval.ipynb
• ✅ Comprehensive Tests: Full test suite for new functionality
• ✅ Updated Documentation: README with usage examples and API reference
• ✅ PyPI Release: Available via pip install xbooster==0.2.6

🧪 Testing:

• All 71 tests pass
• Backward compatibility maintained
• No breaking changes

🔗 Installation:

pip install --upgrade xbooster

Closes #4

---

Full Changelog: v0.2.5...v0.2.6

v.0.2.5

[0.2.5] - 2025-04-19

• Minor changes in catboost_wrapper.py and cb_constructor.py to improve the scorecard generation.
• SQL functionality for CatBoost is added to future development.

v0.2.4

[0.2.4] - 2025-04-18

• Added support for CatBoost classification models and switch to uv for packaging.
• Python version requirement updated to 3.10-3.11.
• Changed the build distribution in pyproject.toml.