Package Architecture

High-level architecture

cooprecsys/
├── assets/        # dashboard/report assets and visualization helpers
├── configs/       # shared INI + typed runtime/model configuration
├── db/            # DuckDB connection/query utilities
├── features/      # date, encoding, feature engineering, loading, LTR prep
├── models/
│   ├── ary2tower/ # two-tower neural recommender + Cython kernels
│   ├── arycolbring/
│   └── ltr_lgbm/
├── noisemaker/    # data exchange, splitting, and robustness/noise helpers
├── prepare/       # schema identification, JSON/dict helpers, file utilities
└── qrates/        # pseudo-ratings, composite scoring, quasi-rate retrieval

The important architectural boundary is that models consume prepared representations. prepare discovers and normalizes structure, db supplies analytical execution, features creates reusable transformations, and qrates can derive a scoring/rating signal before a downstream model is trained.

Model layers

AryColBring

AryColBring remains part of the documented model family. Its CLproximity/ directory contains Cython/OpenMP proximity/training kernels, while inout/, eval/, assist/, and narative/ separate prediction, evaluation, support, and report responsibilities.

Ary2Tower

Ary2Tower exposes a Python orchestration layer (towers.py, trainer.py, inference.py, report.py) around CLtowers/ native kernels. The compiled package includes forward, prediction, similarity, training, and type-level Cython modules. inout/ contains the lower-level architect/predictor interfaces and the residual fallback reasoner.

The current inference contract is important: the primary recommendation path scores the eligible catalogue, instead of taking a small top-k pool and then losing rows during purchase filtering. When the requested count still cannot be filled, the residual fallback uses a Bayesian-smoothed popularity prior with optional recency decay; it is not an item-to-item similarity filter.

LTR-LightGBM

LTR-LightGBM is the feature-rich ranking path. It keeps group-aware preparation, ranker invocation, prediction, reporting, and feature-processing utilities separate from the lower-level model implementation.

Data flow

Raw transactions / pandas / DuckDB
                 |
                 v
         prepare + db loading
                 |
                 v
       dates + encoders + features
                 |
          +------+------+
          |             |
          v             v
       qrates       model training
          |         /      |      \
          |   AryColBring Ary2Tower LTR
          |         \      |      /
          +----------+-----+-----+
                     |
                     v
              ranking / inference
                     |
                     v
            reports / dashboard

This separation also means a pandas DataFrame can be the source for a simple workflow, while the same data can be registered into DuckDB for large analytical transformations without changing the downstream model API.