Experimental/two stage

[feldlime]

Description

Two-stage model added

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Optimization

How Has This Been Tested?

Before submitting a PR, please check yourself against the following list. It would save us quite a lot of time.

• Have you read the contribution guide?
• Have you updated the relevant docstrings? We're using Numpy format, please double-check yourself
• Does your change require any new tests?
• Have you updated the changelog file?

[Copilot]

Pull request overview

This PR introduces a two-stage recommendation pipeline through the CandidateRankingModel class, which combines first-stage candidate generation with second-stage reranking using gradient boosting models.

Key Changes:

• Implements a flexible two-stage ranking architecture with support for multiple candidate generators and various reranking models
• Adds specialized support for CatBoost models through the CatBoostReranker class
• Introduces helper classes for feature collection, negative sampling, and candidate generation
• Includes comprehensive tests and a detailed tutorial notebook

Reviewed changes

Copilot reviewed 13 out of 15 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
rectools/models/ranking/candidate_ranking.py	Core implementation of the two-stage ranking model with candidate generation, feature collection, and reranking logic
rectools/models/ranking/catboost_reranker.py	Specialized reranker for CatBoost classifiers and rankers with pool preparation
rectools/models/ranking/__init__.py	Module exports with fallback imports for optional dependencies
rectools/exceptions.py	New NotFittedForStageError exception for stage-specific fitting requirements
rectools/columns.py	Added Target column constant for train/test target values
rectools/compat.py	Compatibility class for CatBoost when dependency is unavailable
tests/models/ranking/test_candidate_ranking.py	Comprehensive tests for all ranking components
tests/models/ranking/test_catboost_reranker.py	Tests for CatBoost-specific functionality
tests/models/test_serialization.py	Model serialization tests including CandidateRankingModel
tests/test_compat.py	Compatibility layer tests for CatBoostReranker
pyproject.toml	Added catboost dependency and updated black version
README.md	Documentation of new catboost extension
examples/tutorials/candidate_ranking_model_tutorial.ipynb	Detailed tutorial with multiple reranker examples
.github/workflows/test.yml	Removed trailing whitespace

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (9b3992e) to head (e02f4ff).
⚠️ Report is 124 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff             @@
##              main      #296     +/-   ##
===========================================
  Coverage   100.00%   100.00%             
===========================================
  Files           45        85     +40     
  Lines         2242      5874   +3632     
===========================================
+ Hits          2242      5874   +3632     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Copilot reviewed 15 out of 18 changed files in this pull request and generated 8 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.