| # 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. |
|
|
