10 - Appendices

A. Recommendation API cheat sheet

All need tenant auth (X-Tenant-Id / HMAC as configured).

Method	Path	Notes
GET	/recommendations/algorithms	Registry list
GET	/recommendations/algorithms/:logicType	Filtered registry
GET	/recommendations/user-to-item/:userId	count, scenario
GET	/recommendations/item-to-item/:itemId	count, scenario, userId (purchase cap)
GET	/recommendations/recently-viewed/:userId	count, scenario
POST	/recommendations/items-to-items	body { itemIds, count } + scenario, userId
GET	/recommendations/similar-products/:itemId	count, scenario, userId
POST	/recommendations	Unified body: scenario / logicType / ids / count

Response includes algorithm used.

Ingestion

Method	Path
POST	/ingestion/interactions
POST	/ingestion/impressions

Analytics (Admin JWT)

Method	Path
GET	/analytics/scenario/:slug/summary?days=30
GET	/analytics/scenario/:slug/funnel-volume?days=30
GET	/analytics/scenario/:slug/top-items?days=30
GET	/analytics/top-recommended?days=30

---

B. ClickHouse recipes (driffle-dev examples)

Interaction mix (30d)

SELECT type, count() AS c, sum(weight) AS sum_w, round(avg(weight), 3) AS avg_w
FROM recomnext.interactions
WHERE tenant_id = 'driffle-dev'
  AND event_time >= now() - INTERVAL 30 DAY
GROUP BY type
ORDER BY c DESC;

Scenario summary (matches Admin CTR)

SELECT
  (SELECT count()
   FROM recomnext.impressions
   WHERE tenant_id = 'driffle-dev'
     AND scenario_slug = 'pdp-similar-products'
     AND event_time >= now() - INTERVAL 30 DAY) AS impressions,
  (SELECT count()
   FROM recomnext.interactions
   WHERE tenant_id = 'driffle-dev'
     AND scenario_slug = 'pdp-similar-products'
     AND type = 'view'
     AND event_time >= now() - INTERVAL 30 DAY) AS clicks_views,
  round(clicks_views / impressions * 100, 2) AS ctr_pct;

Weighted-history style item scores (global, illustrative)

SELECT item_id,
       sum(weight * multiIf(
         type = 'purchase', 4,
         type = 'cart', 2,
         type = 'rating', 3,
         1)) AS total_weight,
       countIf(type = 'view') AS views,
       countIf(type = 'cart') AS carts,
       countIf(type = 'purchase') AS purchases
FROM recomnext.interactions
WHERE tenant_id = 'driffle-dev'
  AND event_time >= now() - INTERVAL 30 DAY
GROUP BY item_id
ORDER BY total_weight DESC
LIMIT 20;

Co-occurrence for one seed

SELECT b.item_id AS related_item_id, count() AS co_count
FROM recomnext.interactions AS a
INNER JOIN recomnext.interactions AS b
  ON a.tenant_id = b.tenant_id AND a.user_id = b.user_id
WHERE a.tenant_id = 'driffle-dev'
  AND a.item_id = 'SEED_ITEM_ID'
  AND b.item_id != 'SEED_ITEM_ID'
  AND a.event_time >= now() - INTERVAL 30 DAY
  AND b.event_time >= now() - INTERVAL 30 DAY
GROUP BY related_item_id
ORDER BY co_count DESC
LIMIT 40;

Attribution health: views without impressions (same user+item)

WITH
  views AS (
    SELECT user_id, item_id, count() AS view_cnt
    FROM recomnext.interactions
    WHERE tenant_id = 'driffle-dev'
      AND scenario_slug = 'pdp-similar-products'
      AND type = 'view'
      AND event_time >= now() - INTERVAL 30 DAY
    GROUP BY user_id, item_id
  ),
  imps AS (
    SELECT user_id, item_id, count() AS imp_cnt
    FROM recomnext.impressions
    WHERE tenant_id = 'driffle-dev'
      AND scenario_slug = 'pdp-similar-products'
      AND event_time >= now() - INTERVAL 30 DAY
    GROUP BY user_id, item_id
  )
SELECT
  count() AS view_pairs,
  countIf(i.imp_cnt > 0) AS pairs_with_impression,
  sum(v.view_cnt) AS total_views,
  sumIf(v.view_cnt, i.imp_cnt = 0 OR isNull(i.imp_cnt)) AS views_orphan
FROM views v
LEFT JOIN imps i ON v.user_id = i.user_id AND v.item_id = i.item_id;

---

C. Type multipliers (weighted-history)

type	multiplier
purchase	4
rating	3
cart	2
view / other	1

Windows: personal history 30d; popularity fill 7d; purchase-cap history 90d.

---

D. Constraint defaults (conceptual)

Field	Typical default / note
purchasedItemsMaxPercent	10 if unset
longTailPercentage	10 when long-tail on
Freshness boost factor	×1.5 inside window
minItems / maxItems	6 / 12 common scenario defaults

---

E. Document map

File	Contents
README	Hub
01	Architecture
02	Terms
03	Events & CTR
04	Pipeline & knobs
05	Logics & algos
06	ELSA / ReALM / beeFormer
07	Calculations
08	Ops
09	Attribution failure
10	This file