Commerce Recommendations — Product Vision & Strategy Brief¶

Document control¶

Product boundary: A multi-property recommendation service with a Training API that triggers property-local batch generation from relational commerce data and a Serving API that retrieves persisted Recommendation Sets. Catalog operations, presentation, external scheduling, and shopper-specific personalization are excluded.
Status: Approved
Strategic decision owner: Sponsor (user; name not recorded)
Product Manager: Codex
Revision: 0.16 — 2026-08-05
Approved revision: 0.16 — approved by Sponsor (user), 2026-08-05
Next review gate: Review the first feature specification and resolve its remaining behavioral decisions.
Product glossary: CONTEXT.md
Product context map: None needed
Product ADRs: None

Executive product narrative¶

Vision statement¶

Enable independent stores and marketplaces to turn their existing commerce data into trustworthy product-to-product discovery and cross-sell recommendations without building their own recommendation infrastructure.

Strategic thesis¶

Start with property-specific Item-to-Item Recommendation Strategies because they are reusable across downstream experiences, preserve property boundaries, and can be computed efficiently from sparse co-occurrence matrices. Win through clear strategy semantics, evidence-aware fallback behavior, reproducible evaluation, versioned Recommendation Snapshots, and APIs that disclose how each relationship was produced.

What this is not¶

An e-commerce storefront, catalog manager, or recommendation-presentation user interface.
A shopper-specific personalization engine in the first version.
A system that pools behavioral evidence across Commerce Properties.

Vision mandate and context¶

Sponsor's vision seed¶

Input: Multiple stores and marketplaces provide views and online purchases, and may additionally provide in-store/offline purchases, to an ML pipeline and receive Item-to-Item Recommendation Sets for common e-commerce swimlanes.
Source/owner/date: Sponsor conversation, 2026-08-05.
Interpretation: External systems own commerce operations, scheduling, and presentation; this product owns relational-data retrieval, batch recommendation generation, snapshot persistence, and API serving.
Unresolved ambiguity: The primary quality objective and evidence threshold for calling one approach better than another.

Product and value exchange¶

Product definition: An API-accessible recommendation service operating independently for each Commerce Property.
Users/customers: Merchandisers, commerce operators, and downstream systems that consume generated recommendations; commercial buyer and payer are not yet defined.
User value: Obtain explainable, reusable product relationships without operating a dedicated recommendation stack.
Lifecycle stage: Exploration.

Product strategy¶

Strategic choices¶

Where to play: Multi-store and multi-marketplace commerce datasets with stable Item, Order, Browsing Session, and property identifiers.
Where not to play: Storefront functions, cross-property learning, and shopper-specific recommendations in the first version.
How to win: Provide strong, simple, reproducible co-occurrence baselines with strategy-aware cold-item fallback and explicit provenance.
Capabilities required: Sparse co-occurrence modeling, catalog-metadata similarity, temporal popularity, per-property isolation, filtering, offline evaluation, and output provenance.

Invocation and serving contract¶

A Training Run is requested through the Training API for one Commerce Property.
The Training Run retrieves Catalog, Item Metadata, views, and online purchases from a configured relational database rather than uploaded files; in-store/offline purchases are an optional additional input.
A successful Training Run persists a versioned Recommendation Snapshot atomically; a failed run must not replace the currently served snapshot.
The Serving API reads persisted Recommendation Sets from an available snapshot and does not calculate co-occurrence models synchronously.
External infrastructure decides when to call the Training API; daily invocation remains the provisional freshness default.

Relational data-source compatibility¶

Recommendation logic is independent of the source database engine.
A Data Source Adapter uses an installed SQLAlchemy-compatible dialect or an equivalent adapter to execute configured read queries and stream canonical rows directly into the Training Run.
Core recommendation code contains no PostgreSQL-, SQLite-, Snowflake-, or other vendor-specific SQL.
A database engine is supported only when its driver and dialect are installed and its adapter passes the shared compatibility contract; engine neutrality does not imply that an untested driver works automatically.
Source connections are read-only from the recommendation service's perspective.

Canonical streaming-read contract¶

Each saved data-source configuration contains pre-approved read queries or table/view references plus column mappings for Catalog, views, and online purchases, with an optional additional mapping for in-store/offline purchases.
The Training API selects a saved configuration; it does not accept arbitrary SQL or database credentials per request.
Canonical Catalog rows provide an Item identifier plus available category, brand, price, availability, creation time, and descriptive metadata.
Canonical view rows provide a Tracking ID, Browsing Session identifier, Item identifier, and view timestamp.
Canonical Online Purchase and optional Offline Purchase rows provide a Tracking ID, Order identifier, Item identifier, purchase timestamp, and quantity.
Online and Offline Purchase rows contribute to the same purchase-driven strategies, while Order identity remains scoped by Purchase Channel so coincident source Order IDs do not create false co-purchase evidence.
SESSION_ID is mandatory for training Also Viewed, and ORDER_ID is mandatory for training Frequently Bought Together. A Data Source Adapter may map differently named source columns to these canonical fields.
Read queries filter TRACKING_ID using a bound parameter associated with the requested Commerce Property.
Source interaction rows use PRODUCT_ID and CATALOG_ID to resolve the corresponding merchant Catalog row.
Canonical Item identity is the composite of data-source identity, Tracking ID, Catalog ID, and Product ID; no component is assumed globally unique.
Canonical rows are consumed incrementally as a stream from the relational source. The service does not extract, stage, or persist a raw interaction dataset before recommendation generation.

Selected first-version strategies¶

Frequently Bought Together: Same-Order co-occurrence.
Also Viewed: Same-Browsing-Session co-occurrence.
Similar Items: Item Metadata similarity for substitutes and cold Items.
Best Sellers: Time-decayed purchase popularity.
Most Viewed: Time-decayed view popularity.
Trending: Recent interaction momentum relative to a longer property baseline.
Also Viewed fallback selected for benchmarking: normalized same-session co-occurrence with support and shrinkage; Item Metadata similarity; category-level time-decayed views; then property-wide time-decayed views.
Frequently Bought Together fallback selected for benchmarking: normalized same-Order co-occurrence with support and shrinkage; category-pair co-purchase evidence; compatibility or complement rules when supplied; category-level time-decayed purchases; then property-wide time-decayed purchases. Ordinary Item Metadata similarity is excluded because it can produce substitutes rather than complements.
Similar Items cold-start behavior: use Item Metadata similarity when behavioral evidence is sparse or absent.
Cold Commerce Property behavior: Similar Items may operate from Item Metadata, while behavioral strategies remain unavailable or use explicitly identified external merchandising defaults until property-local evidence exists.

The fallback cascade is a literature-supported hypothesis, not a universally proven optimum. Its order and parameters must be tested per Commerce Property and against simpler baselines.

Behavioral isolation¶

Interaction records, co-occurrence counts, popularity statistics, and learned behavioral relationships remain isolated within each Commerce Property.
Recommendation candidates and anchors must share the same Catalog ID; cross-Catalog Recommendation Sets are prohibited in the first version.
Shared code, generic pretrained content encoders, public Item Metadata representations, and default hyperparameters may be reused across properties.
Cross-property behavioral transfer is deferred and would require explicit opt-in, aligned catalogs or taxonomies, privacy controls, and evidence that it outperforms property-local baselines.

Research and learning agenda¶

Question or hypothesis	Why decision-relevant	Evidence threshold
The selected fallback cascade outperforms direct popularity fallback.	Determines whether added complexity creates value.	Temporal holdout comparison per strategy and property, followed by downstream controlled experiments when exposure outcomes are available.
Normalized co-occurrence is preferable to raw pair counts.	Raw counts can collapse into popularity ranking.	Compare tuned cosine/shrinkage and association measures against raw-count and popularity baselines.
Item Metadata improves sparse-Item coverage without unacceptable relevance loss.	Determines the value of the second fallback tier.	Measure ranking quality, catalog coverage, popularity concentration, and results by Item-support cohort.
Cross-property transfer improves cold-start outcomes enough to justify its trust and distribution-shift risks.	Determines whether behavioral isolation should ever be relaxed.	Opt-in evaluation on aligned catalogs must beat property-only metadata and popularity baselines without privacy, leakage, or subgroup regressions.
Advanced language or multimodal priors outperform lightweight metadata similarity for strict cold Items.	Determines whether model complexity is warranted.	Strict temporal cold-Item cohort must show material NDCG@K, Recall@K, and coverage gains relative to cost and reproducibility.

Evaluation standard¶

Use chronological training and holdout periods rather than random interaction splitting.
Evaluate each Recommendation Strategy separately for every Commerce Property.
Use Recall@K and NDCG@K as primary offline ranking measures.
Track catalog coverage, popularity concentration, fallback rate, and performance by Item-support cohort as guardrails and diagnostic measures.
Compare every candidate against raw co-occurrence, tuned normalized co-occurrence, and time-decayed popularity baselines.
Treat offline improvement as evidence for controlled downstream testing, not proof of business impact.
When recommendation-exposure outcomes become available, validate Frequently Bought Together through attachment or conversion outcomes and Also Viewed through click-through or product-discovery outcomes.

Evidence register¶

ID	Claim	Source	Limitations	Confidence
E-001	Offline Item-to-Item similarity tables provide scalable related-item recommendations.	Linden, Smith, and York, 2003	Historical Amazon implementation; not a benchmark on the sponsor's datasets.	High for architecture pattern; unknown for local outcomes.
E-002	Properly tuned nearest-neighbor and non-neural baselines can outperform more complex recommenders.	Ferrari Dacrema, Cremonesi, and Jannach, 2019; Ludewig et al., 2019	Published datasets and evaluation protocols may not match commerce properties here.	High for requiring strong baselines.
E-003	Combining interaction evidence with Item Metadata is an established response to sparse and cold Items.	Burke, 2002; Amazon Similar-Items	No universal hybrid ordering or parameter choice follows from these sources.	Medium-high.
E-004	Popularity is useful in cold-start situations but can reduce discovery value when overused.	Klimashevskaia et al., 2024	Impact is application-specific and requires field evidence.	High for the trade-off; unknown for the local optimum.
E-005	Major commerce platforms distinguish co-purchase, co-view, most-viewed, best-seller, related, and complementary intents.	Amazon Personalize e-commerce use cases; Shopify recommendation intents	Vendor product conventions are evidence of common practice, not proof of optimality.	High for common strategy vocabulary.
E-006	Current cold-start research distinguishes long-tail, few-interaction, strict new-Item, and system-level cold start; these require separate evaluations.	Zhang et al., 2025	Semi-systematic survey covers literature through December 2024 and reports inconsistent evaluation practices.	High for taxonomy; no universal method ranking.
E-007	Recent cold-start work increasingly uses content, graph relations, cross-domain information, and language-model knowledge as progressively broader priors.	Zhang et al., 2025	Many methods target personalized user-to-Item recommendation rather than batch Item-to-Item relationships.	High for research direction; medium for direct applicability.
E-008	Language-model similarity can act as a Bayesian prior for a classical recommender when structured metadata is incomplete.	Wang et al., 2024	Evaluated on two datasets; adds model cost and does not establish superiority for this product's datasets.	Medium.
E-009	2026 multimodal methods combine attributes, images, and co-occurrence signals for cold Items.	M²VAE, AAAI 2026; MoToRec, AAAI 2026	Complex personalized-recommendation models; not evidence that they beat simple metadata similarity for this Item-to-Item use case.	Medium for future exploration.
E-010	Cross-domain transfer depends on bridges such as overlapping users, aligned attributes, or aligned categories and introduces privacy and domain-shift concerns.	Zhang et al., 2025; IFedRec, WWW 2024	Federated and cross-domain settings differ from centralized multi-property batch generation.	High for constraints; unknown local benefit.

Decision log¶

ID	Date	Decision and owner	Evidence	Revisit trigger
D-001	2026-08-05	Sponsor selected a multi-property recommendation pipeline while keeping commerce infrastructure external.	Sponsor direction.	Product boundary changes.
D-002	2026-08-05	Sponsor selected Item-to-Item recommendations using co-occurrence matrices for the first version.	Sponsor direction; E-001 and E-002.	Shopper-specific personalization becomes required.
D-003	2026-08-05	Sponsor defined same Order for Frequently Bought Together and same Browsing Session for Also Viewed.	Sponsor direction; E-005.	Input grouping semantics change.
D-004	2026-08-05	Sponsor selected the proposed fallback cascade for benchmarking, conditional on literature support and local validation.	E-002 through E-004.	A simpler baseline wins, metadata is inadequate, or downstream tests contradict offline results.
D-005	2026-08-05	Sponsor adopted temporal holdout evaluation by property and strategy, using ranking measures, coverage and popularity guardrails, support cohorts, simple baselines, and later downstream controlled tests.	E-002 and E-004.	Evaluation data cannot reproduce the intended recommendation context or downstream objectives change.
D-006	2026-08-05	Sponsor selected Frequently Bought Together, Also Viewed, Similar Items, Best Sellers, Most Viewed, and Trending for the first-version portfolio.	E-003 through E-005.	Evaluation shows a strategy lacks distinct value or a higher-priority intent emerges.
D-007	2026-08-05	Sponsor prohibited cross-property behavioral pooling in the first version and selected property-local, strategy-specific cold-start handling.	E-006 through E-010.	Opt-in transfer demonstrates material benefit under aligned semantics, privacy controls, and property-level evaluation.
D-008	2026-08-05	Sponsor selected API-triggered batch training from a relational database plus a Serving API for persisted Recommendation Snapshots. External infrastructure retains scheduling.	Sponsor direction.	Real-time model updates or file-based ingestion become required.
D-009	2026-08-05	Sponsor required an engine-agnostic relational streaming-read boundary covering databases and warehouses such as Snowflake, PostgreSQL, and SQLite.	Sponsor direction.	An engine requires semantics that cannot satisfy the canonical adapter contract.
D-010	2026-08-05	Sponsor selected saved read queries or relation mappings that stream canonical rows rather than fixed physical source schemas or request-supplied SQL. Purchase rows are partitioned by `TRACKING_ID`.	Sponsor direction.	Source systems cannot provide the canonical fields or require a different isolation key.
D-011	2026-08-05	Sponsor selected `(data_source_id, TRACKING_ID)` as Commerce Property identity and supplied `CATALOG_ID` plus `PRODUCT_ID` as the source join identity for Items.	Sponsor direction.	Source identity guarantees are revised.
D-012	2026-08-05	Sponsor made Catalog ID a hard first-version recommendation boundary; anchors and recommended Items must come from the same merchant Catalog.	Sponsor direction.	An explicitly governed marketplace use case requires cross-Catalog discovery.
D-013	2026-08-05	Sponsor made Order ID mandatory for Frequently Bought Together and Browsing Session ID mandatory for Also Viewed, with adapter-level source-column mapping permitted.	Sponsor direction.	Either strategy is redefined with a different co-occurrence context.
D-014	2026-08-05	Sponsor required direct streaming consumption of relational rows and prohibited extracting, staging, or persisting raw source datasets. The service retains five successful snapshots per property/catalog, serves only the latest, retains Training Run metadata and metrics for 90 days, and failed-run diagnostics for 30 days; these values are deployment-configurable.	Sponsor direction.	Replay, audit, regulatory, or operational evidence demonstrates a need for different retention or a governed raw-data store.
D-015	2026-08-05	Sponsor required V1 to qualify at a per-Catalog scale of hundreds of thousands of Products, at least 100 million view rows, at least 100 million purchase rows, and a historical window of at least two years. These are minimum qualification thresholds, not hard product limits.	Sponsor direction.	Observed production volumes or freshness requirements require a larger qualification profile.
D-016	2026-08-05	Sponsor selected a 12-hour Training Run completion objective at the qualification profile; Training submission/status p95 of at most 500 ms; Serving API p95 of at most 90 ms and p99 of at most 150 ms; 99.9% monthly Serving API availability; and 99.5% monthly Training API availability.	Sponsor direction.	Production workload evidence shows that these objectives are insufficient, infeasible, or materially inefficient.
D-017	2026-08-05	Sponsor limited co-occurrence contribution to at most 100 distinct Products per Browsing Session and 200 per Order. Oversized groups are excluded whole from co-occurrence and category-pair evidence, remain eligible for popularity and Trending counts, and are reported in Training Run metrics.	Sponsor direction; quadratic pair-growth risk.	Legitimate property behavior regularly exceeds the limits or evaluation demonstrates a less biased safe treatment.
D-018	2026-08-05	Sponsor made online purchases the required purchase input and in-store/offline purchases an optional additional input selected by each merchandiser. Both channels inform purchase-driven strategies when supplied, but Order identity remains channel-scoped.	Sponsor direction.	The commerce source cannot distinguish purchase channel or intentionally shares one cross-channel Order identity.

Product Manager to Product Owner handoff¶

Status: Not started; evaluation intent and remaining product constraints are unresolved.

Approval¶

Approved by: Sponsor (user)
Approved on: 2026-08-05
Approved scope: Revision 0.16 as the authoritative strategic intent baseline. Approval does not claim that recommendation hypotheses are validated or approve a technical design.

Change log¶

Revision/date	Material change	Reason
0.1 / 2026-08-05	Recorded initial boundary, strategies, fallback hypothesis, evidence, and decisions.	Sponsor vision discussion and technical literature review.
0.2 / 2026-08-05	Added the required evaluation standard.	Sponsor decision D-005.
0.3 / 2026-08-05	Selected six first-version Recommendation Strategies.	Sponsor decision D-006.
0.4 / 2026-08-05	Added current cold-start and cross-domain evidence plus validation questions.	Sponsor requested a review of the latest literature.
0.5 / 2026-08-05	Adopted property-local behavioral isolation and strategy-specific cold-start handling.	Sponsor decision D-007.
0.6 / 2026-08-05	Added relational database retrieval, Training API, snapshot persistence, and Serving API to the product boundary.	Sponsor decision D-008.
0.7 / 2026-08-05	Replaced the single-engine assumption with an engine-agnostic Data Source Adapter contract.	Sponsor decision D-009.
0.8 / 2026-08-05	Added configurable canonical relational reads and `TRACKING_ID` partitioning for Offline Purchases.	Sponsor decision D-010.
0.9 / 2026-08-05	Added composite Commerce Property and Item identities using data source, Tracking ID, Catalog ID, and Product ID.	Sponsor decision D-011.
0.10 / 2026-08-05	Made Catalog ID a hard recommendation boundary.	Sponsor decision D-012.
0.11 / 2026-08-05	Added mandatory Order ID and Browsing Session ID grouping contracts.	Sponsor decision D-013.
0.12 / 2026-08-05	Required direct streaming reads with no raw-data extraction or staging, and approved operational retention defaults.	Sponsor decision D-014.
0.13 / 2026-08-05	Established the minimum per-Catalog capacity qualification profile.	Sponsor decision D-015.
0.14 / 2026-08-05	Established Training Run completion, API latency, and availability objectives.	Sponsor decision D-016.
0.15 / 2026-08-05	Bounded co-occurrence group size and defined observable oversized-group treatment.	Sponsor decision D-017.
0.16 / 2026-08-05	Made in-store/offline purchases optional alongside required online purchases and separated Order identity by Purchase Channel.	Sponsor decision D-018.