### GPU Setup for Implicit

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Set up your environment for GPU acceleration by installing the CUDA toolkit and the RMM library. Verify GPU support by running a Python command.

```bash
# Install CUDA toolkit 13
# Download from https://developer.nvidia.com/cuda-downloads

# Install RMM for GPU support
pip install rmm-cu13

# Verify GPU support
python -c "import implicit; print(implicit.gpu.HAS_CUDA)"
```

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

### Usage Example for CosineRecommender

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Demonstrates how to create a user-item matrix, train a CosineRecommender, and get recommendations or similar items.

```python
import implicit
import numpy as np
from scipy.sparse import csr_matrix

# Create user-item interaction matrix
data = np.array([1, 1, 1, 1, 1])
row = np.array([0, 0, 1, 1, 2])
col = np.array([0, 2, 1, 3, 2])
user_items = csr_matrix((data, (row, col)), shape=(3, 4))

# Initialize and train Cosine recommender
model = implicit.nearest_neighbours.CosineRecommender(K=5)
model.fit(user_items, show_progress=True)

# Get recommendations
item_ids, scores = model.recommend(0, user_items[0], N=3)
print(f"Recommended: {item_ids}, Scores: {scores}")

# Find similar items
similar_ids, similar_scores = model.similar_items(itemid=1, N=2)
```

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

### Installation

Source: https://github.com/benfred/implicit/blob/main/_autodocs/README.md

Instructions for installing the implicit library, including optional GPU support.

```APIDOC
## Installation

### Standard Installation
```bash
pip install implicit
```

### GPU Support (Optional)
```bash
pip install rmm-cu13
```
```

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

### Example: Train Model with MovieLens Data

Source: https://github.com/benfred/implicit/blob/main/_autodocs/08-datasets.md

Demonstrates loading the 100K MovieLens variant, transposing the ratings matrix for typical layout, training an ALS model, and getting movie recommendations. Ensure you have `scipy.sparse` imported.

```python
import implicit
from scipy.sparse import csr_matrix

# Load 100K variant (smallest, fastest)
movies, ratings = implicit.datasets.movielens.get_movielens("100k")

# Ratings matrix is (movies × users), transpose for typical layout
ratings_users_items = ratings.T.tocsr()

# Train model
model = implicit.als.AlternatingLeastSquares(factors=50)
model.fit(ratings_users_items)

# Get recommendations
recommendations = model.recommend(0, ratings_users_items[0], N=10)

# Get movie titles
print(f"Recommended movies: {movies[recommendations[0]]}")
```

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

### Install Python Files

Source: https://github.com/benfred/implicit/blob/main/implicit/CMakeLists.txt

Finds all .py files in the current directory and installs them to the 'implicit' destination.

```cmake
FILE(GLOB python_files *.py)
install(FILES ${python_files} DESTINATION implicit)
```

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

### Install Implicit with Pip

Source: https://github.com/benfred/implicit/blob/main/README.md

Install the Implicit library using pip. This command will use prebuilt binary wheels for common platforms.

```bash
pip install implicit
```

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

### BPR Model Training and Recommendation Example

Source: https://github.com/benfred/implicit/blob/main/_autodocs/02-bayesian-personalized-ranking.md

Example demonstrating how to initialize, train, and use the BPR model for generating recommendations and finding similar items. Requires SciPy sparse matrix for user-item interactions.

```python
import implicit
import numpy as np
from scipy.sparse import csr_matrix

# Create user-item interaction matrix
data = np.array([1, 1, 1, 1, 1])
row = np.array([0, 0, 1, 1, 2])
col = np.array([0, 2, 1, 3, 2])
user_items = csr_matrix((data, (row, col)), shape=(3, 4))

# Initialize BPR model
model = implicit.bpr.BayesianPersonalizedRanking(
    factors=50,
    learning_rate=0.01,
    iterations=50,
    verify_negative_samples=True
)

# Train the model
model.fit(user_items, show_progress=True)

# Get recommendations
item_ids, scores = model.recommend(
    userid=0,
    user_items=user_items[0],
    N=3
)

# Find similar items
similar_ids, similar_scores = model.similar_items(itemid=1, N=2)
```

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

### Install Python Files

Source: https://github.com/benfred/implicit/blob/main/implicit/cpu/CMakeLists.txt

Finds all Python files in the current directory and installs them to the implicit/cpu destination.

```cmake
FILE(GLOB cpu_python_files *.py)
install(FILES ${cpu_python_files} DESTINATION implicit/cpu)
```

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

### Install Implicit Library

Source: https://github.com/benfred/implicit/blob/main/_autodocs/README.md

Install the implicit library using pip. Optional GPU support can be installed with rmm-cu13.

```bash
pip install implicit
# GPU support (optional): pip install rmm-cu13
```

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

### Install NMSLIB

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Installs the NMSLIB library, which requires compilation. This is a prerequisite for using the NMSLibModel.

```bash
pip install nmslib
```

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

### Install Implicit Library

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Install the Implicit library using pip. Choose the CPU-only version or the CPU+GPU version for Linux. GPU support may require additional prerequisites.

```bash
# CPU only
pip install implicit

# CPU + GPU (Linux)
pip install implicit

# With GPU support prerequisites
pip install rmm-cu13
```

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

### Usage Example for TFIDFRecommender

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Demonstrates how to train a TFIDFRecommender and obtain recommendations or similar items.

```python
model = implicit.nearest_neighbours.TFIDFRecommender(K=10)
model.fit(user_items)

item_ids, scores = model.recommend(0, user_items[0], N=5)
similar_ids, similar_scores = model.similar_items(2, N=3)
```

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

### BM25Recommender Usage Example

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Shows how to instantiate, fit, and use the BM25Recommender for generating recommendations and finding similar items. Requires user_items data for fitting.

```python
model = implicit.nearest_neighbours.BM25Recommender(K=15, K1=2.0, B=0.5)
model.fit(user_items)

item_ids, scores = model.recommend(0, user_items[0], N=5)
similar_ids, similar_scores = model.similar_items(1, N=3)
```

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

### Install GPU Python Files

Source: https://github.com/benfred/implicit/blob/main/implicit/gpu/CMakeLists.txt

Finds all Python files in the current directory and installs them to the 'implicit/gpu' destination.

```cmake
FILE(GLOB gpu_python_files *.py)
install(FILES ${gpu_python_files} DESTINATION implicit/gpu)
```

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

### Train ALS Model and Get Recommendations

Source: https://github.com/benfred/implicit/blob/main/_autodocs/08-datasets.md

Demonstrates how to train an Alternating Least Squares (ALS) model using the loaded LastFM play counts and then retrieve recommendations for a specific user. Ensure the `implicit` library is installed.

```python
import implicit

artistids, userids, plays = implicit.datasets.lastfm.get_lastfm()

# Train a model
model = implicit.als.AlternatingLeastSquares(factors=50, iterations=15)
model.fit(plays, show_progress=True)

# Get recommendations for user 0
recommendations = model.recommend(0, plays[0], N=10)
```

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

### Install CUDA Library

Source: https://github.com/benfred/implicit/blob/main/implicit/gpu/CMakeLists.txt

Installs the compiled '_cuda' library target to the 'implicit/gpu' directory within the installation prefix.

```cmake
install(TARGETS _cuda LIBRARY DESTINATION implicit/gpu)
```

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

### Install Implicit Library

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Install the implicit library using pip. Ensure BLAS multithreading is disabled for optimal performance by setting OPENBLAS_NUM_THREADS and MKL_NUM_THREADS to 1.

```bash
# Install implicit
pip install implicit

# Disable BLAS multithreading (CRITICAL)
export OPENBLAS_NUM_THREADS=1
export MKL_NUM_THREADS=1

# Optional: Use NumPy linked to Intel MKL for better performance
# conda install -c conda-forge numpy scipy openblas
```

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

### Transpile and Build TopK Module

Source: https://github.com/benfred/implicit/blob/main/implicit/cpu/CMakeLists.txt

Transpiles the TopK Cython file to CXX, creates a Python module, and installs it.

```cmake
cython_transpile(topk.pyx LANGUAGE CXX)
python_add_library(topk MODULE topk.cxx)
install(TARGETS topk LIBRARY DESTINATION implicit/cpu)
```

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

### Import Pattern

Source: https://github.com/benfred/implicit/blob/main/_autodocs/README.md

Demonstrates the standard import pattern and initialization for the implicit library, using ALS as an example.

```APIDOC
## Import Pattern

```python
import implicit

# Initialize the AlternatingLeastSquares model
model = implicit.als.AlternatingLeastSquares(factors=50)

# Fit the model to user-item data
model.fit(user_items)

# Get recommendations for a user
recommendations = model.recommend(userid, user_items[userid], N=10)
```
```

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

### Explore Similar Items and Users

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Provides examples for finding items similar to a given item (content discovery) and users similar to a reference user (useful for cold-start scenarios or community building).

```python
# Find related items (content discovery)
similar_ids, scores = model.similar_items(seed_item_id, N=20)

# Find similar users (for cold-start or community building)
similar_users, scores = model.similar_users(reference_user_id, N=10)
```

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

### Install Implicit with Conda (CPU+GPU)

Source: https://github.com/benfred/implicit/blob/main/README.md

Install the CPU and GPU enabled version of the Implicit library using conda from the conda-forge channel. Ensure CUDA toolkit and RMM are installed.

```bash
conda install -c conda-forge implicit implicit-proc=*=gpu
```

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

### ALS Model Usage Example

Source: https://github.com/benfred/implicit/blob/main/_autodocs/01-alternating-least-squares.md

Example demonstrating how to initialize, fit, and use the Alternating Least Squares model for generating recommendations and finding similar items. Requires scipy.sparse for user-item matrix representation.

```python
import implicit
import numpy as np
from scipy.sparse import csr_matrix

# Create sample user-item interaction matrix (users × items)
# Values represent confidence weights (e.g., play counts)
data = np.array([1, 2, 3, 4, 5])
row = np.array([0, 0, 1, 1, 2])
col = np.array([0, 2, 1, 3, 2])
user_items = csr_matrix((data, (row, col)), shape=(3, 4))

# Initialize model
model = implicit.als.AlternatingLeastSquares(
    factors=50,
    regularization=0.01,
    iterations=20
)

# Fit the model
model.fit(user_items)

# Get recommendations for user 0
item_ids, scores = model.recommend(
    userid=0,
    user_items=user_items[0],
    N=5
)
print(f"Recommended items: {item_ids}")
print(f"Scores: {scores}")

# Find similar items to item 2
similar_ids, similar_scores = model.similar_items(itemid=2, N=3)
print(f"Similar items: {similar_ids}")
```

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

### Install Implicit with Conda (CPU)

Source: https://github.com/benfred/implicit/blob/main/README.md

Install the CPU-only version of the Implicit library using conda from the conda-forge channel.

```bash
conda install -c conda-forge implicit
```

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

### Transpile and Build BPR Module

Source: https://github.com/benfred/implicit/blob/main/implicit/cpu/CMakeLists.txt

Transpiles the BPR Cython file to CXX, creates a Python module, and installs it.

```cmake
cython_transpile(bpr.pyx LANGUAGE CXX)
python_add_library(bpr MODULE bpr.cxx)
install(TARGETS bpr LIBRARY DESTINATION implicit/cpu)
```

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

### Transpile and Build LMF Module

Source: https://github.com/benfred/implicit/blob/main/implicit/cpu/CMakeLists.txt

Transpiles the LMF Cython file to CXX, creates a Python module, and installs it.

```cmake
cython_transpile(lmf.pyx LANGUAGE CXX)
python_add_library(lmf MODULE lmf.cxx)
install(TARGETS lmf LIBRARY DESTINATION implicit/cpu)
```

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

### Common Dataset Usage Pattern

Source: https://github.com/benfred/implicit/blob/main/_autodocs/08-datasets.md

Demonstrates a typical workflow for using datasets with Implicit models, including loading, splitting, training, and making predictions. Ensure necessary libraries like numpy, scipy, and scikit-learn are installed.

```python
import implicit
import numpy as np
from scipy.sparse import csr_matrix

# 1. Load dataset
movies, ratings = implicit.datasets.movielens.get_movielens("100k")
ratings = ratings.T.tocsr()  # Transpose to users × items

# 2. Optionally split into train/test
from sklearn.model_selection import train_test_split

all_interactions = ratings.copy()
train, test = train_test_split(all_interactions, test_size=0.2, random_state=42)

# 3. Train model
model = implicit.als.AlternatingLeastSquares(
    factors=50,
    regularization=0.01,
    iterations=15
)
model.fit(ratings, show_progress=True)

# 4. Evaluate on test set (example)
ndcg_scores = []
for userid in range(test.shape[0]):
    if test[userid].nnz > 0:
        recommendations, scores = model.recommend(
            userid,
            all_interactions[userid],
            N=10
        )
        # Calculate NDCG or other metrics
        
# 5. Make predictions for new users
new_user_interactions = ratings[0]  # or custom vector
recommendations, scores = model.recommend(
    userid=0,
    user_items=new_user_interactions,
    N=10
)

print(f"Recommended movie indices: {recommendations}")
```

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

### AnnoyAlternatingLeastSquares Usage Example

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Demonstrates creating an ALS model with an Annoy ANN index, fitting the model, and performing approximate recommendations and similar item lookups.

```python
import implicit.approximate_als

# Create ALS model with Annoy ANN index
model = implicit.approximate_als.AnnoyAlternatingLeastSquares(
    factors=50,
    regularization=0.01,
    iterations=15,
    n_trees=50,
    search_k=-1
)

# Fit the model (includes building Annoy indexes)
model.fit(user_items)

# Recommendation and similar_items now use approximate search
item_ids, scores = model.recommend(0, user_items[0], N=10)
similar_ids, similar_scores = model.similar_items(5, N=10)
```

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

### Benchmark Model Fit and Recommendation Times

Source: https://github.com/benfred/implicit/blob/main/_autodocs/11-configuration-and-advanced.md

Measure the time taken to fit a model and generate recommendations. This helps identify performance bottlenecks. Ensure you have the 'implicit' and 'numpy' libraries installed.

```python
import time
import numpy as np

def benchmark_model(model, user_items, n_runs=5):
    """Measure fit and recommend time"""
    
    # Benchmark fitting
    fit_times = []
    for _ in range(n_runs):
        model_copy = model.__class__(**model.__dict__)
        start = time.time()
        model_copy.fit(user_items, show_progress=False)
        fit_times.append(time.time() - start)
    
    # Benchmark recommendations
    rec_times = []
    for userid in range(100):
        start = time.time()
        model.recommend(userid, user_items[userid], N=10)
        rec_times.append(time.time() - start)
    
    print(f"Fit time: {np.mean(fit_times):.2f}s ± {np.std(fit_times):.2f}s")
    print(f"Recommend time: {np.mean(rec_times)*1000:.2f}ms ± {np.std(rec_times)*1000:.2f}ms")

# Usage
model = implicit.als.AlternatingLeastSquares(factors=50)
benchmark_model(model, user_items)
```

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

### Download Specific Dataset File

Source: https://github.com/benfred/implicit/blob/main/_autodocs/07-utility-functions.md

Example of downloading a specific dataset file, such as lastfm_360k.hdf5, to a local path within the implicit datasets directory. Ensures the file is available for use.

```python
from implicit.datasets._download import download_file

download_file(
    "https://github.com/benfred/recommender_data/releases/download/v1.0/lastfm_360k.hdf5",
    "~/implicit_datasets/lastfm_360k.hdf5"
)
```

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

### Transpile and Build ALS Module

Source: https://github.com/benfred/implicit/blob/main/implicit/cpu/CMakeLists.txt

Transpiles the ALS Cython file to CXX, creates a Python module, and installs it.

```cmake
cython_transpile(_als.pyx LANGUAGE CXX)
python_add_library(_als MODULE _als.cxx)
install(TARGETS _als LIBRARY DESTINATION implicit/cpu)
```

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

### Transpile and Create Python Library (evaluation)

Source: https://github.com/benfred/implicit/blob/main/implicit/CMakeLists.txt

Transpiles a .pyx file to C++ using cython_transpile and then creates a Python module library. The library is installed to the 'implicit' destination.

```cmake
cython_transpile(evaluation.pyx LANGUAGE CXX)
python_add_library(evaluation MODULE evaluation.cxx)
install(TARGETS evaluation LIBRARY DESTINATION implicit)
```

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

### Transpile and Create Python Library (_nearest_neighbours)

Source: https://github.com/benfred/implicit/blob/main/implicit/CMakeLists.txt

Transpiles a .pyx file to C++ using cython_transpile and then creates a Python module library. The library is installed to the 'implicit' destination.

```cmake
cython_transpile(_nearest_neighbours.pyx LANGUAGE CXX)
python_add_library(_nearest_neighbours MODULE _nearest_neighbours.cxx)
install(TARGETS _nearest_neighbours LIBRARY DESTINATION implicit)
```

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

### AnnoyAlternatingLeastSquares

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Combines ALS with Spotify's Annoy library. Annoy is pure Python with precompiled binary wheels, easiest to install.

```APIDOC
## AnnoyAlternatingLeastSquares

### Description
Combines ALS with Spotify's Annoy library. Annoy is pure Python with precompiled binary wheels, easiest to install.

### Parameters
#### Positional Arguments
- **	exttt{*}args** - Required - Positional args for `implicit.als.AlternatingLeastSquares`

#### Keyword Arguments
- **approximate_similar_items** (bool) - Optional - Default: True - Build Annoy index for similar_items
- **approximate_recommend** (bool) - Optional - Default: True - Build Annoy index for recommend
- **n_trees** (int) - Optional - Default: 50 - Number of trees in forest; more trees = higher precision, slower build
- **search_k** (int) - Optional - Default: -1 - Search parameter; -1 = search n_trees × n_nodes trees
- **use_gpu** (bool) - Optional - Default: `implicit.gpu.HAS_CUDA` - Use GPU for ALS
- **	exttt{**kwargs}** - Required - Keyword args for `implicit.als.AlternatingLeastSquares`

### Returns
AnnoyModel wrapping an ALS model

### Usage Example
```python
import implicit.approximate_als

# Create ALS model with Annoy ANN index
model = implicit.approximate_als.AnnoyAlternatingLeastSquares(
    factors=50,
    regularization=0.01,
    iterations=15,
    n_trees=50,
    search_k=-1
)

# Fit the model (includes building Annoy indexes)
model.fit(user_items)

# Recommendation and similar_items now use approximate search
item_ids, scores = model.recommend(0, user_items[0], N=10)
similar_ids, similar_scores = model.similar_items(5, N=10)
```
```

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

### Train and Recommend with Logistic Matrix Factorization

Source: https://github.com/benfred/implicit/blob/main/_autodocs/03-logistic-matrix-factorization.md

Demonstrates how to initialize, train, and use a Logistic Matrix Factorization model for generating recommendations and finding similar items. Ensure necessary libraries like implicit, numpy, and scipy are imported.

```python
import implicit
import numpy as np
from scipy.sparse import csr_matrix

# Create user-item interaction matrix
data = np.array([1, 1, 1, 1, 1])
row = np.array([0, 0, 1, 1, 2])
col = np.array([0, 2, 1, 3, 2])
user_items = csr_matrix((data, (row, col)), shape=(3, 4))

# Initialize LMF model
model = implicit.lmf.LogisticMatrixFactorization(
    factors=20,
    learning_rate=1.0,
    iterations=30,
    neg_prop=30
)

# Train the model
model.fit(user_items, show_progress=True)

# Get recommendations
item_ids, scores = model.recommend(
    userid=0,
    user_items=user_items[0],
    N=3
)
print(f"Recommended items: {item_ids}")
print(f"Scores: {scores}")

# Find similar items
similar_ids, similar_scores = model.similar_items(itemid=2, N=2)
```

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

### FaissModel Initialization

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Initializes the FaissModel wrapper for approximate similar items and recommendations. Configure ANN parameters like nlist and nprobe, and choose GPU acceleration.

```python
class FaissModel(RecommenderBase):
    def __init__(
        self,
        model,
        approximate_similar_items=True,
        approximate_recommend=True,
        nlist=400,
        nprobe=20,
        use_gpu=implicit.gpu.HAS_CUDA,
    ):
        ...
```

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

### NMSLibModel Initialization

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Initializes the NMSLibModel wrapper for approximate similar items and recommendations. Select the indexing method (e.g., 'hnsw') and configure index and query parameters.

```python
class NMSLibModel(RecommenderBase):
    def __init__(
        self,
        model,
        approximate_similar_items=True,
        approximate_recommend=True,
        method="hnsw",
        index_params=None,
        query_params=None,
    ):
        ...
```

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

### ModelFitError Trigger: Excessive Regularization

Source: https://github.com/benfred/implicit/blob/main/_autodocs/10-errors-and-exceptions.md

Shows how setting regularization too high can lead to ModelFitError. It contrasts a 'BAD' example with a high regularization value against a 'GOOD' example with a reasonable value.

```python
# BAD: regularization too high
model = implicit.als.AlternatingLeastSquares(regularization=100.0)
model.fit(user_items)  # May fail with ModelFitError

# GOOD: reasonable regularization
model = implicit.als.AlternatingLeastSquares(regularization=0.01)
```

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

### Set Positive Example Weighting (ALS)

Source: https://github.com/benfred/implicit/blob/main/_autodocs/11-configuration-and-advanced.md

Adjust the `alpha` parameter to control the confidence weight scaling for positive examples in ALS. The default is 1.0, meaning all interactions are weighted equally. Higher values give more weight to explicit positives.

```python
model = implicit.als.AlternatingLeastSquares(alpha=1.0)  # No weighting (default)
model = implicit.als.AlternatingLeastSquares(alpha=40.0)  # Strong weight on positives
```

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

### Constructing Sparse Matrices (COO and LIL)

Source: https://github.com/benfred/implicit/blob/main/_autodocs/09-types.md

Demonstrates how to create sparse matrices in Coordinate (COO) and List of Lists (LIL) formats, which can be useful for constructing data before converting to CSR format required by the library.

```python
from scipy.sparse import coo_matrix, csr_matrix

# COO format (easier to construct)
coo = coo_matrix((data, (rows, cols)))

# LIL format
from scipy.sparse import lil_matrix
lil = lil_matrix((n_users, n_items))
```

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

### Load Model and Generate User Recommendations

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Shows how to load a pre-trained Implicit model and generate personalized item recommendations for a specific user, filtering out items they have already interacted with. Results are printed with their scores.

```python
# 1. Load model
model = implicit.als.AlternatingLeastSquares.load("model.npz")

# 2. Get user interactions
user_interactions = user_item_matrix[user_id]

# 3. Generate recommendations
item_ids, scores = model.recommend(
    userid=user_id,
    user_items=user_interactions,
    N=10,
    filter_already_liked_items=True
)

# 4. Format results
for item_id, score in zip(item_ids, scores):
    print(f"Item {item_id}: Score {score:.4f}")
```

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

### Calculate Top Recommendations for a Batch of Users

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/gpu/matrix_factorization_base.md

Efficiently calculates top N recommendations for multiple users by passing them as a batch. Leverages multi-threading on the CPU.

```python
# calculate the top recommendations for a batch of users
userids = np.arange(10)
ids, scores = model.recommend(userids, user_items[userids])
```

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

### BM25Recommender Constructor

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Demonstrates the basic constructor for the BM25Recommender. This is used to create an instance of the recommender before fitting it to data.

```python
model = implicit.nearest_neighbours.BM25Recommender(K=20, K1=1.2, B=0.75)
```

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

### Basic Implicit Model Usage

Source: https://github.com/benfred/implicit/blob/main/_autodocs/README.md

Demonstrates the common import pattern and basic usage of the AlternatingLeastSquares model, including fitting the model and generating recommendations.

```python
import implicit
model = implicit.als.AlternatingLeastSquares(factors=50)
model.fit(user_items)
recommendations = model.recommend(userid, user_items[userid], N=10)
```

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

### Common Methods for Implicit Models

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Illustrates common methods available across all Implicit models, including training with progress display, generating recommendations, finding similar items/users, and model persistence (save/load).

```python
# Training
model.fit(user_items, show_progress=True, callback=None)

# Recommendation
ids, scores = model.recommend(userid, user_items, N=10)

# Similarity
ids, scores = model.similar_items(itemid, N=10)
ids, scores = model.similar_users(userid, N=10)

# Persistence
model.save("path.npz")
model = ModelClass.load("path.npz")
```

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

### Load Model from Disk

Source: https://github.com/benfred/implicit/blob/main/_autodocs/06-base-classes.md

Instantiate a model by loading its state from a file. The method automatically appends the '.npz' extension if it's missing from the provided path.

```python
model = implicit.als.AlternatingLeastSquares.load("my_model.npz")
# or
model = implicit.als.AlternatingLeastSquares.load("my_model")  # .npz added
```

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

### Recommend Items for a Batch of Users

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/cpu/als.md

Efficiently calculates top N recommendations for multiple users using NumPy arrays. Requires 'model' and 'user_items' to be prepared for batch processing.

```python
userids = np.arange(10)
ids, scores = model.recommend(userids, user_items[userids])
```

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

### Download and Include Rapids-CMake

Source: https://github.com/benfred/implicit/blob/main/implicit/gpu/CMakeLists.txt

Downloads the RAPIDS.cmake file from a specified URL and includes it for dependency management. This is part of the setup for using rapids-cmake.

```cmake
set(rapids-cmake-version "26.02")
    file(DOWNLOAD https://raw.githubusercontent.com/rapidsai/rapids-cmake/refs/heads/release/26.02/RAPIDS.cmake
        ${CMAKE_BINARY_DIR}/RAPIDS.cmake)
    include(${CMAKE_BINARY_DIR}/RAPIDS.cmake)
    include(rapids-cmake)
    include(rapids-cpm)
    include(rapids-cuda)
    include(rapids-export)
    include(rapids-find)
```

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

### AnnoyAlternatingLeastSquares Factory

Source: https://github.com/benfred/implicit/blob/main/_autodocs/05-approximate-nearest-neighbours.md

Combines ALS with Spotify's Annoy library. Annoy is pure Python with precompiled binary wheels, easiest to install.

```python
implicit.approximate_als.AnnoyAlternatingLeastSquares(
    *args,
    approximate_similar_items=True,
    approximate_recommend=True,
    n_trees=50,
    search_k=-1,
    use_gpu=implicit.gpu.HAS_CUDA,
    **kwargs,
)
```

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

### Recommend Items for a Batch of Users

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/cpu/bpr.md

Efficiently calculates top N recommendations for multiple users using vectorized operations. Requires NumPy for array manipulation and a pre-initialized 'model' and 'user_items' sparse matrix.

```python
# calculate the top recommendations for a batch of users
userids = np.arange(10)
olds, scores = model.recommend(userids, user_items[userids])
```

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

### Get Recommendations for Users

Source: https://github.com/benfred/implicit/blob/main/_autodocs/06-base-classes.md

Generate top N item recommendations for a single user or multiple users, optionally filtering out items they have already interacted with.

```python
# Get top 10 items for user 42
ids, scores = model.recommend(
    userid=42,
    user_items=user_items[42],
    N=10,
    filter_already_liked_items=True
)

# Get top 10 items for multiple users
userids = np.array([10, 20, 30])
ids, scores = model.recommend(
    userid=userids,
    user_items=user_items[userids],
    N=10
)
```

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

### Recommend Items for a Single User

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/cpu/bpr.md

Calculates the top N recommendations for a single user. Ensure the 'model' object is initialized and 'user_items' is a valid sparse matrix.

```python
# calculate the top recommendations for a single user
ids, scores = model.recommend(0, user_items[0])
```

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

### Recommend Items for a Single User

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/cpu/als.md

Calculates the top N recommendations for a single user. Ensure the 'model' object is initialized and 'user_items' is a sparse matrix.

```python
ids, scores = model.recommend(0, user_items[0])
```

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

### Handling ModelFitError During Model Fitting

Source: https://github.com/benfred/implicit/blob/main/_autodocs/06-base-classes.md

Example of how to catch and handle ModelFitError during the model fitting process. This is useful for gracefully managing potential numerical issues or data problems.

```python
try:
    model.fit(user_items)
except ModelFitError as e:
    print(f"Model fit failed: {e}")

```

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

### Train ALS Model and Generate Recommendations

Source: https://github.com/benfred/implicit/blob/main/_autodocs/00-index.md

Demonstrates the complete workflow for training an Alternating Least Squares (ALS) model using user-item interaction data, evaluating it, and saving the trained model. Includes data loading, model configuration, training, recommendation generation, and saving.

```python
import implicit
from scipy.sparse import csr_matrix

# 1. Load/prepare data
user_items = csr_matrix(...)

# 2. Configure model
model = implicit.als.AlternatingLeastSquares(
    factors=50,
    regularization=0.01,
    iterations=15,
    random_state=42
)

# 3. Train
model.fit(user_items, show_progress=True)

# 4. Evaluate (on holdout test set)
test_recommendations = model.recommend(
    userid=np.arange(test_users),
    user_items=test_set[np.arange(test_users)],
    N=10
)

# 5. Save
model.save("production_model.npz")
```

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

### BM25Recommender Initialization

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Initializes the BM25Recommender with specified parameters for BM25 weighting. K controls the number of neighbors, K1 is the saturation parameter, B is the length normalization parameter, and num_threads can be set for parallel processing.

```python
implicit.nearest_neighbours.BM25Recommender(K=20, K1=1.2, B=0.75, num_threads=0)
```

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

### Get Similar Items for an Artist

Source: https://github.com/benfred/implicit/blob/main/examples/tutorial_lastfm.ipynb

Retrieves items similar to a given item (artist) using the `similar_items` method. Requires item IDs and scores, and optionally artist names for display.

```python
# get related items for the beatles (itemid = 25512)
ids, scores = model.similar_items(252512)

# display the results using pandas for nicer formatting
pd.DataFrame({"artist": artists[ids], "score": scores})
```

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

### Load Sketchfab Dataset

Source: https://github.com/benfred/implicit/blob/main/_autodocs/08-datasets.md

Loads the Sketchfab 3D model recommendations dataset. Returns model metadata, user identifiers, and user-model interaction matrix.

```python
from implicit.datasets import sketchfab

models, users, interactions = sketchfab.get_sketchfab()
```

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

### Recommend Items for a Single User

Source: https://github.com/benfred/implicit/blob/main/_autodocs/06-base-classes.md

Use this method to get personalized item recommendations for a single user. It can filter out already liked items and allows specifying a custom list of items to rank.

```python
# Single user recommendation
ids, scores = model.recommend(
    userid=0,
    user_items=user_items[0],
    N=10,
    filter_already_liked_items=True
)
```

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

### Using Deprecated rank_items vs. New recommend Method

Source: https://github.com/benfred/implicit/blob/main/_autodocs/06-base-classes.md

Illustrates the old pattern of using the deprecated `rank_items` method and the new pattern using the `recommend` method with the `items` parameter.

```python
ids, scores = model.rank_items(userid, user_items, selected_items)
```

```python
ids, scores = model.recommend(userid, user_items, items=selected_items)
```

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

### Set Number of Latent Factors

Source: https://github.com/benfred/implicit/blob/main/_autodocs/11-configuration-and-advanced.md

Adjust the number of latent factors to balance model capacity and computational efficiency. Start with 50-100 for prototyping and increase for production. Higher values risk overfitting.

```python
model = implicit.als.AlternatingLeastSquares(factors=50)  # Small, fast
model = implicit.als.AlternatingLeastSquares(factors=100)  # Medium (default)
model = implicit.als.AlternatingLeastSquares(factors=200)  # Large, slower
```

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

### ModelFitError Trigger: Negative Values in ALS

Source: https://github.com/benfred/implicit/blob/main/_autodocs/10-errors-and-exceptions.md

Explains that negative values in ALS are treated as explicit dislikes and can sometimes cause numerical issues, especially with extreme values. This snippet shows an example of mixed positive and negative data.

```python
# Negative values in ALS are treated as explicit dislikes
# This is fine but can cause numerical issues with extreme values
from scipy.sparse import csr_matrix

# OK: mix of positive (like) and negative (dislike)
data = np.array([5.0, -1.0, 3.0, -2.0])
user_items = csr_matrix((data, (rows, cols)), ...)
model.fit(user_items)
```

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

### Batch Processing with Multiple User IDs

Source: https://github.com/benfred/implicit/blob/main/_autodocs/09-types.md

Illustrates how to perform batch processing by passing an array of user IDs and corresponding user-item interaction data to recommendation functions. Ensures that the number of user IDs matches the first dimension of the user-item data.

```python
# Single user
userid = 0  # int
result = model.recommend(userid, user_items[0], N=10)

# Multiple users
userids = np.array([0, 1, 2])  # array of ints
user_items_batch = user_items[userids]  # Must have matching shape

# verify shapes match
assert len(userids) == user_items_batch.shape[0]

result = model.recommend(userids, user_items_batch, N=10)
```

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

### ModelFitError Trigger: Large Learning Rate (BPR/LMF)

Source: https://github.com/benfred/implicit/blob/main/_autodocs/10-errors-and-exceptions.md

Illustrates how an excessively large learning rate in BPR or LMF models can cause gradient overflow, potentially leading to ModelFitError. It provides examples of both 'BAD' and 'GOOD' learning rate settings.

```python
# BAD: learning rate huge
model = implicit.bpr.BayesianPersonalizedRanking(learning_rate=100.0)
model.fit(user_items)  # May fail

# GOOD: reasonable learning rate
model = implicit.bpr.BayesianPersonalizedRanking(learning_rate=0.01)
```

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

### Access and manipulate csr_matrix

Source: https://github.com/benfred/implicit/blob/main/_autodocs/09-types.md

Shows common operations on a CSR matrix, including accessing rows, getting counts, transposing, converting to dense format, and iterating over rows. Use `tocsr()` to ensure the matrix is in CSR format after operations like transpose.

```python
user_items = csr_matrix(...)  # shape (users, items)

# Access single row
user_0_interactions = user_items[0]  # Returns csr_matrix or csr_array

# Get number of interactions
n_interactions = user_items.nnz
n_users, n_items = user_items.shape

# Transpose
item_users = user_items.T.tocsr()

# Convert format
dense = user_items.toarray()  # WARNING: may not fit in memory for large matrices

# Iterate over rows
for user_id in range(user_items.shape[0]):
    row = user_items[user_id]
```

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

### Make Batch Recommendations for Users

Source: https://github.com/benfred/implicit/blob/main/examples/tutorial_lastfm.ipynb

Generates recommendations for multiple users efficiently by passing an array of user IDs to the `recommend` method. This utilizes multi-threading for better performance.

```python
# Make recommendations for the first 1000 users in the dataset
userids = np.arange(1000)
ids, scores = model.recommend(userids, user_plays[userids])
ids, ids.shape
```

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

### Configure BPR Learning Rate

Source: https://github.com/benfred/implicit/blob/main/_autodocs/11-configuration-and-advanced.md

Adjust the SGD learning rate for Bayesian Personalized Ranking (BPR) models. Start with 0.01 and modify based on training stability and convergence speed. Higher rates can lead to instability, while lower rates slow convergence.

```python
model = implicit.bpr.BayesianPersonalizedRanking(learning_rate=0.01)  # Default
model = implicit.bpr.BayesianPersonalizedRanking(learning_rate=0.001)  # Slower learning
model = implicit.bpr.BayesianPersonalizedRanking(learning_rate=0.1)  # Faster learning
```

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

### Download and Load Last.fm Dataset

Source: https://github.com/benfred/implicit/blob/main/examples/tutorial_lastfm.ipynb

Downloads and loads the last.fm dataset locally into memory. The dataset includes artist and user labels along with a sparse matrix of play counts.

```python
from implicit.datasets.lastfm import get_lastfm

artists, users, artist_user_plays = get_lastfm()
```

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

### Initialize BayesianPersonalizedRanking Model

Source: https://github.com/benfred/implicit/blob/main/_autodocs/02-bayesian-personalized-ranking.md

Factory function to create a CPU or GPU implementation of the BPR model. Configure parameters like factors, learning rate, regularization, and GPU usage.

```python
implicit.bpr.BayesianPersonalizedRanking(
    factors=100,
    learning_rate=0.01,
    regularization=0.01,
    dtype=np.float32,
    iterations=100,
    use_gpu=implicit.gpu.HAS_CUDA,
    num_threads=0,
    verify_negative_samples=True,
    random_state=None,
)
```

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

### load

Source: https://github.com/benfred/implicit/blob/main/docs/source/api/models/recommender_base.md

Loads the model from a file.

```APIDOC
## load(fileobj_or_path) -> RecommenderBase

### Description
Loads the model from a file.

### Parameters
#### Path Parameters
* **fileobj_or_path** (str or io.IOBase) – Either the filename or an open file-like object to load the model from

### Returns
The model loaded up from disk

### Return type
RecommenderBase
```

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

### recommend

Source: https://github.com/benfred/implicit/blob/main/_autodocs/01-alternating-least-squares.md

Generates item recommendations for a given user.

```APIDOC
## recommend

### Description
Recommends top N items for user(s).

### Method
`recommend(userid, user_items, N=10, filter_already_liked_items=True, filter_items=None, recalculate_user=False, items=None)`

### Parameters
- **userid** (int or array) - Required - User ID(s).
- **user_items** (csr_matrix) - Required - User interaction matrix.
- **N** (int) - Optional - Number of recommendations to return.
- **filter_already_liked_items** (bool) - Optional - Exclude items user has interacted with.
- **filter_items** (array) - Optional - Item IDs to exclude.
- **recalculate_user** (bool) - Optional - Recalculate user factors from interactions.
- **items** (array) - Optional - Restrict recommendations to these items.

### Returns
Tuple of (item_ids, scores)
- **item_ids**: ndarray of recommended item IDs
- **scores**: ndarray of recommendation scores
```

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

### Find and Initialize RMM

Source: https://github.com/benfred/implicit/blob/main/implicit/gpu/CMakeLists.txt

Includes the RMM CMake module and initializes it, making RMM available for use.

```cmake
# get rmm
    include(${rapids-cmake-dir}/cpm/rmm.cmake)
    rapids_cpm_rmm()
```

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

### Monitor Training Progress with Callback

Source: https://github.com/benfred/implicit/blob/main/_autodocs/11-configuration-and-advanced.md

Implement a callback function to track and log training loss and time during model fitting. This is useful for visualizing training progress and identifying potential issues.

```python
import implicit
import matplotlib.pyplot as plt

losses = []
times = []
start = time.time()

def track_loss(epoch, elapsed, loss):
    if loss is not None:
        losses.append(loss)
        times.append(time.time() - start)
        if epoch % 5 == 0:
            print(f"Epoch {epoch}: Loss={loss:.4f}, Time={elapsed:.2f}s")

model = implicit.als.AlternatingLeastSquares(
    factors=50,
    iterations=20,
    calculate_training_loss=True
)

model.fit(user_items, show_progress=True, callback=track_loss)

# Plot training curve
plt.plot(losses)
plt.xlabel("Epoch")
plt.ylabel("Training Loss")
plt.show()
```

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

### ItemItemRecommender Constructor

Source: https://github.com/benfred/implicit/blob/main/_autodocs/04-nearest-neighbours.md

Initializes an ItemItemRecommender model. It computes pairwise similarities between items and uses these to make recommendations.

```APIDOC
## ItemItemRecommender Constructor

### Description
Initializes an ItemItemRecommender model. It computes pairwise similarities between items and uses these to make recommendations.

### Method
```python
implicit.nearest_neighbours.ItemItemRecommender(K=20, num_threads=0)
```

### Parameters
#### Path Parameters
- **K** (int) - Optional - Default: 20 - Number of nearest neighbors to find for each item during training
- **num_threads** (int) - Optional - Default: 0 - Number of parallel threads; 0 = auto-detect CPU cores
```

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

### Add Subdirectories

Source: https://github.com/benfred/implicit/blob/main/implicit/CMakeLists.txt

Includes build targets from the 'cpu' and 'gpu' subdirectories.

```cmake
add_subdirectory(cpu)
add_subdirectory(gpu)
```

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

### Basic Usage of Implicit ALS Model

Source: https://github.com/benfred/implicit/blob/main/README.md

Demonstrates the basic workflow for initializing, training, and using an Alternating Least Squares model for recommendations and finding similar items.

```python
import implicit

# initialize a model
model = implicit.als.AlternatingLeastSquares(factors=50)

# train the model on a sparse matrix of user/item/confidence weights
model.fit(user_item_data)

# recommend items for a user
recommendations = model.recommend(userid, user_item_data[userid])

# find related items
related = model.similar_items(itemid)
```