◈ relate

Recommendations, live in your browser.

Drop a small CSV of users, items and ratings — get recommendations back instantly. No install, no upload, no server. The engine runs on your machine.

Powered by CoreRec · built by Bhasha

▶ Try the live demo · Repo

---

Why

Open-source recsys libraries are hard to feel. relate turns "interesting repo" into a "wow" in ten seconds: you paste a tiny ratings file and watch real recommendations appear, with reasons, computed entirely client-side. Then, when you're ready for scale, the same pipeline runs on CoreRec in Python.

Two engines, one shape

relate mirrors CoreRec's fit(...) → recommend(...) pattern in two places:

	Engine	Use it for
🌐 Browser	core/relate.mjs — dependency-free JS (Item-CF, User-CF, Matrix Factorization, Popularity)	the zero-install playground, demos, edge/offline
🐍 Python	python/relate — engine="corerec" (production) or engine="builtin" (numpy reference)	real training, batch jobs, scale

The browser engine is a faithful, small-data port of the same algorithms — so the demo and the library agree.

Quickstart — browser (no install)

Just open the live demo, or serve the repo locally:

# ES modules need to be served over http (not file://)
python -m http.server 8080
# then open http://localhost:8080/web/

Use it as a library in any web app:

import { parseCSV, guessColumns, Dataset, createModel } from "./core/relate.mjs";

const { headers, rows } = parseCSV(csvText);
const cols = guessColumns(headers);
const records = rows.map(r => Object.fromEntries(headers.map((h, i) => [h, r[i]])));

const ds = Dataset.from(records, cols);
const model = createModel("itemcf").fit(ds);          // or "mf", "usercf", "popularity"

console.log(model.recommend("Kabir", 5));
// [{ item: "Inception", score: 4.34, reasons: ["Because you liked “The Matrix”"] }, ...]

Quickstart — Python

cd python
pip install -r requirements.txt
python examples/quickstart.py

from relate import RelatePipeline, load_ratings

df = load_ratings("../data/sample_ratings.csv")           # auto-detects columns

# Reference engine (numpy, always available)
pipe = RelatePipeline(engine="builtin", model="itemcf").fit(df)
print(pipe.recommend("Kabir", top_k=5))

# Production engine — powered by CoreRec
#   pip install corerec
pipe = RelatePipeline(engine="corerec", model="dcn", embedding_dim=64, epochs=20).fit(df)
print(pipe.recommend("Kabir", top_k=5))

CLI:

python -m relate.pipeline --data ../data/sample_ratings.csv --user Kabir --top-k 5
python -m relate.pipeline --data ratings.csv --engine corerec --model dcn --user 1

Input format

A CSV with a user column, an item column, and an optional rating column. Headers are auto-detected (user_id, movie, rating, stars, …). If there's no rating column, relate treats interactions as implicit (rating = 1).

user_id,item_id,rating
Aarav,Interstellar,5
Aarav,Inception,5
Kabir,Interstellar,5
...

Algorithms

Name	Key	Good for
Item-based CF	itemcf	"more like what you liked", explainable
User-based CF	usercf	"people like you also liked"
Matrix Factorization	mf	dense rating prediction (SVD-style, biased SGD)
Popularity	popularity	baseline / cold-start fallback

The browser playground falls back to Popularity for cold users automatically.

Layout

relate/
├── core/relate.mjs        # browser engine (no deps)
├── web/                   # the playground (GitHub Pages–ready)
├── python/relate/         # pipeline: CoreRec + builtin engines
├── python/examples/       # quickstart
├── data/sample_ratings.csv
└── test/run.mjs           # engine correctness checks

Develop

node test/run.mjs          # JS engine checks
cd python && python examples/quickstart.py

License

MIT © Bhasha. CoreRec is a separate project — see https://corerec.online.