How Recommendations Work — a self-recommending living book
A book about recommender systems that personalizes itself with one — and lets its readers extend it.
Live: recsys-pbook.vercel.app · RecSys '26 demo · CC BY-NC-SA 4.0
By Pavel Kordík (Recombee, FIT CTU Prague) and Eva Nečasová (AI dětem), with the Recombee team · 🤝 Want to collaborate? · 🎞 Sister project: SlAIdy
▶ Narrated 3-minute demo walkthrough — serving, telling, catalog co-creation, and the loop closing on the reader's own signals.
A recommendation platform normally decides three things for you: how content is served, how each piece is told, and what exists in the catalog at all. This book inverts all three:
- Serving — the reader picks the consumption paradigm (story missions, carousels, an algorithmic feed, a map) and can switch anytime. The initial paradigm is randomized; every switch is logged, so the deployment doubles as a research instrument.
- Telling — every concept can be told many ways: another example world, deeper or gentler, more visual, as a story or a comic, in another language. The reader steers each section; the catalog answers first, and a missing telling is an honestly reported gap — never a silent near-match.
- Catalog — on a real gap, readers generate a new telling (contract-constrained, validated) or remix any passage, diagram, or animation. Shared creations climb a curation ladder — private → community → edited → core — with full provenance; editorship itself is earned through adopted contributions. Readers can even propose whole missing concepts, which are then shown to others as proposed, not written yet cards — demand is measured before anyone writes.
Because a book teaching recommender systems is personalized by one, readers watch the mechanisms they are reading about act on their own behavior.
The content model
Content separates what must be learned from how it is told:
- A concept is a unit of understanding with a human-owned contract: learning objective, must-cover points, one canonical recall question + answer, forbidden claims. Contracts live in
content/concepts.json.
- A telling is one presentation of a concept, tagged on the facet taxonomy below. A telling declares the subspace it covers — ranges
a..b on ordered dimensions, sets a|b on categorical ones (and on the concept axis: one telling may serve several concepts).
| Dimension | What it captures | Values (subset shown) |
|---|
| lens | the world all examples come from | generic · e-commerce · media · social feeds · education · job boards |
| depth | assumed reader background | intro · standard · technical · research |
| visuality | how much visuals carry the point | text-first · balanced · visual-first |
| formalism | amount of math | none · light · full |
| length | reading commitment | tl;dr · standard · deep |
| genre | structural form | explainer · story · worked example · code walkthrough · comic · animation |
| language | natural language | English · Czech |
| carriers | building blocks present (derived from content) | prose · table · diagram · image · animation · formula · code |
| trust state | provenance rung; controls serving, labels, certification | private → community → edited → core |
The recommender (Recombee) receives facets as item properties and learns per-reader facet affinities; the reader sees and can override that profile (open learner model). Generation is segment-scoped — written for everyone who shares the requested facets, never addressed to an individual — and passes a mechanical gate (contract coverage, formalism/length lints, honest visuality) before display. The certificate reads human-verified core content only: co-creation grows the catalog without lowering the certified bar.
Roles
Readers steer · contributors share · editors verify · the arbiter decides.
- Readers — onboard in two taps, optionally state a learning goal (the book composes a 🎯 personal mission from matching concepts), steer any section, vote on proposed concepts, earn XP.
- Contributors — flag issues, share their generated/remixed tellings, or author tellings as PRs. Every profile has an invite link (
?invite=R-…).
- Editors — work from
/admin: 📊 Overview (readers, the last 7 days, what needs a look, book status) → 📚 Content (concepts by chapter with signals, coverage of tellings, preview, hand-off to the studio) → 🌱 Wishes & proposals → 🤝 Reader contributions → 🏫 Classes, ✉️ Messages, ⚡ AI & credits (editor key) → 🗂 Data (profile export for Tiny, log export, Recombee sync, editor invites). Editorship is earned (an adopted telling promotes you) or invited (?invite=E-… links, created in Data).
Full guides: HUMANS.md (readers / contributors / editors) · AGENTS.md (binding rules for AI collaborators — the facet metadata is AI-maintained under the governance split humans own the facts, AI maintains the metadata) · PERSONALIZATION.md (implementation reference) · SECURITY.md (what each API endpoint trusts, the editor key, the AI gateway, Supabase setup) · _design-collective-pbook.md (design rationale) · _editorial.md (log of record).
This is the beginning of the README. Read the rest at the original. Read the full README ↗
