recotem

Recotem is a recipe-driven recommender system framework that simplifies training and serving recommendation models. It is built on irspack and uses a single YAML recipe file to define the entire pipeline: data source, training algorithm, hyperparameter search, and output location. The `recotem train` command produces a signed binary artifact, while `recotem serve` runs a FastAPI server that exposes endpoints like `/v1/recipes/{name}:recommend` and `:recommend-related`, with automatic hot-swapping when new artifacts appear. It requires no database or message broker, making it lightweight and easy to deploy. Key features include: - **Recipe-driven configuration**: One YAML file defines a complete model, from data ingestion to serving. - **Hyperparameter optimization**: Uses Optuna to search across irspack algorithms. - **Feature-aware iALS**: Supports item/user side features (categorical, numerical, multi-label) for improved recommendations. - **Cold-start support**: Can recommend for unknown users or items using attribute features. - **Pluggable data sources**: Built-in support for CSV, Parquet, BigQuery, and SQL (PostgreSQL, MySQL, SQLite), with extensibility via Python entry points. - **Secure artifacts**: HMAC-signed with multi-key rotation and a deterministic class allow-list for safe deserialization. - **API key authentication**: Optional `X-API-Key` header, with keys hashed at rest. - **Flexible storage**: Uses fsspec for local, S3, GCS, Azure, and HTTPS paths. - **Observability**: Optional Prometheus metrics and structured JSON logs with secret redaction. The tool is designed for reproducibility and operational simplicity. Training runs as a batch job (e.g., cron, Airflow, Kubernetes CronJob), and serving is a long-lived process that watches for new artifacts and swaps them atomically. This separation allows training and serving to run on different machines, communicating only via artifact files. Installation is via pip with extras for specific data sources (e.g., `recotem[bigquery]`, `recotem[s3]`). A multi-arch Docker image is available on ghcr.io. The project requires Python 3.12+ and supports glibc Linux (x86-64/arm64), macOS (Apple Silicon), and Windows (x86-64). Some extras like `bprfm` have narrower platform support and may require building from source. The quickstart example demonstrates training a TopPop recommender from a small CSV and serving recommendations via HTTP. The documentation site (recotem.org) provides comprehensive guides, API references, and operational details.