Recommendations

Overview of AACsearch recommendation engines — similar items, also-viewed, frequently-bought-together, trending, personalized, and GraphRAG. Which engine to pick for which surface.

AACsearch ships seven recommendation engines built on the same indexed corpus that powers search. They are designed to be dropped onto a product page, cart, homepage, or empty-result fallback without standing up a separate ML stack.

Engine	Input you supply	Best surface	Code path
Similar items	One product/document ID	Product detail page	`GET /recommendations/similar`
Also viewed	One product ID	"Customers also viewed" rail	`GET /recommendations/also-viewed`
Frequently bought together	One product ID	Cart, PDP "Complete the look"	`GET /recommendations/frequently-bought-together`
Trending	Optional category/segment filter	Homepage, empty results	`GET /recommendations/trending`
Personalized	`userId` (session or signed-in)	Homepage logged-in, push email	`GET /recommendations/personalized`
GraphRAG recommendations	One node + KnowledgeSpace	Knowledge graph navigation	`GET /knowledge/graphrag/recommendations`
User segments	Segment definition (rules)	Cohort targeting	`GET /recommendations/user-segments`

Picking an engine

Use this decision flow:

You know the current item the user is looking at → Similar for taste-match, Frequently bought together for cart attach, Also viewed for navigation.
You know who the user is (logged in or session id) → Personalized.
You don't know either (anonymous, empty cart, blank homepage) → Trending.
You're inside a knowledge graph (RAG/agentic flow, not commerce) → GraphRAG recommendations.

The engines compose — the dashboard's "Recommended for you" rail typically chains Personalized → Trending so a brand-new visitor with no history still gets something.

Tenancy & scope

Every recommendation request requires:

A bearer token scoped to one organization (same auth as POST /search).
An indexId or collectionName so the engine knows which corpus to score against.

Recommendations never cross indexes or organizations. The tenant filter is compiled at the SQL WHERE level (Invariant 4), not just at the API gate.

Latency profile

Engine	Read p95 (Pro tier)	Notes
Similar	80 ms	Vector search on item embedding; fast.
Also viewed	50 ms	Co-occurrence lookup, precomputed.
Frequently bought together	60 ms	Co-cart-occurrence, precomputed.
Trending	40 ms	Read from precomputed daily/hourly bucket.
Personalized	120 ms	Vector + filter; slower because of the per-user re-ranking.
Personalized from analytics	200 ms	Walks recent events for the user, more I/O.
GraphRAG	150 ms	Graph traversal + LLM step (cached).

These are budgeted under the read-path SLO described in Performance & scaling. Stay within them and recommendations slot into the same multi_search round-trip as the rest of the page.

Quota cost

Each call to a recommendation endpoint counts as one Search Unit against the monthly quota (maxSearchesPerMonth). Same cost as a POST /search. See Plans & Limits → Search Units.

Configuration surface

For engines that have tunables (model choice, decay window, segment membership), the config lives in:

GET /recommendations/personalization-config / PATCH …config
Dashboard → Search → Recommendations → Settings

Defaults are sensible. Touch the config only when you know exactly which lever you are pulling — every option has an inline doc-link.

Cold start. Personalized engines need ≥ 5 events for a given user before they outperform Trending. If you see uniform-looking results for a brand-new user, that is correct behaviour — the engine is in cold-start mode. Trending is the fallback, and the dashboard surfaces this explicitly.

Telemetry

Every recommendation surface logs:

recommendation_shown — engine, request id, returned IDs
recommendation_clicked — which ID the user clicked (drives "uplift" charts)
recommendation_converted — purchase / conversion attributed back

These events feed the Recommendations card in Dashboard → Analytics, plus the per-engine CTR/conversion rollup. They use the same analytics event bus as search (SearchUsageEvent), so historic data follows the same retention as search analytics.