4051077cff
- API.md: document `similar_to`/`region`/`unavailable_shards` on /feed and /search, the new POST /vector_search k-NN probe, and the cluster-node-only routes (/cluster/*, /sharded/*, /hardnegs) - CHANGELOG.md: M12 entries — multi-vector preference + ANN candidate-gen, idle-readiness + TLS scale-up (m12p5/p6), sharded ingestion (m12p4) - ROADMAP.md: mark M11 + M12 COMPLETE; restate the v1.0 bar (30-day-green nightly calendar + Ref-A/k3s throughput re-runs) - prometheus-alerts.yaml: add ship-stall, quorum-lag, divergence-quarantine, reseed-pending, and snapshot-pin-force-drop cluster alerts - check-docs.sh: self-updating milestone-status freshness guard derived from ROADMAP's latest COMPLETE milestone - refresh specs (00-14), ai-lookup, guides, and runbooks to M0-M12
2.5 KiB
Entities
Last Updated: 2026-02-19 Confidence: High
Summary
Entities are the nodes of the system. Three types: Items (content), Users, and Creators. Every entity has metadata, a vector embedding slot, and an attached signal ledger.
Key Facts:
- Items have metadata, embeddings, and signals — signals are typed timestamped streams, not fields
- Users have preferences, histories, and relationships — living profiles that update continuously
- A user's taste is two-tier: cold-start users (
< 5interactions) carry a single adaptive-LR preference vector (K=1); warm users carry multiple preference clusters (one centroid per coherent interest) - Creators are linked to Items and have their own embeddings (aggregated from catalog)
- Relationships are first-class edges between entities (weighted, directional, traversable)
File Pointer: VISION.md:36-43
How It Works
Items enter via the WRITE path with metadata + embedding. A signal ledger is initialized at zero. Cold start exploration budget is applied automatically. Items are immediately queryable after commit.
Users accumulate implicit taste from engagement history, updated on every positive-engagement signal write (like, completion, etc.). The model has two tiers, gated on the user's total positive interaction count (COLD_START_N = 5):
- Cold start (
< 5interactions): a single preference vector (entities/preference.rs) blended via an adaptive learning rate (alpha = base / (1 + ln(1 + count))) and L2-normalized — the K=1 case. - Warm (≥ 5 interactions): multiple preference clusters (
entities/multi_preference.rs). Each positive engagement is assigned to its nearest centroid by cosine; a DP-means threshold (τ, default0.55) opens a new cluster when nothing is similar enough, capped atK_MAX = 10(over the cap, the engagement is assigned to the nearest centroid, never evicted). Each cluster carries its own adaptive LR and a forward-decayed importance (default half-life 30 days). On crossing the threshold the single vector seeds cluster 0, so the cold taste is never discarded.
This keeps a user who engages with hiking, cooking, and cars from collapsing into one averaged centroid that represents none of them.
Creators are entities with their own embeddings derived from their item catalog. Creator-level signals include engagement rate, posting frequency, and follower count.