CoopRecSys is a Python machine-learning and AI toolkit for building production-oriented recommendation systems around cooperative and commerce-style transaction data.
The current model layer contains three complementary approaches:
- AryColBring — Cython/OpenMP collaborative filtering for sparse implicit-feedback interactions, with Logistic, WARP, BPR, and WARP-kOS objectives.
- Ary2Tower — a two-tower neural recommender whose hot paths can execute through compiled Cython/OpenMP kernels, with a pure-NumPy execution path when native extensions are unavailable.
- LTR-LightGBM — feature-rich learning-to-rank workflows for query/customer groups where engineered features and ranking objectives matter.
The package around those models is intentionally broader than the model classes themselves. It includes assets, configs, db, features, noisemaker, prepare, and qrates so that ingestion, pseudo-ratings, feature preparation, experimentation, evaluation, and reporting can be kept reproducible.
What this documentation covers
- Getting Started — installation, environments, source builds, and first recommendation workflows.
- Architecture — how data, features, model families, reports, and dashboard surfaces connect.
- Models — AryColBring, Ary2Tower, and LTR-LightGBM, including native extension behavior.
- Data & Features —
prepare,db,features, encoding, DuckDB workflows, and feature lifecycle. - Explainability & Dashboards — reporting, visual diagnostics, and operational dashboard surfaces.
- Operations — configuration, native builds, tests, CI/CD, release packaging, and wheels.
- Reference — package layout, API conventions, configuration files,
qrates, and reusable utilities.
Canonical import rule
Source-tree layout and installed-package layout are different concepts. The public Python package should be imported as cooprecsys, not as src.models or src.cooprecsys.
from cooprecsys.models.ary2tower import TwoTowerTrainer, TwoTowerInference
from cooprecsys.models.arycolbring import AryColBringThe src/ prefix belongs to the repository filesystem layout used by a source checkout; it is not the Python import namespace.
Release baseline
This documentation is aligned with the current production documentation/source tree and the recent native two-tower fixes. Where the repository contains optional or model-specific components, the pages document the behavior present in the supplied source rather than inventing a larger public API.
Engineering note: native extensions are build artifacts. Consumers should prefer published wheels. Developers building from source should use the model-specific build entry point documented for that model so the extension is compiled in the correct package directory.
Maintainer
Aryanto (masterofray)
Portfolio: ai.arydatalabs.workers.dev
LinkedIn: linkedin.com/in/aryanto-ray
Email: aryanto.dandan@gmail.com