### Install Development Tools on Windows

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Installs Git and GitHub CLI using WinGet. Restart your terminal after installation.

```powershell
winget install Git.Git
winget install GitHub.cli
winget install prefix-dev.pixi
```

--------------------------------

### Install Development Dependencies on Windows

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Installs Git, uv, and Rustup on Windows using winget, followed by a Rust toolchain installation.

```console
> winget install Git.Git astral-sh.uv Rustlang.Rustup
> rustup install stable-msvc
```

--------------------------------

### Install All Extras

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Installs all optional development dependencies. Note: may not work on Windows.

```shell
$ uv sync --all-extras
```

--------------------------------

### Install Development Tools on Mac OS

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Installs Git, GitHub CLI, and Pixi using Homebrew. Ensure Homebrew is installed first.

```bash
brew install git gh pixi
```

--------------------------------

### Install LensKit with uv

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/install.rst

Use uv to install LensKit. uv is a fast, modern Python package installer.

```bash
uv pip install lenskit
```

--------------------------------

### Install LensKit for Python

Source: https://context7.com/lenskit/lkpy/llms.txt

Install LensKit using uv, pip, or conda. The uv package manager is recommended for faster installations.

```bash
uv pip install lenskit
```

```bash
python -m pip install lenskit
```

```bash
conda install -c conda-forge lenskit
```

--------------------------------

### Install LensKit with uv

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Install the current release of LensKit using the `uv` package manager. This is the recommended method.

```console
$ uv pip install lenskit
```

--------------------------------

### Set Up LensKit Development Environment

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Creates a virtual environment with Python 3.12 and installs development dependencies using uv.

```shell
$ uv venv -p 3.12
$ uv sync
```

--------------------------------

### Install Development Dependencies on Mac

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Installs Git, uv, and Rustup on macOS using Homebrew.

```shell
$ brew install git uv rustup
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Installs the pre-commit hooks for the 'dev-full' environment. These hooks help ensure code quality before commits.

```bash
pixi run -e dev-full pre-commit install
```

--------------------------------

### Install Development Environment with Pixi

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Installs and activates the 'dev-full' development environment using Pixi. This environment includes all necessary tools for development.

```bash
pixi shell -e dev-full
```

--------------------------------

### Install LensKit with Conda

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/install.rst

Install LensKit from the conda-forge channel using conda.

```bash
conda install -c conda-forge lenskit
```

--------------------------------

### Install Free-Threaded Python

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/parallelism.rst

Use `uv` to install a free-threaded Python 3.14 or newer for multithreaded operation.

```console
uv venv -p 3.14t
```

--------------------------------

### Install LensKit development version from GitHub

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Install the latest development version of LensKit directly from its GitHub repository using `uv pip`.

```console
$ uv pip install -U git+https://github.com/lenskit/lkpy
```

--------------------------------

### Install LensKit with pip

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Install the current release of LensKit using the classic `pip` package manager.

```console
$ python -m pip install lenskit
```

--------------------------------

### Install LensKit with pixi

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Install LensKit from conda-forge using the `pixi` package manager.

```console
$ pixi add lenskit
```

--------------------------------

### Install LensKit with pip

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/install.rst

Use pip to install LensKit in a standard Python environment, such as a virtual environment.

```bash
pip install lenskit
```

--------------------------------

### Install LensKit with Pixi

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/install.rst

Install LensKit from conda-forge using Pixi, a package and environment manager.

```bash
pixi add lenskit
```

--------------------------------

### Install LensKit with conda

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Install LensKit from conda-forge using the `conda` package manager.

```console
$ conda install -c conda-forge lenskit
```

--------------------------------

### Install Modified LensKit Locally

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Installs a locally modified version of LensKit into an experiment's environment using uv pip.

```shell
uv pip install -e /path/to/lkpy
```

--------------------------------

### Constructing a Standard Recommendation Pipeline

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/pipeline.rst

Use PipelineBuilder to define inputs, components, and connections for a standard recommendation pipeline. This example shows how to set up user history lookup, candidate selection, scoring, and ranking.

```python
pipe = PipelineBuilder()
# define an input parameter for the user ID (the 'query')
query = pipe.create_input('query', ID)
# allow candidate items to be optionally specified
items = pipe.create_input('items', ItemList, None)
# look up a user's history in the training data
history = pipe.add_component('history-lookup', LookupTrainingHistory, query=query)
# find candidates from the training data
default_candidates = pipe.add_component(
    'candidate-selector',
    TrainingItemsCandidateSelector,
    query=history,
)
# if the client provided items as a pipeline input, use those; otherwise
# use the candidate selector we just configured.
candidates = pipe.use_first_of('candidates', items, default_candidates)
# score the candidate items using the specified scorer
score = pipe.add_component('scorer', scorer, query=query, items=candidates)
# rank the items by score
recommend = pipe.add_component('ranker', TopNRanker, {'n': 50}, items=score)
pipe.alias('recommender', recommend)
pipe.default_component('recommender')
pipe = pipe.build()
```

--------------------------------

### Install TBB with Conda

Source: https://github.com/lenskit/lkpy/wiki/PerformanceTips

Install Intel's Thread Building Blocks (TBB) using Conda. This is a prerequisite for optimizing LensKit and MKL threading.

```bash
conda install tbb
```

--------------------------------

### Clone Repository and Set Up Upstream

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Clones your forked repository and sets up the main LensKit repository as an upstream remote. This is part of the initial setup for development.

```bash
gh repo clone myuser/lkpy
```

--------------------------------

### Configure uv for LensKit development version

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Configure `uv` to use the LensKit development PyPI index by adding it to `pyproject.toml`. This allows installation of development versions.

```toml
[[tool.uv.index]]
name = "lenskit"
url = "https://pypi.lenskit.org/lenskit-dev/"
```

--------------------------------

### Batch Recommendation Generation

Source: https://context7.com/lenskit/lkpy/llms.txt

Generates recommendations for multiple users in parallel using `lenskit.batch.recommend`. Shows how to train a pipeline and then use the batch function to get recommendations for a set of test users.

```python
from lenskit.pipeline import topn_pipeline
from lenskit.knn import ItemKNNScorer
from lenskit.splitting import sample_users, SampleFrac
from lenskit.data.movielens import load_movielens
import lenskit.batch as lkb

dataset = load_movielens("data/ml-latest-small")
split = sample_users(dataset, size=100, method=SampleFrac(0.2), rng=0)

pipe = topn_pipeline(ItemKNNScorer(max_nbrs=20), n=10)
pipe.train(split.train)

# Batch recommend for all 100 test users
recs = lkb.recommend(pipe, split.test, n=10, n_jobs=4)
print(type(recs))
# <class 'lenskit.data._collection._list.ItemListCollection'>
print(len(recs))
# 100

# Get recommendations for a specific user
user_recs = recs.lookup(42)
print(user_recs.ids()[:5])
# [318, 593, 527, 2571, 858]
```

--------------------------------

### Configure uv for CPU-only PyTorch installation

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Configure `uv` to use a specific index for CPU-only PyTorch installations. This helps manage package conflicts and ensures only PyTorch and its direct dependencies are used.

```toml
[[tool.uv.index]]
name = "torch-cpu"
url = "https://pypi.lenskit.org/torch/cpu/"
```

--------------------------------

### LensKit CLI: Environment Check

Source: https://context7.com/lenskit/lkpy/llms.txt

Run the LensKit doctor to check the environment for potential issues and ensure all dependencies are correctly installed.

```bash
lenskit doctor
```

--------------------------------

### Invoke Recommender Operation

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/queries.rst

Use the `recommend` operation function to get top-N recommendations for a user. It requires a pipeline and a query input.

```python
rec_list = recommend(pipe, user_id, n=20)
```

--------------------------------

### Get Recommendations with LensKit Pipeline

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/migrating.rst

Use the `recommend` function from `lenskit` to invoke a pipeline and obtain recommendations. The user identifier is now passed as the `query` argument.

```python
from lenskit import recommend
recs = recommend(pipe, user_id)
```

--------------------------------

### Train Pipeline with Custom Training Options

Source: https://context7.com/lenskit/lkpy/llms.txt

Train a pipeline on a dataset using `Pipeline.train`, which iterates over `Trainable` components. Respect `TrainingOptions` such as `retrain`, `device` (CPU/CUDA), and `rng` for reproducible training. This example uses an ImplicitMFScorer.

```python
from lenskit.pipeline import topn_pipeline
from lenskit.als import ImplicitMFScorer, ImplicitMFConfig
from lenskit.training import TrainingOptions
from lenskit.data.movielens import load_movielens

dataset = load_movielens("data/ml-latest-small")
pipe = topn_pipeline(ImplicitMFScorer, ImplicitMFConfig(features=64, epochs=15))

opts = TrainingOptions(
    retrain=True,
    device="cpu",       # or "cuda" for GPU training
    rng=42,
)
pipe.train(dataset, options=opts)

from lenskit import recommend
recs = recommend(pipe, query=12, n=10)
print(recs.ids())
```

--------------------------------

### Load MovieLens Dataset

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/data/index.rst

Loads the MovieLens dataset from a specified directory. This is the primary way to get started with data in LensKit.

```python
from lenskit.data import load_movielens
mlds = load_movielens('data/ml-latest-small')
mlds.item_count
```

--------------------------------

### Configure and train a recommendation model for batch runs

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/batch.rst

Sets up a PopScorer model and a top-N recommendation pipeline, then trains it on the sampled training data.

```python
model = PopScorer()
pop_pipe = topn_pipeline(model, n=20)
pop_pipe.train(split.train)
```

--------------------------------

### Instantiate LinearBlendScorer with Configuration Class

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/implementing.rst

Shows how to instantiate the LinearBlendScorer component by providing a specific configuration object.

```python
>>> LinearBlendScorer(LinearBlendConfig(mix_weight=0.2))
<LinearBlendScorer {
    "mix_weight": 0.2
}>
```

--------------------------------

### Instantiate LinearBlendScorer with Defaults

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/implementing.rst

Demonstrates instantiating the LinearBlendScorer component using its default configuration.

```python
>>> LinearBlendScorer()
<LinearBlendScorer {
    "mix_weight": 0.5
}>
```

--------------------------------

### Instantiate LinearBlendScorer with Constructor Parameters

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/implementing.rst

Illustrates instantiating the LinearBlendScorer component by directly passing configuration parameters to the constructor.

```python
>>> LinearBlendScorer(mix_weight=0.7)
<LinearBlendScorer {
    "mix_weight": 0.7
}>
```

--------------------------------

### Create Top-N Recommendation Pipelines

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Creates recommendation pipelines for the defined models, configured to produce top-N recommendations.

```python
pipe_ii = topn_pipeline(model_ii)
pipe_als = topn_pipeline(model_als)
```

--------------------------------

### Update Anaconda and Install LensKit

Source: https://github.com/lenskit/lkpy/wiki/LensKitTutorial

Run these commands in an Anaconda prompt to update your Anaconda distribution and install the LensKit package.

```bash
conda update --all
conda install -c lenskit lenskit
```

--------------------------------

### Create Top-N Pipeline with ImplicitMFScorer

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/pipeline.rst

Constructs a standard top-N recommendation pipeline using implicit-feedback matrix factorization. This is the simplest way to create a pipeline for top-N recommendations.

```python
als = ImplicitMFScorer(50)
pipe = topn_pipeline(als)
```

--------------------------------

### Set Up Recommendation Metrics Collector

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Initializes a MeasurementCollector and adds NDCG, RBP, and RecipRank metrics to it for evaluating recommendation quality.

```python
mc = MeasurementCollector()
mc.add_metric(NDCG(n=100))
mc.add_metric(RBP(n=100))
mc.add_metric(RecipRank(n=100))
```

--------------------------------

### Run Pipeline for Recommendations

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/pipeline.rst

Executes a configured pipeline to generate recommendations for a given user. This method is used after a pipeline has been constructed.

```python
user_recs = pipe.run('recommender', query=user_id)
```

--------------------------------

### Configure uv for CUDA 12.8 PyTorch installation

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Configure `uv` to use a specific index for PyTorch installations with CUDA 12.8 support. This index provides filtered PyTorch packages and fallbacks for different platforms.

```toml
[[tool.uv.index]]
name = "torch-gpu"
url = "https://pypi.lenskit.org/torch/cu128/"
```

--------------------------------

### LensKit CLI: Fetch Dataset

Source: https://context7.com/lenskit/lkpy/llms.txt

Download a standard dataset provided by LensKit to a specified output directory. Simplifies data acquisition for benchmarking.

```bash
lenskit data fetch --dataset ml-latest-small --output data/
```

--------------------------------

### Run Pipeline using Convenience Function

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/pipeline.rst

A convenience function to run a pipeline and generate recommendations. This is an alternative to calling the `run` method directly on the pipeline object.

```python
from lenskit import recommend
user_recs = recommend(pipe, user_id)
```

--------------------------------

### LensKit CLI: Describe Dataset

Source: https://context7.com/lenskit/lkpy/llms.txt

Get a summary description of a dataset, including its size and characteristics. Useful for understanding data before processing.

```bash
lenskit data describe data/ml-latest-small/
```

--------------------------------

### Define Recommender Models

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Initializes two different recommender models: ItemKNNScorer and BiasedMFScorer.

```python
model_ii = ItemKNNScorer(k=20)
model_als = BiasedMFScorer(features=50)
```

--------------------------------

### Import necessary modules for batch recommendation

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/batch.rst

Imports required for setting up and running a batch recommendation experiment.

```python
from lenskit.basic import PopScorer
from lenskit.pipeline import topn_pipeline
from lenskit.batch import recommend
from lenskit.data import load_movielens
from lenskit.splitting import sample_users, SampleN
from lenskit.metrics import MeasurementCollector, RBP
```

--------------------------------

### Initialize Data Structures for Evaluation

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Sets up ItemListCollection objects to store test data and recommendations from different models during cross-validation.

```python
# test data is organized by user
all_test = ItemListCollection(UserIDKey)
# recommendations will be organized by model and user ID
# create a new empty list for each recommender
als_recs = ItemListCollection(UserIDKey)
iknn_recs = ItemListCollection(UserIDKey)
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Creates a new branch for your feature development, starting from the updated 'main' branch. Use a descriptive name for the branch.

```bash
git checkout -b feature/my-new-thing
```

--------------------------------

### LensKit CLI: Hyperparameter Tuning

Source: https://context7.com/lenskit/lkpy/llms.txt

Run hyperparameter tuning for recommendation models based on a TOML configuration. Requires specifying the pipeline, data, and an output directory for results.

```bash
lenskit tune pipelines/bias-search.toml \
    --data data/ml-latest-small/ --output tuning-results/
```

--------------------------------

### Add LensKit as a dependency with uv

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/install.rst

Add LensKit as a dependency to your project's pyproject.toml and virtual environment using uv.

```bash
uv add lenskit
```

--------------------------------

### LensKit CLI: Generate Recommendations

Source: https://context7.com/lenskit/lkpy/llms.txt

Generate recommendations for a specified list of users using a pre-trained pipeline. Output is typically saved in a structured format like Parquet.

```bash
lenskit recommend --pipeline trained-model/ --users users.csv --n 10 --output recs.parquet
```

--------------------------------

### Get Item Statistics

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/data/index.rst

Computes and returns statistics for each item in the dataset, such as record count, user count, and time ranges. Provides insights into item engagement.

```python
mlds.item_stats()
```

--------------------------------

### Train ImplicitMFScorer for Implicit Feedback

Source: https://context7.com/lenskit/lkpy/llms.txt

Trains an ImplicitMFScorer model for implicit feedback using ALS. This example shows how to build an implicit feedback dataset from interaction data and train the model.

```python
from lenskit.als import ImplicitMFScorer, ImplicitMFConfig
from lenskit.pipeline import topn_pipeline
from lenskit.data import DatasetBuilder
import pandas as pd

# Build implicit-feedback dataset (no ratings, just interactions)
plays = pd.DataFrame({
    "user_id": [1, 1, 2, 2, 3, 3, 3],
    "item_id": [10, 20, 10, 30, 20, 30, 40],
})
dsb = DatasetBuilder("plays")
dsb.add_interactions("play", plays, entities=["user", "item"], missing="insert", default=True)
dataset = dsb.build()

scorer = ImplicitMFScorer(ImplicitMFConfig(features=64, epochs=15, reg=0.1))
pipe = topn_pipeline(scorer, n=5)
pipe.train(dataset)

from lenskit import recommend
recs = recommend(pipe, query=1, n=5)
print(recs.ids())
# [30, 40, 20, ...]
```

--------------------------------

### Implement a Linear Blend Scorer Component

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/implementing.rst

Example of a custom component that computes a linear weighted blend of scores from two other components. This component can be instantiated with default or custom configuration parameters.

```python
from lenskit.data import ItemList, RecQuery
from lenskit.sharing import shareable
from lenskit.components import Scorer, Component
from dataclasses import dataclass

@dataclass
class LinearBlendConfig:
    mix_weight: float = 0.5

@shareable
class LinearBlendScorer(Scorer, Component[LinearBlendConfig]):
    def __init__(self, config: LinearBlendConfig | None = None, *, mix_weight: float | None = None):
        if config is None:
            config = LinearBlendConfig()
        if mix_weight is not None:
            config = LinearBlendConfig(mix_weight=mix_weight)
        self.config = config

    def score(self, rec_query: RecQuery, items: ItemList, *, context=None) -> ItemList:
        # In a real component, you'd get scores from other components
        # For this example, we'll just use dummy scores
        scores1 = np.full(len(items), 0.5)
        scores2 = np.full(len(items), 0.8)

        mixed_scores = (
            self.config.mix_weight * scores1
            + (1.0 - self.config.mix_weight) * scores2
        )

        return ItemList(items, scores=mixed_scores)

    def __str__(self):
        return f"<LinearBlendScorer {{
    \"mix_weight\": {self.config.mix_weight}
}}">"
```

--------------------------------

### Import Project Root Helper

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Imports a utility to help locate project root directories, useful for accessing data files.

```python
from pyprojroot.here import here
```

--------------------------------

### Update Main Branch and Push

Source: https://github.com/lenskit/lkpy/wiki/DevWorkflow

Updates your local 'main' branch by pulling changes from both your fork's 'main' and the upstream 'main' repository, then pushes the updated branch. This should be done before starting new work.

```bash
git checkout main
git pull
git pull upstream main
git push
```

--------------------------------

### Set MKL Threading Layer to TBB

Source: https://github.com/lenskit/lkpy/wiki/PerformanceTips

Configure the MKL (Math Kernel Library) to use TBB for threading. This ensures consistent threading behavior with LensKit when TBB is installed. Set this in your shell scripts or at the beginning of your Python script.

```bash
export MKL_THREADING_LAYER=tbb
```

```python
import os
os.environ['MKL_THREADING_LAYER'] = 'tbb'
```

--------------------------------

### Activate Virtual Environment

Source: https://github.com/lenskit/lkpy/blob/main/README.md

Activates the created virtual environment to make development tools available.

```shell
$ . ./.venv/bin/activate
```

--------------------------------

### Load and split MovieLens data for batch processing

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/batch.rst

Loads the MovieLens 100k dataset and samples users for training and testing.

```python
data = load_movielens('data/ml-100k.zip')
split = sample_users(data, 150, SampleN(5, rng=1024), rng=42)
```

--------------------------------

### Import LensKit Components

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/GettingStarted.ipynb

Imports necessary components from the LensKit library for building and evaluating recommendation systems.

```python
from lenskit.als import BiasedMFScorer
from lenskit.batch import recommend
from lenskit.data import ItemListCollection, UserIDKey, load_movielens
from lenskit.knn import ItemKNNScorer
from lenskit.metrics import NDCG, RBP, MeasurementCollector, RecipRank
from lenskit.pipeline import topn_pipeline
from lenskit.splitting import SampleFrac, crossfold_users
```

--------------------------------

### Create Pipeline with RecPipelineBuilder

Source: https://github.com/lenskit/lkpy/blob/main/docs/guide/pipeline.rst

Uses `RecPipelineBuilder` to create a recommendation pipeline with more flexibility than `topn_pipeline`. This allows for standard pipeline designs to be configured.

```python
als = ImplicitMFScorer(50)
builder = RecPipelineBuilder()
builder.scorer(als)
pipe = builder.build('ALS')
```