Embedding Similarity Playground methodology

Version 2026-09-07 · Primary-source ledger: JSON · The three named diagrams are licensed by Kingy.ai under CC BY 4.0.

# Embedding Similarity Playground

Edit a query and three candidate vectors. Watch magnitude change dot-product rankings, then normalize the geometry.

## Run locally

Open `index.html` directly, or run `python3 -m http.server 4190 --bind 127.0.0.1` from this folder and visit http://127.0.0.1:4190/. No package manager, compilation, third-party runtime, account, telemetry, or remote request is needed.

## Model and boundaries

These are synthetic 2D vectors, not learned language embeddings. Position has no assigned semantic meaning. Cosine and unit normalization are undefined for the zero vector; undefined comparisons are excluded from those rankings.

- **cosine:** `(Q·X)/(||Q||*||X||), for nonzero vectors`
- **dot:** `Qx*Xx + Qy*Xy; larger ranks first`
- **distance:** `sqrt((Qx-Xx)^2+(Qy-Xy)^2); smaller ranks first`
- **normalize:** `v/||v||; zero vector is undefined`
- **unit_identity:** `For unit vectors, squared Euclidean distance = 2 - 2*cosine`

### Teaching assumptions

- All examples are geometric teaching coordinates in [-10,10], with no trained encoder or corpus.
- Normalization applies to query and all candidates.
- Ties use absolute tolerance 1e-10; undefined results are excluded.
- Raw zero-vector dot products and Euclidean distances remain defined.

## Presets and operation

Select a preset, edit the controls, and inspect the output. Invalid input displays an error and disables exports rather than silently substituting values. Reset restores the selected example. Each preset is a complete state and includes provenance in `presets.json`, dated 2026-09-07. The local `config.js` embeds identical catalog and source data so the page also works from disk; validation checks that it matches the JSON. Update those together with the generation source.

## Primary-source ledger

- **E1: Cosine is normalized dot product.** The scikit-learn cosine similarity definition divides dot product by the two L2 norms; it equals the linear kernel on L2-normalized data. [primary-documentation](https://scikit-learn.org/stable/modules/generated/sklearn.metrics.pairwise.cosine_similarity.html). Checked 2026-09-07. Boundary: This demo uses mathematical undefined for zero vectors rather than the library’s zero-fill convention.
- **E2: Unit normalization removes magnitude.** L2 normalization rescales each nonzero vector to unit norm. [primary-documentation](https://scikit-learn.org/stable/modules/generated/sklearn.preprocessing.Normalizer.html). Checked 2026-09-07. Boundary: Magnitude may contain useful information in a real model; normalization is not universally appropriate.

## Independently reusable assets

| Diagram | Editable source | 2400×1350 raster | Use |
| --- | --- | --- | --- |
| Three definitions of near | [SVG](assets/metric-geometry.svg) | [PNG](assets/png/metric-geometry.png) | Dot product, cosine, and distance use different geometry. |
| What normalization removes | [SVG](assets/normalization.svg) | [PNG](assets/png/normalization.png) | The unit circle keeps direction and discards magnitude. |
| One query, two winners | [SVG](assets/ranking-flip.svg) | [PNG](assets/png/ranking-flip.png) | A hand-checkable example of conflicting rankings. |

SVGs contain editable text and vector geometry with system-font fallbacks. Kingy may reuse the original assets internally and in its own editorial work; no public redistribution license has been assigned. Source links and attribution policy need to be settled before external distribution. The diagrams are teaching artifacts, not screenshots of hardware or measurements.

## Exports

CSV flattens nested keys into field/value rows. JSON preserves the complete typed object, including topic, schema version, generated time, preset date, inputs, results, formulas, assumptions, and methodology/source paths. Undefined mathematical results are JSON null and CSV `null`. Examples under `exports/` were downloaded from the browser controls and parsed during QA.

## Worked expected result

Q=(1,0), A=(2,1), B=(0.8,0), C=(-1,1): raw dot [2,0.8,-1]; cosine [2/sqrt(5),1,-1/sqrt(2)]; distance [sqrt(2),0.2,sqrt(5)]. Raw winners: dot A, cosine B, distance B. Normalized winners: B for all. Zero query: cosine undefined for all; raw dot is zero for all; raw distances remain defined.

## Source map

`index.html` contains the accessible page and explanation; `styles.css` the standalone visual shell; `common.js` input validation and exports; `config.js` the local catalog; `app.js` the topic-specific computation and rendering. `sources.json` and `presets.json` are portable ledgers. `VALIDATION.md` and `output/playwright/` record QA. Authoring source is retained in the companion production kit after season completion.