Quick Start: First Recommendation Workflow

1. Choose a model family

2. Prepare the interaction data

A minimal sparse matrix can be built directly, or your pandas/transaction table can first pass through prepare, features, and qrates.

import numpy as np
import scipy.sparse as sp

interactions = sp.coo_matrix(
    (
        np.ones(1000, dtype=np.float32),
        (
            np.random.randint(0, 100, 1000),
            np.random.randint(0, 50, 1000),
        ),
    ),
    shape=(100, 50),
)

3. Train AryColBring

The public package import uses cooprecsys, not the repository’s src/ path:

from cooprecsys.models.arycolbring import AryColBring

model = AryColBring(
    no_components=32,
    loss='warp',
    learning_rate=0.05,
    random_state=42,
)
model.fit(interactions, epochs=10, num_threads=4)

4. Or train Ary2Tower

from cooprecsys.models.ary2tower import TwoTowerTrainer, TwoTowerConfig

trainer = TwoTowerTrainer(
    n_users=100,
    n_items=50,
    config=TwoTowerConfig(
        embedding_dim=32,
        hidden_dim=64,
        output_dim=16,
        n_epochs=10,
        num_threads=4,
        random_state=42,
    ),
)
trainer.fit(interactions)
trainer.save_model('artifacts/models/ary2tower.npz')

5. Generate exact-N recommendations

from cooprecsys.models.ary2tower import TwoTowerInference

infer = TwoTowerInference(
    'artifacts/models/ary2tower.npz',
    purchase_data=purchases,
)

recs = infer.recommend(
    user_id=7,
    n_items=10,
    exclude_purchased=True,
)

The recommendation path scores the eligible catalogue and then uses the residual fallback only to fill a genuine shortfall. The fallback is Bayesian-smoothed popularity with optional recency weighting; it is not item-item similarity.

6. Evaluate before deployment

Check ranking quality, catalogue coverage, duplicate rate, cold-start behavior, latency, and the fraction of recommendations that required fallback.

For LTR use query-group aware evaluation. For Ary2Tower additionally compare the compiled Cython backend with the NumPy path during CI or pre-release validation.

7. Move to explainability and diagnostics

Use model-specific report and visualization modules after the core ranking contract has passed. See Explainability & Dashboards, QRates, and Configuration Files.