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
35 lines
2.5 KiB
Markdown
35 lines
2.5 KiB
Markdown
# 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 (`< 5` interactions) 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 (`< 5` interactions):** 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 (τ, default `0.55`) opens a new cluster when nothing is similar enough, capped at `K_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.
|
|
|
|
## Related Topics
|
|
- [Signals](./signals.md)
|
|
- [Ranking Profiles](./ranking-profiles.md)
|