Feature Request: Support for LightGBM Model Integration

[RektPunk]

I would like to request the support for LightGBM, which is a highly popular and performant gradient boosting framework, especially known for its speed and efficiency when dealing with large datasets, models within xBooster.

I am happy to contribute to the implementation if necessary. Could the maintainers please review this request and provide guidance on the best approach for integration?

[xRiskLab]

Hi @RektPunk,

Thank you for the earlier commit and for opening this feature request!

LightGBM support has indeed been an ongoing enhancement proposal for a while, so it’s great to see your interest, contributions are very welcome.

Below are some initial discovery artifacts related to potential LightGBM integration within xbooster:

1. Creation of tree charts for verification:

lgb.create_tree_digraph(lgb_model, tree_index=0, precision=6)

2. Creating dataframes with leaf scores:

dict_lgb = {
    'tree_index': 'Tree',
    'node_depth': 'Node',
    'node_index': 'ID',
    'split_feature': 'Feature',
    'decision_type': 'Sign',
    'threshold': 'Split',
    'left_child': 'Yes',
    'right_child': 'No',
    'missing_direction': 'Missing',
    'value': 'gain',
    'weight': 'Cover'
}

dict_lgb_keys = list(dict_lgb.keys())

# extract from dict first column
lgb_model.booster_.trees_to_dataframe()[dict_lgb_keys].rename(columns=dict_lgb).query('Tree == 0 and Feature.isna()')

3. Base score:

base_score = np.log(y_train.mean() / (1 - y_train.mean()))

train_data = lgb.Dataset(
    X_train.astype("category"),
    label=y_train,
    init_score=np.full(y_train.shape[0], base_score, dtype=float),
)

params = {
    "objective": "binary",
    "learning_rate": 1,
    "num_leaves": 2,  # depth=1 ≈ num_leaves=2
    "max_depth": 1,
    "seed": 42,
}

lgb_model = lgb.train(params=params, train_set=train_data, num_boost_round=1)

4. Leaf parsing:

w1_lgb = lgb_model.dump_model()["tree_info"][0]["tree_structure"]["left_child"][
    "leaf_value"
]
w2_lgb = lgb_model.dump_model()["tree_info"][0]["tree_structure"]["right_child"][
    "leaf_value"
]
print(f"w1_lgb: {w1_lgb:.3f}")
print(f"w2_lgb: {w2_lgb:.3f}")

The proposed structure is to include a new module, lgb_scorecard_constructor.py, which would handle internal LightGBM processing and be invoked within the main class.

Would you like to start a draft implementation for review? We can help guide integration details from there.

[RektPunk]

Thank you so much for explaining it so kindly! I’ll give it a try, but it might take me some time… I’m still trying to understand the existing code. By the way, are there any papers or articles related to the logic?

[xRiskLab]

🎉 Alpha Release Available: v0.2.7a1

Hi @RektPunk! I've created an alpha release with a reference implementation of the LightGBM scorecard constructor.

📦 Installation

pip install git+https://github.com/xRiskLab/xBooster.git@v0.2.7a1

📚 Key Files to Review

1. xbooster/lgb_constructor.py - LightGBM implementation (partial, with TODOs for remaining methods)
2. xbooster/xgb_constructor.py - Complete XGBoost reference to follow
3. examples/lgb_constructor_example.py - Working example showing what's implemented
4. tests/test_lgb_constructor.py - Test suite

✅ Implemented

• extract_leaf_weights(): Parse tree structure
• get_leafs(): Get leaf indices/margins

🚧 To Implement

• construct_scorecard(): Add WOE/IV calculations (see xgb_constructor.py lines 330-411)
• create_points(): Apply PDO scaling (lines 413-501)
• predict_score(): Score new data (lines 503-548)

Run the example to see it in action:

uv run python examples/lgb_constructor_example.py

Let me know if you have questions! 🚀

[xRiskLab]

Alpha Release Available! 🎉

Hi @RektPunk,

We've published an alpha release with initial LightGBM support as you requested!

Installation

pip install git+https://github.com/xRiskLab/xBooster.git@v0.2.7a2

What's Implemented (Alpha - 2/5 methods)

✅ extract_leaf_weights() - Parse LightGBM tree structure and extract leaf values
✅ get_leafs() - Get leaf indices and margins for predictions

What's Not Yet Implemented

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

Example

Check out the working example: examples/lgb_constructor_example.py

Try It Out

We'd love your feedback on this alpha implementation! Feel free to:

• Test it with your LightGBM models
• Report any issues or suggestions
• Contribute to implementing the remaining methods

Release Notes: https://github.com/xRiskLab/xBooster/releases/tag/v0.2.7a2

Thanks for the feature request! 🙌

[RektPunk]

Awesome! I'll give it a try. Really appreciate it @xRiskLab .

[RektPunk]

I will close this issue since LightGBM has now been successfully implemented and integrated into the project in #8.
A big thank you to @xRiskLab for all hard work on this!