Embedding Losses Mining

---
name: embedding-losses-mining
description: "Routes embedding-network, contrastive-loss, triplet-loss, and
  online mining tasks for the Siamese-triplet repository."
metadata:
  disco-role: operating
disable-model-invocation: true
license: BSD 3-Clause
---

# Embedding, Losses, and Mining

Use this sub-skill when the task is about the repository's embedding backbone, the siamese and triplet wrappers, the contrastive or triplet losses, or the pair/triplet selection helpers used for online mining.

## Covered surface

- `EmbeddingNet`
- `EmbeddingNetL2`
- `ClassificationNet`
- `SiameseNet`
- `TripletNet`
- `ContrastiveLoss`
- `TripletLoss`
- `OnlineContrastiveLoss`
- `OnlineTripletLoss`
- `PairSelector` and `TripletSelector` implementations

## When to route here

Read this sub-skill for tasks that mention:

- image embeddings
- Siamese or triplet networks
- contrastive or triplet margin losses
- hard negative mining
- pair or triplet selectors
- online contrastive or online triplet learning
- 2D embedding backbones and post-backbone classification heads

## What to do first

1. Read `references/api-reference.md` for shapes and return values.
2. Read `references/troubleshooting.md` if a selector or loss returns empty results.
3. Run `scripts/check_losses_networks.py` for a tiny no-download smoke.

## Evidence signals

- Source evidence comes from `networks.py`, `losses.py`, `utils.py`, README loss descriptions, and the notebook training cells.
- The surface is pure PyTorch; CPU verification covers the selected behavior, while CUDA is an optional acceleration path.
- The smoke script checks object construction, tensor shapes, selector outputs, and online-loss return contracts.

## Short workflow

- Instantiate `EmbeddingNet` and verify that it maps `1×28×28` images to a 2D embedding.
- Wrap the backbone with `ClassificationNet`, `SiameseNet`, or `TripletNet` depending on the downstream loss.
- Choose the loss:
  - `ContrastiveLoss` for pairwise same/different supervision
  - `TripletLoss` for explicit anchor/positive/negative supervision
  - `OnlineContrastiveLoss` or `OnlineTripletLoss` when mining pairs or triplets inside a mini-batch
- For online mining, pair the loss with a selector that matches the batch structure and label density.

## Decision points

- Use `EmbeddingNetL2` if normalized embeddings are important.
- Use `ClassificationNet` only when the task is ordinary classification rather than metric learning.
- Use `HardNegativePairSelector` when you want the hardest negative pairs from a batch.
- Use one of the triplet selector factories when you want exhaustive, random hard, or semi-hard negative mining.
- Keep the margin the same between the loss and the selector strategy unless the reference explicitly says otherwise.

## Common failure modes

- The selector sees too few examples per class and cannot mine meaningful pairs or triplets.
- The code assumes CPU-friendly selector logic, so large batches can become expensive even when the backbone is on GPU.
- `OnlineTripletLoss` returns `(loss, num_triplets)`, which is easy to misuse if a caller expects a plain tensor.
- `EmbeddingNetL2` divides by the norm without an epsilon guard.

## Acceptance checks

- Network wrappers produce outputs with the expected arity.
- Direct losses return scalar tensors.
- Online contrastive loss returns a scalar tensor.
- Online triplet loss returns a scalar tensor plus a mined-triplet count.
- Selector fixtures contain at least two samples per class.

## Read next

- `references/api-reference.md` for the module and selector map.
- `references/troubleshooting.md` for CPU/GPU and empty-mining issues.
- `../dataset-sampling/SKILL.md` if the next step is a wrapper or sampler problem.
- `../training-experiments/SKILL.md` if the next step is a fit-loop or notebook workflow check.