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.