API Surface & Import Guidance

Package entry point

import cooprecsys

Model APIs are grouped below cooprecsys.models:

from cooprecsys.models.ary2tower import (
    TwoTowerConfig,
    TwoTowerTrainer,
    TwoTowerInference,
)
from cooprecsys.models.arycolbring import AryColBring

Do not use from src.models... in application code. That is a repository-layout import and does not describe the installed package namespace.

Integration boundaries

Keep these concerns separate:

• data — pandas/DuckDB ingestion;
• prepare — schema discovery and file/metadata helpers;
• features — deterministic feature transformations and encoders;
• qrates — pseudo-rating/composite-score derivation;
• models — fit/predict/recommend;
• evaluation/reporting — metrics, diagnostics, HTML artifacts;
• application — business-specific orchestration.

Important Ary2Tower APIs

TwoTowerTrainer manages fitting and model serialization. TwoTowerInference provides paired scoring plus top-N serving. TwoTowerWeights, UserTower, and ItemTower expose the underlying representation layer for advanced diagnostics.

The lower-level TwoTowerPredictor in models/ary2tower/inout/approximator.py is useful when an application needs direct pair scoring or explicit ranking over a supplied item set without the higher-level serving wrapper.

Native backend inspection

from cooprecsys.models.ary2tower.towers import backend_info
print(backend_info())

The expected production-native path identifies the compiled Cython/OpenMP backend. If the extension cannot be imported, the Python API remains available through NumPy implementations.

API documentation scope

This site documents stable integration concepts and important concrete entry points from the supplied source. It deliberately avoids pretending to be a generated symbol-by-symbol API reference. For exact signatures, inspect the source package linked below.

GitHub source