# Product Embedding Explorer: local API contract

Served on loopback (`127.0.0.1:8765`). FastAPI publishes the machine-readable
contract at `/openapi.json` and interactive documentation at `/docs`.

## GET /api/status

200: `{ "models": ["product-type", "fine-tuned", "base"], "default_model": "product-type",
"device": "cpu", "max_products": 300 }`. `fine-tuned` is only listed when a
completed local model exists. Base weights must already be cached; the web server
never downloads models and never starts training.
`product-type` is listed and selected by default only when its local checkpoint
and a completed `validated.json` training/evaluation marker are present. This is
the graded product-function model. `fine-tuned` retains the original identity
model meaning for compatibility with existing clients.

## POST /api/embed

Request: `{ "products": ["Samsung Galaxy S8", "Case for Samsung S8"],
"model": "fine-tuned", "method": "pca", "include_embeddings": false }`.

- 2–300 nonempty product strings, at most 1,000 characters per string.
- `model`: `product-type`, `fine-tuned`, or `base`; `method`: `pca` or `tsne`.
- Input limit: 96 tokens for `product-type`, 128 for the other two checkpoints.
  The historical request default remains `fine-tuned`; the UI sends the explicitly
  selected model and follows the status endpoint's preferred available model.
- t-SNE needs at least four products. PCA supports two or three by padding zero
  axes. Both operate on normalized full-dimensional embeddings.
- Duplicates remain separate entries and may have overlapping coordinates.

200 response:

```
{
  "model": "fine-tuned", "embedding_dimensions": 768,
  "projection": {"method": "pca", "explained_variance": 0.72,
    "warning": "3D projection distorts distances; compare cosine similarity."},
  "products": [{"id": 0, "text": "...", "xyz": [0.1, -0.2, 0.3],
    "nearest": [{"id": 1, "similarity": 0.91}]}],
  "similarities": [[1.0, 0.91], [0.91, 1.0]],
  "embeddings": null
}
```

`embeddings` contains the normalized vectors only if requested. Coordinates are
centered. PCA coordinates retain the Euclidean scale of normalized embeddings;
they are not expanded to fit a fixed radius. For two to four products, PCA can
retain the complete centered vector span, preserving pairwise Euclidean distance
(equal to `sqrt(2 * (1 - cosine_similarity))`). Larger lists can lose distance
information in three dimensions. t-SNE has arbitrary layout units and is scaled
to unit radius for display; its spacing is not comparable between submissions.
`nearest` excludes self and contains up to five neighbors measured in original
embedding space.

Errors: 422 invalid input; 503 model/checkpoint unavailable; 500 inference failure.
Client displays errors and retains the last successful visualization. No product
text is sent to an external service or stored by the endpoint.