02 - Glossary

Shared vocabulary for analysts and PMs editing scenarios.

Term	Meaning
Tenant	Customer isolation key (e.g. driffle-dev). All catalog/events/scenarios are per tenant.
Placement	Where recommendations appear (PDP rail, home, cart). Usually mapped to one scenario slug.
Logic type	What question we ask: user→item, item→item, multi-seed, similar, recently viewed.
Algorithm	How we score candidates for that logic (weighted-history, co-occurrence, vector-similarity, …).
Scenario	Named Admin config: logic + algorithm + nextQL filter/boosters + constraints + Qdrant/hybrid knobs + min/max. Identified by slug.
Seed	Input item(s) for item-based logics (itemId / itemIds cart).
Candidate	Item considered before final cut.
Score	Numeric rank signal (algorithm-specific units; not always comparable across algos).
nextQL	Filter / booster expression language evaluated on item attributes.
Booster	boost by F where <condition> - multiplies score when true.
Filter	nextQL predicate - items that fail are removed.
Constraint	Post-rank policy: diversity, freshness boost, long-tail injection, purchase-cap %.
Rule	Reusable Admin object (filter / booster / constraint) referenced by rulesSlugs on a scenario.
Request-time override	Per-request replacement of filter, boosters, rulesSlugs, segmentationId, and/or itemsPerSegment on recommendation APIs. Omit keeps the scenario value; present replaces. Constraints are not overridable in v1.
Impression	“This recommended item was shown” → impressions table (needs scenario_slug for per-scenario analytics).
Interaction	User/item event: view, cart, purchase, rating → interactions table.
Weight (event)	Optional float on an interaction (default 1.0). Combined with type multipliers in weighted-history.
scenario_slug / scenarioSlug	Attribution field linking an event to a placement/scenario.
CTR (Admin)	100 × views_with_slug / impressions_with_slug where “views” means type='view'.
Purchase cap	Limit how many already-purchased items (90d) may appear in a result list (default 10%). Needs userId.
Cold start	User/item with little history - algos fall back (e.g. popularity, same-category).
RRF	Reciprocal Rank Fusion - merges ranked lists by rank position, not raw scores.
Centroid	Average of seed vectors for multi-seed hybrid when cart is category-homogeneous.
Factors	Learned vectors for users/items from ELSA or ReALM, stored in Mongo model_factors.
Availability	Unavailable items (available: false) are excluded from serving.
Identity merge	Link anonymous sessionId history into an authenticated userId after login.

Logic vs algorithm vs scenario

Placement "PDP Similar"
   → scenario slug: pdp-similar-products
        → logicType: similar-products
        → algorithm: vector-similarity   (or beeformer-multimodal)
        → filter / boosters / constraints / qdrantSettings

Changing algorithm changes candidate generation. Changing constraints changes post-rank shaping. Changing filter removes candidates that fail nextQL.