Skip to content

Embedded ANN specifications

These specifications capture the user-confirmed ANN scope and distinguish the default-off implementation from the still-open production qualification gates.

Confirmed scope

Both Similar Items and For You; embedded deployment; maintained ANN library rather than a custom algorithm; Apple Silicon optimization preferred. The later user request adds a default-off PyTorch two-tower training option, documented in the implementation. For You may discover eligible Items across its published Catalog. Metadata-derived vectors and bounded authorized Shopper Profile queries are the baseline to evaluate. Indexes refresh with successful snapshot publication; acknowledged interactions may change queries between runs.

Decision gates

The Wayfinder map retains decisions on vector representation, quality/resource thresholds, artifact lifecycle and final library/index choice. The specification issues use native blocking relationships and the required ready-for-agent label; that label does not override those gates. Specifications are related to the map, not decision-ticket children, keeping the decision frontier distinct.

Faiss CPU HNSW is the first implemented, pinned candidate, not a qualified production index. The installed Apple Silicon wheel exposes a Metal GPU bridge in addition to CPU optimizations, but the GPU index did not enforce a native Item-ID selector in a small runtime check. A serving path using that bridge would need a separately proven way to enforce eligibility.

Initial implementation evidence: the pinned Faiss 1.15.1 faiss-cpu wheel imports on the local M2 Pro with Python 3.14 and NumPy 2. Its runtime compile options report ARM_NEON and MAC_METAL, get_num_gpus() returns one, and the generic GPU bridge successfully searched a small Flat index. The earlier research note predates this runtime check and is superseded on Metal availability. The benchmark below uses CPU Flat and HNSW only. The synthetic native-index experiment in the testing guide now measures Flat versus HNSW, including concurrency, fresh-process load and selective-filter underfill. A smoke Catalog projection experiment separately measures dense representation drift. Commerce relevance of the SVD representation, complete Serving API latency and qualification remain open.

Verification and handoff

The default-off implementation adds source, dependency, schema and runtime seams; it does not approve broad production enablement. Separate experimental benchmark code and evidence are documented in the ANN experiment report. Check these documents with make docs-check and git diff --check; experiment verification is reported separately and does not approve production use. The implementation and governing documentation now record the selected baseline candidate and fallback behavior. Qualifying the representation and index remains separate work.