mantissa-embed 0.1.0__tar.gz

mantissa_embed-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tekin Ertekin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mantissa_embed-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mantissa-embed
+Version: 0.1.0
+Summary: CNN metric learning on the mantissa C engine: image embeddings for similarity, verification and retrieval
+Author: Tekin Ertekin
+License: MIT
+Project-URL: Homepage, https://github.com/tekinertekin/mantissa-embed
+Project-URL: Base, https://github.com/tekinertekin/mantissa-cnn
+Project-URL: Engine, https://github.com/tekinertekin/mantissa
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: mantissa-cnn>=0.2.2
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# mantissa-embed
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.9%2B-3776AB.svg)
+[![Base](https://img.shields.io/badge/base-mantissa--cnn-4B8BBE.svg)](https://github.com/tekinertekin/mantissa-cnn)
+[![Engine](https://img.shields.io/badge/engine-mantissa-00599C.svg)](https://github.com/tekinertekin/mantissa)
+
+**Learning what "similar" means, with a C engine.** A classifier answers *which
+class*; an embedder answers *how alike* — it maps each image to a point in a
+vector space where same-thing images land close together and different-thing
+images land far apart. That single geometry powers similarity search,
+verification ("are these two the same?") and retrieval ("show me the nearest
+matches"), for classes the model was never trained to name.
+
+`mantissa-embed` trains that embedding with **metric learning** — the
+contrastive and triplet losses — on top of a
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) trunk: its
+Conv2D / MaxPool2D / Flatten / Dense layers, its
+[mantissa](https://github.com/tekinertekin/mantissa) C-engine and pure-numpy
+backends, and its dataset loaders are reused, not reimplemented. This package
+adds only what metric learning needs on top of a classifier: the two losses,
+an `Embedder` that trains a trunk with them, and the four things embeddings buy
+you — `fit` / `embed` / `retrieve` / `verify`.
+
+## The mantissa family
+
+Part of the **mantissa** family: a low-precision engine written in C, with
+small Python packages built on top. Each package sits under the one it depends
+on — ⭐ marks where you are, and every other name links to its repo.
+
+- [mantissa](https://github.com/tekinertekin/mantissa) — low-precision neural-network engine in C (the core)
+  - [mantissa-perceptron](https://github.com/tekinertekin/mantissa-perceptron) — perceptron & ADALINE, the linear classics
+  - [mantissa-nn](https://github.com/tekinertekin/mantissa-nn) — shared neural-net primitives (layers, engine binding)
+    - [mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) — convolutional networks for images
+      - [mantissa-auto-encoder](https://github.com/tekinertekin/mantissa-auto-encoder) — autoencoders for denoising & super-resolution
+      - [mantissa-interpret](https://github.com/tekinertekin/mantissa-interpret) — CNN interpretability (occlusion, saliency, Grad-CAM)
+      - ⭐ **mantissa-embed** — CNN metric learning (image embeddings for similarity & retrieval) *(you are here)*
+    - [mantissa-mlp](https://github.com/tekinertekin/mantissa-mlp) — multilayer perceptrons, fully-connected nets
+
+
+## New to metric learning?
+
+A classifier learns a fixed set of labels and a decision boundary between them.
+Metric learning learns something more basic and more reusable: a **distance**.
+It trains the network so that the Euclidean distance between two images'
+embeddings *is* a measure of how similar they are — and it does that using only
+the relation between examples ("these two are the same kind", "these two are
+not"), never a class *name*. Two consequences follow:
+
+- **It generalizes to classes it never trained on.** Because the loss only ever
+  says "closer" or "farther", a model trained on some identities produces useful
+  distances for identities it has never seen — the basis of face verification,
+  where you cannot retrain for every new person.
+- **One embedding serves many tasks.** Compute it once per image, then:
+  *verify* by thresholding a distance, *retrieve* by nearest-neighbour search,
+  *cluster* by feeding the vectors to any clustering method.
+
+Two classic losses do the training, and this package implements both:
+
+- **Contrastive loss** works on **pairs**. A same-class pair pays its squared
+  distance (pulled together); a different-class pair pays a hinge that is zero
+  once the pair is at least a `margin` apart (pushed apart, but only until far
+  enough) — Hadsell, Chopra & LeCun (2006), "Dimensionality Reduction by
+  Learning an Invariant Mapping", *CVPR*.
+- **Triplet loss** works on **triples** of (anchor, positive, negative). It asks
+  only that the negative be farther from the anchor than the positive, by at
+  least a `margin` — a *relative* constraint, which is often easier to satisfy
+  and to scale than pinning absolute distances — Schroff, Kalenichenko &
+  Philbin (2015), "FaceNet: A Unified Embedding for Face Recognition and
+  Clustering", *CVPR*.
+
+**A Siamese/triplet network is just one network run more than once.** The two
+legs of a pair (or three of a triplet) share the *same* weights, so there is no
+second network to manage: stack the legs into one batch, run a single forward
+pass, compute the loss and its per-row gradient on the resulting embeddings,
+and backpropagate that gradient through the one trunk. That is exactly what
+`Embedder.fit` does — the same custom forward/loss/backward loop the rest of the
+family uses, with a metric loss where the classifier's softmax would be.
+
+## Install
+
+```sh
+pip install mantissa-embed
+```
+
+Pulls in `mantissa-cnn >= 0.2.2` (and transitively `mantissa-nn` + the
+`mantissa-core` engine). For the demo's plots, `pip install mantissa-embed[viz]`.
+
+From checkouts (works today, no PyPI needed): clone this repo, `cnn`,
+`mantissa-nn` and [mantissa](https://github.com/tekinertekin/mantissa) side by
+side, build the engine (`make dist` there), then here:
+
+```sh
+pip install -e ../mantissa -e ../mantissa-nn -e ../cnn && pip install -e ".[viz]"
+```
+
+mantissa-cnn finds the sibling engine checkout automatically, and its dataset
+loaders find a `data/` directory via `MANTISSA_CNN_DATA` (the demo points this
+at the sibling `cnn/data/` for you).
+
+## Quickstart
+
+```sh
+# datasets are mantissa-cnn's; nothing downloads implicitly — fetch once:
+python -m mantissa_cnn.datasets download mnist
+```
+
+```python
+from mantissa_cnn import datasets
+from mantissa_embed import Embedder, models
+
+Xtr, ytr, Xte, yte = datasets.subset("mnist", 6000, 2000, seed=0)
+
+emb = Embedder(models.small_cnn_embedder(embed_dim=16), loss="triplet")  # or "contrastive"
+emb.fit(Xtr, ytr, epochs=8, batch_size=64, lr=0.05, verbose=True)
+
+Z = emb.embed(Xte)                       # (2000, 16) embedding vectors
+idx, dist = emb.retrieve(Xte[0], Z, k=5) # 5 nearest test images to query 0
+same = emb.verify(Xte[0], Xte[1], threshold=1.0)   # same identity? (bool)
+```
+
+Or compose your own trunk from mantissa-cnn's layers — any Conv/Pool/Flatten
+stack ending in `Dense(embed_dim, act="identity")`:
+
+```python
+from mantissa_cnn import Conv2D, MaxPool2D, Flatten, Dense
+from mantissa_embed import Embedder
+
+emb = Embedder(
+    [Conv2D(16, 3, pad=1), MaxPool2D(2), Flatten(), Dense(32)],  # 32-D embedding
+    loss="contrastive", margin=1.0, seed=0)
+```
+
+## The API
+
+`Embedder(layers, loss="triplet"|"contrastive", margin=None, seed=0, backend="mantissa")`,
+then:
+
+| method | does | returns |
+|---|---|---|
+| `fit(X, y, epochs, batch_size, lr, verbose)` | trains the trunk by metric learning; `y` only decides same/different | `self` (`history_["loss"]` per epoch) |
+| `embed(X)` | one forward pass, chunked | `(n, embed_dim)` embeddings |
+| `retrieve(query, gallery, k)` | k nearest gallery items in embedding space (numpy `argpartition`, no sklearn) | `(indices, distances)`, nearest-first |
+| `verify(a, b, threshold=None)` | embedding distance between `a` and `b`; with `threshold`, a boolean same/different | distance, or bool |
+
+`retrieve` and `verify` accept raw images **or** a pre-computed `(., embed_dim)`
+matrix, so a fixed gallery is embedded once and reused across queries.
+
+Deliberately minimal, like the rest of the family: NCHW float32 images, plain
+SGD, the two classic losses, plain Euclidean distances. No autograd graph, no
+optimizer zoo, no ANN index. The trunk's convolutions run in C on zero-copy
+float32 buffers; the losses are memory-bound reductions over embedding vectors
+and honestly stay in numpy (`mantissa_embed.losses`, importable and gradient-
+checked on their own). Layers allocate scratch once per batch shape and reuse
+it.
+
+## Results
+
+A `small_cnn_embedder` (52,528 params, 16-D embedding) trained on a 6k-image
+MNIST subset with the triplet loss and the mantissa C engine (8 epochs, triplet
+loss **0.090 → 0.016**), then embedding the held-out 2k test set. Reproduce with
+`python examples/embeddings_demo.py`.
+
+The embedding separates the digits with no label ever entering the loss — colour
+is the true digit, shown only for the plot:
+
+![MNIST test embeddings, 2-D PCA, coloured by true digit — visible per-digit clusters](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/embedding_manifold.png)
+
+And nearest-neighbour retrieval returns same-digit images (green border = a
+correct match, i.e. the neighbour's true digit equals the query's):
+
+![retrieval gallery: five query digits, each with its five nearest neighbours in embedding space](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/retrieval_gallery.png)
+
+## License
+
+MIT — © Tekin Ertekin. Base package:
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn); engine:
+[mantissa](https://github.com/tekinertekin/mantissa) — same author, MIT.

mantissa_embed-0.1.0/README.md

@@ -0,0 +1,178 @@
+# mantissa-embed
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.9%2B-3776AB.svg)
+[![Base](https://img.shields.io/badge/base-mantissa--cnn-4B8BBE.svg)](https://github.com/tekinertekin/mantissa-cnn)
+[![Engine](https://img.shields.io/badge/engine-mantissa-00599C.svg)](https://github.com/tekinertekin/mantissa)
+
+**Learning what "similar" means, with a C engine.** A classifier answers *which
+class*; an embedder answers *how alike* — it maps each image to a point in a
+vector space where same-thing images land close together and different-thing
+images land far apart. That single geometry powers similarity search,
+verification ("are these two the same?") and retrieval ("show me the nearest
+matches"), for classes the model was never trained to name.
+
+`mantissa-embed` trains that embedding with **metric learning** — the
+contrastive and triplet losses — on top of a
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) trunk: its
+Conv2D / MaxPool2D / Flatten / Dense layers, its
+[mantissa](https://github.com/tekinertekin/mantissa) C-engine and pure-numpy
+backends, and its dataset loaders are reused, not reimplemented. This package
+adds only what metric learning needs on top of a classifier: the two losses,
+an `Embedder` that trains a trunk with them, and the four things embeddings buy
+you — `fit` / `embed` / `retrieve` / `verify`.
+
+## The mantissa family
+
+Part of the **mantissa** family: a low-precision engine written in C, with
+small Python packages built on top. Each package sits under the one it depends
+on — ⭐ marks where you are, and every other name links to its repo.
+
+- [mantissa](https://github.com/tekinertekin/mantissa) — low-precision neural-network engine in C (the core)
+  - [mantissa-perceptron](https://github.com/tekinertekin/mantissa-perceptron) — perceptron & ADALINE, the linear classics
+  - [mantissa-nn](https://github.com/tekinertekin/mantissa-nn) — shared neural-net primitives (layers, engine binding)
+    - [mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) — convolutional networks for images
+      - [mantissa-auto-encoder](https://github.com/tekinertekin/mantissa-auto-encoder) — autoencoders for denoising & super-resolution
+      - [mantissa-interpret](https://github.com/tekinertekin/mantissa-interpret) — CNN interpretability (occlusion, saliency, Grad-CAM)
+      - ⭐ **mantissa-embed** — CNN metric learning (image embeddings for similarity & retrieval) *(you are here)*
+    - [mantissa-mlp](https://github.com/tekinertekin/mantissa-mlp) — multilayer perceptrons, fully-connected nets
+
+
+## New to metric learning?
+
+A classifier learns a fixed set of labels and a decision boundary between them.
+Metric learning learns something more basic and more reusable: a **distance**.
+It trains the network so that the Euclidean distance between two images'
+embeddings *is* a measure of how similar they are — and it does that using only
+the relation between examples ("these two are the same kind", "these two are
+not"), never a class *name*. Two consequences follow:
+
+- **It generalizes to classes it never trained on.** Because the loss only ever
+  says "closer" or "farther", a model trained on some identities produces useful
+  distances for identities it has never seen — the basis of face verification,
+  where you cannot retrain for every new person.
+- **One embedding serves many tasks.** Compute it once per image, then:
+  *verify* by thresholding a distance, *retrieve* by nearest-neighbour search,
+  *cluster* by feeding the vectors to any clustering method.
+
+Two classic losses do the training, and this package implements both:
+
+- **Contrastive loss** works on **pairs**. A same-class pair pays its squared
+  distance (pulled together); a different-class pair pays a hinge that is zero
+  once the pair is at least a `margin` apart (pushed apart, but only until far
+  enough) — Hadsell, Chopra & LeCun (2006), "Dimensionality Reduction by
+  Learning an Invariant Mapping", *CVPR*.
+- **Triplet loss** works on **triples** of (anchor, positive, negative). It asks
+  only that the negative be farther from the anchor than the positive, by at
+  least a `margin` — a *relative* constraint, which is often easier to satisfy
+  and to scale than pinning absolute distances — Schroff, Kalenichenko &
+  Philbin (2015), "FaceNet: A Unified Embedding for Face Recognition and
+  Clustering", *CVPR*.
+
+**A Siamese/triplet network is just one network run more than once.** The two
+legs of a pair (or three of a triplet) share the *same* weights, so there is no
+second network to manage: stack the legs into one batch, run a single forward
+pass, compute the loss and its per-row gradient on the resulting embeddings,
+and backpropagate that gradient through the one trunk. That is exactly what
+`Embedder.fit` does — the same custom forward/loss/backward loop the rest of the
+family uses, with a metric loss where the classifier's softmax would be.
+
+## Install
+
+```sh
+pip install mantissa-embed
+```
+
+Pulls in `mantissa-cnn >= 0.2.2` (and transitively `mantissa-nn` + the
+`mantissa-core` engine). For the demo's plots, `pip install mantissa-embed[viz]`.
+
+From checkouts (works today, no PyPI needed): clone this repo, `cnn`,
+`mantissa-nn` and [mantissa](https://github.com/tekinertekin/mantissa) side by
+side, build the engine (`make dist` there), then here:
+
+```sh
+pip install -e ../mantissa -e ../mantissa-nn -e ../cnn && pip install -e ".[viz]"
+```
+
+mantissa-cnn finds the sibling engine checkout automatically, and its dataset
+loaders find a `data/` directory via `MANTISSA_CNN_DATA` (the demo points this
+at the sibling `cnn/data/` for you).
+
+## Quickstart
+
+```sh
+# datasets are mantissa-cnn's; nothing downloads implicitly — fetch once:
+python -m mantissa_cnn.datasets download mnist
+```
+
+```python
+from mantissa_cnn import datasets
+from mantissa_embed import Embedder, models
+
+Xtr, ytr, Xte, yte = datasets.subset("mnist", 6000, 2000, seed=0)
+
+emb = Embedder(models.small_cnn_embedder(embed_dim=16), loss="triplet")  # or "contrastive"
+emb.fit(Xtr, ytr, epochs=8, batch_size=64, lr=0.05, verbose=True)
+
+Z = emb.embed(Xte)                       # (2000, 16) embedding vectors
+idx, dist = emb.retrieve(Xte[0], Z, k=5) # 5 nearest test images to query 0
+same = emb.verify(Xte[0], Xte[1], threshold=1.0)   # same identity? (bool)
+```
+
+Or compose your own trunk from mantissa-cnn's layers — any Conv/Pool/Flatten
+stack ending in `Dense(embed_dim, act="identity")`:
+
+```python
+from mantissa_cnn import Conv2D, MaxPool2D, Flatten, Dense
+from mantissa_embed import Embedder
+
+emb = Embedder(
+    [Conv2D(16, 3, pad=1), MaxPool2D(2), Flatten(), Dense(32)],  # 32-D embedding
+    loss="contrastive", margin=1.0, seed=0)
+```
+
+## The API
+
+`Embedder(layers, loss="triplet"|"contrastive", margin=None, seed=0, backend="mantissa")`,
+then:
+
+| method | does | returns |
+|---|---|---|
+| `fit(X, y, epochs, batch_size, lr, verbose)` | trains the trunk by metric learning; `y` only decides same/different | `self` (`history_["loss"]` per epoch) |
+| `embed(X)` | one forward pass, chunked | `(n, embed_dim)` embeddings |
+| `retrieve(query, gallery, k)` | k nearest gallery items in embedding space (numpy `argpartition`, no sklearn) | `(indices, distances)`, nearest-first |
+| `verify(a, b, threshold=None)` | embedding distance between `a` and `b`; with `threshold`, a boolean same/different | distance, or bool |
+
+`retrieve` and `verify` accept raw images **or** a pre-computed `(., embed_dim)`
+matrix, so a fixed gallery is embedded once and reused across queries.
+
+Deliberately minimal, like the rest of the family: NCHW float32 images, plain
+SGD, the two classic losses, plain Euclidean distances. No autograd graph, no
+optimizer zoo, no ANN index. The trunk's convolutions run in C on zero-copy
+float32 buffers; the losses are memory-bound reductions over embedding vectors
+and honestly stay in numpy (`mantissa_embed.losses`, importable and gradient-
+checked on their own). Layers allocate scratch once per batch shape and reuse
+it.
+
+## Results
+
+A `small_cnn_embedder` (52,528 params, 16-D embedding) trained on a 6k-image
+MNIST subset with the triplet loss and the mantissa C engine (8 epochs, triplet
+loss **0.090 → 0.016**), then embedding the held-out 2k test set. Reproduce with
+`python examples/embeddings_demo.py`.
+
+The embedding separates the digits with no label ever entering the loss — colour
+is the true digit, shown only for the plot:
+
+![MNIST test embeddings, 2-D PCA, coloured by true digit — visible per-digit clusters](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/embedding_manifold.png)
+
+And nearest-neighbour retrieval returns same-digit images (green border = a
+correct match, i.e. the neighbour's true digit equals the query's):
+
+![retrieval gallery: five query digits, each with its five nearest neighbours in embedding space](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/retrieval_gallery.png)
+
+## License
+
+MIT — © Tekin Ertekin. Base package:
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn); engine:
+[mantissa](https://github.com/tekinertekin/mantissa) — same author, MIT.

mantissa_embed-0.1.0/mantissa_embed/__init__.py

@@ -0,0 +1,31 @@
+"""mantissa-embed: CNN metric learning on the mantissa C engine, built on
+mantissa-nn and mantissa-cnn.
+
+>>> from mantissa_embed import Embedder, models
+>>> from mantissa_cnn import datasets
+>>> Xtr, ytr, Xte, yte = datasets.subset("mnist", 4000, 1000, seed=0)
+>>> emb = Embedder(models.small_cnn_embedder(embed_dim=16), loss="triplet")
+>>> emb.fit(Xtr, ytr, epochs=5, batch_size=64, lr=0.05)
+>>> idx, dist = emb.retrieve(Xte[0], Xte[1:], k=5)   # 5 nearest neighbours
+
+The shared base (Dense/Flatten layers, both backends) comes from mantissa-nn;
+the convolution and pooling layers and the image datasets come from
+mantissa-cnn. This package adds the metric losses (contrastive, triplet), an
+``Embedder`` that trains a trunk with them, and a small-CNN trunk factory. The
+public API is fit / embed / retrieve / verify — similarity, retrieval and
+verification from learned image embeddings.
+"""
+try:
+    import mantissa_cnn  # noqa: F401  (Conv2D/MaxPool2D; pulls the mantissa-nn base)
+except ImportError:
+    raise ImportError(
+        "mantissa-cnn is not installed — run: pip install mantissa-cnn"
+    ) from None
+
+from .losses import contrastive_loss_grad, triplet_loss_grad
+from .model import Embedder
+from . import models
+
+__version__ = "0.1.0"
+__all__ = ["Embedder", "contrastive_loss_grad", "triplet_loss_grad",
+           "models", "__version__"]

mantissa_embed-0.1.0/mantissa_embed/losses.py

@@ -0,0 +1,81 @@
+"""Metric-learning losses, computed in numpy: contrastive and triplet.
+
+Both are memory-bound elementwise reductions over a batch of embeddings — one
+subtract, one square-sum per row — so numpy is the right tool; the convolution
+trunk that produced the embeddings still runs in the C engine (see
+:mod:`mantissa_embed.model`). Each returns the scalar loss and the per-row
+gradient(s) of that loss w.r.t. its embedding input(s), already scaled by
+1/batch so one learning rate works regardless of how many pairs/triplets a
+batch forms.
+
+Convention: distances are plain Euclidean. Contrastive uses the distance
+itself; triplet uses the squared distance, following each paper.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+__all__ = ["contrastive_loss_grad", "triplet_loss_grad"]
+
+_EPS = np.float32(1e-8)
+
+
+def contrastive_loss_grad(Za, Zb, same, margin: float = 1.0):
+    """Contrastive loss over a batch of pairs (Hadsell, Chopra & LeCun, 2006,
+    "Dimensionality Reduction by Learning an Invariant Mapping", CVPR).
+
+    For each pair with Euclidean distance ``d = ||Za - Zb||``:
+    similar pairs (``same == 1``) pay ``d**2``; dissimilar pairs pay
+    ``max(margin - d, 0)**2`` — pulled together, or pushed apart until at
+    least ``margin`` away. Returns ``(loss, dZa, dZb)``; ``dZb == -dZa`` since
+    the loss sees only the difference ``Za - Zb``.
+    """
+    Za = np.asarray(Za, dtype=np.float32)
+    Zb = np.asarray(Zb, dtype=np.float32)
+    same = np.asarray(same, dtype=np.float32).reshape(-1, 1)
+    n = Za.shape[0]
+
+    diff = Za - Zb                                   # (n, d)
+    d = np.sqrt(np.sum(diff * diff, axis=1, keepdims=True) + _EPS)   # (n, 1)
+    hinge = np.maximum(margin - d, 0.0)              # dissimilar push term
+
+    per = same * (d * d) + (1.0 - same) * (hinge * hinge)
+    loss = float(np.sum(per)) / n
+
+    # d(d**2)/dZa = 2*diff ; d(hinge**2)/dZa = -2*hinge*diff/d (when hinge>0)
+    g = same * 2.0 * diff - (1.0 - same) * 2.0 * hinge * diff / d
+    dZa = (g / n).astype(np.float32)
+    return loss, dZa, -dZa
+
+
+def triplet_loss_grad(Za, Zp, Zn, margin: float = 0.2):
+    """Triplet loss over a batch of (anchor, positive, negative) triples
+    (Schroff, Kalenichenko & Philbin, 2015, "FaceNet: A Unified Embedding for
+    Face Recognition and Clustering", CVPR).
+
+    With squared Euclidean distances ``d_ap = ||Za - Zp||**2`` and
+    ``d_an = ||Za - Zn||**2``, each triple pays
+    ``max(d_ap - d_an + margin, 0)`` — the anchor is pulled toward its
+    positive and pushed off its negative until the negative is at least
+    ``margin`` farther than the positive. Non-violating triples contribute no
+    loss and no gradient. Returns ``(loss, dZa, dZp, dZn)``.
+    """
+    Za = np.asarray(Za, dtype=np.float32)
+    Zp = np.asarray(Zp, dtype=np.float32)
+    Zn = np.asarray(Zn, dtype=np.float32)
+    n = Za.shape[0]
+
+    d_ap = np.sum((Za - Zp) ** 2, axis=1, keepdims=True)
+    d_an = np.sum((Za - Zn) ** 2, axis=1, keepdims=True)
+    viol = d_ap - d_an + margin
+    active = (viol > 0.0).astype(np.float32)         # (n, 1)
+    loss = float(np.sum(np.maximum(viol, 0.0))) / n
+
+    # gradients of (d_ap - d_an) on active rows, scaled by 1/n:
+    #   dZa = 2(Za-Zp) - 2(Za-Zn) = 2(Zn-Zp)
+    #   dZp = -2(Za-Zp) ;  dZn =  2(Za-Zn)
+    s = (active * (2.0 / n)).astype(np.float32)
+    dZa = s * (Zn - Zp)
+    dZp = s * (Zp - Za)
+    dZn = s * (Za - Zn)
+    return loss, dZa.astype(np.float32), dZp.astype(np.float32), dZn.astype(np.float32)

mantissa_embed-0.1.0/mantissa_embed/model.py

@@ -0,0 +1,299 @@
+"""Embedder: a CNN trunk trained by metric learning (contrastive / triplet).
+
+Same custom training loop as the rest of the family (mantissa_cnn.Sequential,
+mantissa_autoencoder.Autoencoder), with the classifier/regression head swapped
+for a metric loss over embeddings:
+
+- Shuffled mini-batches (seeded ``np.random.default_rng``), plain SGD.
+- Each batch forms pairs (contrastive) or triplets (triplet) from the labels,
+  then uses the family's one clean trick: the two/three legs of every
+  pair/triplet are STACKED into a single batch, pushed through the trunk in
+  ONE forward pass, the loss + per-row gradient are computed in numpy (see
+  :mod:`mantissa_embed.losses`), and that gradient is seeded straight into the
+  backward chain — one backward, then ``step`` every layer. No second forward,
+  no shared-weight bookkeeping: a Siamese/triplet network is just one network
+  run on a stacked batch.
+- The trunk's convolutions run in the C engine (or the numpy backend); only
+  the metric loss — a memory-bound reduction over embedding vectors — is numpy.
+
+Data contract: X is NCHW float32 (the datasets module gives [0, 1]); y is
+integer class ids, used only to decide which samples are "same" and which are
+"different" — the embedding itself is trained without ever seeing a class
+*name*, which is the point of metric learning.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from mantissa_nn import _numpy_backend
+from mantissa_cnn._engine import cnn_engine   # CNN feature gate: the trunk uses Conv2D
+
+from .losses import contrastive_loss_grad, triplet_loss_grad
+
+__all__ = ["Embedder"]
+
+_DEFAULT_MARGIN = {"triplet": 0.2, "contrastive": 1.0}
+
+
+class Embedder:
+    """A convolutional trunk that maps images to embedding vectors, trained so
+    that same-class images land close and different-class images land far.
+
+    Parameters
+    ----------
+    layers : list of Layer
+        A Conv2D/MaxPool2D/Flatten/Dense trunk ending in
+        ``Dense(embed_dim, act="identity")`` — see
+        :func:`mantissa_embed.models.small_cnn_embedder`.
+    loss : {"triplet", "contrastive"}
+        The metric objective. "triplet" (FaceNet) forms (anchor, positive,
+        negative) triples; "contrastive" (Hadsell-Chopra-LeCun) forms
+        same/different pairs.
+    margin : float, optional
+        Loss margin. Defaults to 0.2 for triplet, 1.0 for contrastive.
+    seed : int
+        Seeds one rng stream for weight init, epoch shuffling and pair/triplet
+        sampling — two models with the same seed and backend train identically.
+    backend : {"mantissa", "numpy"}
+        "mantissa" (default) requires the C engine and raises
+        ImportError/RuntimeError with the exact fix otherwise.
+
+    Fitted attributes
+    -----------------
+    history_ : dict with "loss" (per-epoch mean training loss).
+    embed_dim_ : embedding width, i.e. the trunk's output size, after build().
+    """
+
+    def __init__(self, layers, loss: str = "triplet", margin=None,
+                 seed: int = 0, backend: str = "mantissa"):
+        if loss not in _DEFAULT_MARGIN:
+            raise ValueError(f"loss must be 'triplet' or 'contrastive', got {loss!r}")
+        if backend == "mantissa":
+            tk = cnn_engine()                 # raises with the exact fix
+            # mantissa >= 0.2.2: a per-model Session memoizes each buffer's
+            # ctypes pointer by identity. Same signatures; older engines just
+            # take the plain methods.
+            self._backend = tk.session() if hasattr(tk, "session") else tk
+        elif backend == "numpy":
+            self._backend = _numpy_backend
+        else:
+            raise ValueError(f"backend must be 'mantissa' or 'numpy', got {backend!r}")
+        self.backend = backend
+        self.layers = list(layers)
+        self.loss = loss
+        self.margin = float(margin) if margin is not None else _DEFAULT_MARGIN[loss]
+        self.seed = int(seed)
+        self._rng = np.random.default_rng(self.seed)
+        self._built = False
+
+    # -- construction ---------------------------------------------------------
+
+    def build(self, in_shape):
+        """Initialize parameters for input shape (c, h, w). Called by fit()
+        automatically; call it yourself to inspect summary() before training."""
+        shape = tuple(int(d) for d in in_shape)
+        self.in_shape_ = shape
+        for layer in self.layers:
+            shape = layer.build(shape, self._rng)
+        if len(shape) != 1:
+            raise ValueError(f"embedder output must be a flat vector, got shape "
+                             f"{shape} — end the trunk with Flatten()/Dense(embed_dim)")
+        self.embed_dim_ = shape[0]
+        self._built = True
+        return self
+
+    def summary(self) -> str:
+        """Per-layer output shapes and parameter counts (build() first)."""
+        if not self._built:
+            raise RuntimeError("summary() needs parameters — call build(in_shape) or fit() first")
+        rows = [(type(l).__name__, str(l.out_shape), l.param_count())
+                for l in self.layers]
+        total = sum(r[2] for r in rows)
+        w = max(len(r[0]) for r in rows)
+        lines = [f"{'layer':<{w}}  {'out shape':<16}  params",
+                 "-" * (w + 26)]
+        lines += [f"{name:<{w}}  {shape:<16}  {p:,}" for name, shape, p in rows]
+        lines.append(f"embedding dim: {self.embed_dim_}")
+        lines.append(f"total params: {total:,}")
+        return "\n".join(lines)
+
+    # -- training -------------------------------------------------------------
+
+    def fit(self, X, y, epochs: int = 10, batch_size: int = 32,
+            lr: float = 0.01, verbose: bool = False):
+        """Train the embedding by metric learning on labeled images.
+
+        Labels ``y`` are used only to sample same/different pairs (contrastive)
+        or (anchor, positive, negative) triples (triplet) — one pair/triple per
+        anchor per batch, sampled from the whole training set.
+        """
+        X = self._check(X, name="X")
+        y = np.ascontiguousarray(y, dtype=np.int64).ravel()
+        n = len(X)
+        if len(y) != n:
+            raise ValueError(f"X has {n} samples but y has {len(y)}")
+        if not self._built:
+            self.build(X.shape[1:])
+
+        classes = np.unique(y)
+        if len(classes) < 2:
+            raise ValueError("metric learning needs at least 2 classes in y")
+        pos_pool = {int(c): np.flatnonzero(y == c) for c in classes}
+        neg_pool = {int(c): np.flatnonzero(y != c) for c in classes}
+        for c in classes:
+            if len(pos_pool[int(c)]) < 2:
+                raise ValueError(f"class {int(c)} has <2 samples — cannot form a "
+                                 f"positive pair")
+
+        backend = self._backend
+        layers = self.layers
+        bs = min(int(batch_size), n)
+        self.history_ = {"loss": []}
+
+        for epoch in range(int(epochs)):
+            order = self._rng.permutation(n)
+            loss_sum = 0.0
+            count = 0
+            for start in range(0, n, bs):
+                a_idx = order[start:start + bs]
+                ya = y[a_idx]
+                pos = self._sample(pos_pool, ya, classes)
+                neg = self._sample(neg_pool, ya, classes)
+
+                if self.loss == "triplet":
+                    batch = np.concatenate([X[a_idx], X[pos], X[neg]])
+                    Z = self._forward(batch, layers, backend)
+                    t = len(a_idx)
+                    loss, dZa, dZp, dZn = triplet_loss_grad(
+                        Z[:t], Z[t:2 * t], Z[2 * t:], self.margin)
+                    dZ = np.concatenate([dZa, dZp, dZn])
+                else:  # contrastive
+                    same = (self._rng.random(len(a_idx)) < 0.5)
+                    b_idx = np.where(same, pos, neg)
+                    batch = np.concatenate([X[a_idx], X[b_idx]])
+                    Z = self._forward(batch, layers, backend)
+                    p = len(a_idx)
+                    loss, dZa, dZb = contrastive_loss_grad(
+                        Z[:p], Z[p:], same, self.margin)
+                    dZ = np.concatenate([dZa, dZb])
+
+                grad = np.ascontiguousarray(dZ, dtype=np.float32)
+                for i in range(len(layers) - 1, -1, -1):
+                    grad = layers[i].backward(grad, backend, need_dx=i > 0)
+                for layer in layers:           # after ALL grads: dX of layer i
+                    layer.step(backend, lr)    # depends on its pre-step params
+
+                loss_sum += loss * len(a_idx)
+                count += len(a_idx)
+
+            self.history_["loss"].append(loss_sum / count)
+            if verbose:
+                print(f"epoch {epoch + 1}/{epochs}  "
+                      f"loss {self.history_['loss'][-1]:.6f}")
+        return self
+
+    def _sample(self, pool, ya, classes):
+        """One index per anchor drawn (with replacement) from ``pool[label]``
+        — the same-class pool for positives, the complement pool for
+        negatives. Vectorized per class (there are only a handful)."""
+        out = np.empty(len(ya), dtype=np.int64)
+        for c in classes:
+            mask = ya == c
+            m = int(mask.sum())
+            if m:
+                out[mask] = self._rng.choice(pool[int(c)], size=m)
+        return out
+
+    # -- inference ------------------------------------------------------------
+
+    def embed(self, X):
+        """Embedding vectors for images X, shape (n, embed_dim_)."""
+        self._require_built()
+        X = self._check(X, expect=self.in_shape_, name="X")
+        return self._embed_batched(X)
+
+    def retrieve(self, query, gallery, k: int = 5):
+        """k nearest gallery items to each query in embedding space.
+
+        ``query`` is one image ``(c, h, w)`` or a batch ``(nq, c, h, w)``;
+        ``gallery`` is a batch of images ``(m, c, h, w)``. Either may instead
+        be a pre-computed embedding matrix ``(., embed_dim_)`` — handy when the
+        gallery is fixed across many queries. Returns ``(indices, distances)``,
+        each ``(k,)`` for a single query or ``(nq, k)`` for a batch, sorted
+        nearest-first by Euclidean distance.
+        """
+        self._require_built()
+        single = (np.ndim(query) == len(self.in_shape_))     # one image, no batch axis
+        Q = self._as_embeddings(query if not single else np.asarray(query)[None])
+        G = self._as_embeddings(gallery)
+        k = min(int(k), G.shape[0])
+
+        # ||q - g||^2 = |q|^2 + |g|^2 - 2 q.g ; argpartition for the k smallest.
+        d2 = (np.sum(Q * Q, axis=1, keepdims=True)
+              + np.sum(G * G, axis=1)[None, :]
+              - 2.0 * Q @ G.T)                            # (nq, m)
+        np.maximum(d2, 0.0, out=d2)
+        part = np.argpartition(d2, k - 1, axis=1)[:, :k]
+        rows = np.arange(Q.shape[0])[:, None]
+        order = np.argsort(d2[rows, part], axis=1)
+        idx = part[rows, order]
+        dist = np.sqrt(d2[rows, idx])
+        if single:
+            return idx[0], dist[0]
+        return idx, dist
+
+    def verify(self, a, b, threshold=None):
+        """Euclidean distance between embeddings of ``a`` and ``b`` (lower =
+        more likely the same identity). ``a``/``b`` are single images or equal-
+        length batches. With ``threshold`` given, returns a boolean "same"
+        decision (``distance <= threshold``) instead of the distance.
+        """
+        self._require_built()
+        Za = self._as_embeddings(a)
+        Zb = self._as_embeddings(b)
+        dist = np.sqrt(np.maximum(np.sum((Za - Zb) ** 2, axis=1), 0.0))
+        out = dist if threshold is None else (dist <= float(threshold))
+        return out[0] if out.shape[0] == 1 else out
+
+    # -- internals ------------------------------------------------------------
+
+    def _as_embeddings(self, A):
+        """Coerce images (2, 3 or 4-D) or a ready (., embed_dim_) matrix to a
+        2-D embedding batch."""
+        A = np.asarray(A, dtype=np.float32)
+        if A.ndim == 2 and A.shape[1] == self.embed_dim_:
+            return A                                    # already embeddings
+        if A.ndim == len(self.in_shape_):
+            A = A[None]                                 # single image -> batch
+        return self._embed_batched(self._check(A, expect=self.in_shape_))
+
+    def _embed_batched(self, X, chunk: int = 256):
+        out = np.empty((len(X), self.embed_dim_), dtype=np.float32)
+        for s in range(0, len(X), chunk):
+            h = X[s:s + chunk]                          # contiguous slice view
+            for layer in self.layers:
+                h = layer.forward(h, self._backend)
+            out[s:s + chunk] = h                        # copy out: scratch is reused
+        return out
+
+    @staticmethod
+    def _forward(batch, layers, backend):
+        out = np.ascontiguousarray(batch, dtype=np.float32)
+        for layer in layers:
+            out = layer.forward(out, backend)
+        return out
+
+    def _require_built(self):
+        if not self._built:
+            raise RuntimeError("model has no parameters — call build(in_shape) or fit() first")
+
+    def _check(self, X, expect=None, name="X"):
+        X = np.ascontiguousarray(X, dtype=np.float32)
+        want_ndim = 1 + (len(expect) if expect is not None else 3)
+        if X.ndim != want_ndim:
+            raise ValueError(f"{name} must have shape (n,) + {expect or '(c, h, w)'} "
+                             f"float32, got ndim={X.ndim}")
+        if expect is not None and tuple(X.shape[1:]) != tuple(expect):
+            raise ValueError(f"{name} has sample shape {tuple(X.shape[1:])}, "
+                             f"expected {tuple(expect)}")
+        return X

mantissa_embed-0.1.0/mantissa_embed/models.py

@@ -0,0 +1,38 @@
+"""Trunk factory: a small convolutional embedding network.
+
+Returns a *layer list* (not a built model) — hand it to
+:class:`mantissa_embed.Embedder`, which owns the backend and seeds weight init
+at build time. Built the same way as :func:`mantissa_cnn.models.lenet5`: a
+Conv/Pool/Flatten/Dense stack, but the head is ``Dense(embed_dim,
+act="identity")`` — it emits an embedding vector, not class logits. The metric
+loss lives on top of that vector (see :mod:`mantissa_embed.losses`).
+"""
+from __future__ import annotations
+
+from mantissa_cnn import Conv2D, Dense, Flatten, MaxPool2D
+
+__all__ = ["small_cnn_embedder"]
+
+
+def small_cnn_embedder(in_shape=(1, 28, 28), embed_dim: int = 16, seed: int = 0):
+    """A LeNet-shaped trunk mapping an image to an ``embed_dim`` vector.
+
+    Conv 8@3x3 -> pool -> Conv 16@3x3 -> pool -> Flatten -> Dense 64 ->
+    Dense(embed_dim). relu convolutions (He init), identity embedding head
+    (Glorot init) — the metric loss, not a softmax, sits on the head.
+
+    ``in_shape`` is accepted for symmetry with the family's model factories and
+    to document the intended input; the layers infer their shapes at build
+    time. ``seed`` is likewise reserved for signature symmetry — weight init is
+    seeded by the ``Embedder`` when it builds this list, not here (an unbuilt
+    layer carries no randomness).
+    """
+    return [
+        Conv2D(8, 3, pad=1, act="relu"),
+        MaxPool2D(2),
+        Conv2D(16, 3, pad=1, act="relu"),
+        MaxPool2D(2),
+        Flatten(),
+        Dense(64, act="relu"),
+        Dense(int(embed_dim), act="identity"),
+    ]

mantissa_embed-0.1.0/mantissa_embed.egg-info/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mantissa-embed
+Version: 0.1.0
+Summary: CNN metric learning on the mantissa C engine: image embeddings for similarity, verification and retrieval
+Author: Tekin Ertekin
+License: MIT
+Project-URL: Homepage, https://github.com/tekinertekin/mantissa-embed
+Project-URL: Base, https://github.com/tekinertekin/mantissa-cnn
+Project-URL: Engine, https://github.com/tekinertekin/mantissa
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Requires-Dist: mantissa-cnn>=0.2.2
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.5; extra == "viz"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Dynamic: license-file
+
+# mantissa-embed
+
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Python](https://img.shields.io/badge/python-3.9%2B-3776AB.svg)
+[![Base](https://img.shields.io/badge/base-mantissa--cnn-4B8BBE.svg)](https://github.com/tekinertekin/mantissa-cnn)
+[![Engine](https://img.shields.io/badge/engine-mantissa-00599C.svg)](https://github.com/tekinertekin/mantissa)
+
+**Learning what "similar" means, with a C engine.** A classifier answers *which
+class*; an embedder answers *how alike* — it maps each image to a point in a
+vector space where same-thing images land close together and different-thing
+images land far apart. That single geometry powers similarity search,
+verification ("are these two the same?") and retrieval ("show me the nearest
+matches"), for classes the model was never trained to name.
+
+`mantissa-embed` trains that embedding with **metric learning** — the
+contrastive and triplet losses — on top of a
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) trunk: its
+Conv2D / MaxPool2D / Flatten / Dense layers, its
+[mantissa](https://github.com/tekinertekin/mantissa) C-engine and pure-numpy
+backends, and its dataset loaders are reused, not reimplemented. This package
+adds only what metric learning needs on top of a classifier: the two losses,
+an `Embedder` that trains a trunk with them, and the four things embeddings buy
+you — `fit` / `embed` / `retrieve` / `verify`.
+
+## The mantissa family
+
+Part of the **mantissa** family: a low-precision engine written in C, with
+small Python packages built on top. Each package sits under the one it depends
+on — ⭐ marks where you are, and every other name links to its repo.
+
+- [mantissa](https://github.com/tekinertekin/mantissa) — low-precision neural-network engine in C (the core)
+  - [mantissa-perceptron](https://github.com/tekinertekin/mantissa-perceptron) — perceptron & ADALINE, the linear classics
+  - [mantissa-nn](https://github.com/tekinertekin/mantissa-nn) — shared neural-net primitives (layers, engine binding)
+    - [mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn) — convolutional networks for images
+      - [mantissa-auto-encoder](https://github.com/tekinertekin/mantissa-auto-encoder) — autoencoders for denoising & super-resolution
+      - [mantissa-interpret](https://github.com/tekinertekin/mantissa-interpret) — CNN interpretability (occlusion, saliency, Grad-CAM)
+      - ⭐ **mantissa-embed** — CNN metric learning (image embeddings for similarity & retrieval) *(you are here)*
+    - [mantissa-mlp](https://github.com/tekinertekin/mantissa-mlp) — multilayer perceptrons, fully-connected nets
+
+
+## New to metric learning?
+
+A classifier learns a fixed set of labels and a decision boundary between them.
+Metric learning learns something more basic and more reusable: a **distance**.
+It trains the network so that the Euclidean distance between two images'
+embeddings *is* a measure of how similar they are — and it does that using only
+the relation between examples ("these two are the same kind", "these two are
+not"), never a class *name*. Two consequences follow:
+
+- **It generalizes to classes it never trained on.** Because the loss only ever
+  says "closer" or "farther", a model trained on some identities produces useful
+  distances for identities it has never seen — the basis of face verification,
+  where you cannot retrain for every new person.
+- **One embedding serves many tasks.** Compute it once per image, then:
+  *verify* by thresholding a distance, *retrieve* by nearest-neighbour search,
+  *cluster* by feeding the vectors to any clustering method.
+
+Two classic losses do the training, and this package implements both:
+
+- **Contrastive loss** works on **pairs**. A same-class pair pays its squared
+  distance (pulled together); a different-class pair pays a hinge that is zero
+  once the pair is at least a `margin` apart (pushed apart, but only until far
+  enough) — Hadsell, Chopra & LeCun (2006), "Dimensionality Reduction by
+  Learning an Invariant Mapping", *CVPR*.
+- **Triplet loss** works on **triples** of (anchor, positive, negative). It asks
+  only that the negative be farther from the anchor than the positive, by at
+  least a `margin` — a *relative* constraint, which is often easier to satisfy
+  and to scale than pinning absolute distances — Schroff, Kalenichenko &
+  Philbin (2015), "FaceNet: A Unified Embedding for Face Recognition and
+  Clustering", *CVPR*.
+
+**A Siamese/triplet network is just one network run more than once.** The two
+legs of a pair (or three of a triplet) share the *same* weights, so there is no
+second network to manage: stack the legs into one batch, run a single forward
+pass, compute the loss and its per-row gradient on the resulting embeddings,
+and backpropagate that gradient through the one trunk. That is exactly what
+`Embedder.fit` does — the same custom forward/loss/backward loop the rest of the
+family uses, with a metric loss where the classifier's softmax would be.
+
+## Install
+
+```sh
+pip install mantissa-embed
+```
+
+Pulls in `mantissa-cnn >= 0.2.2` (and transitively `mantissa-nn` + the
+`mantissa-core` engine). For the demo's plots, `pip install mantissa-embed[viz]`.
+
+From checkouts (works today, no PyPI needed): clone this repo, `cnn`,
+`mantissa-nn` and [mantissa](https://github.com/tekinertekin/mantissa) side by
+side, build the engine (`make dist` there), then here:
+
+```sh
+pip install -e ../mantissa -e ../mantissa-nn -e ../cnn && pip install -e ".[viz]"
+```
+
+mantissa-cnn finds the sibling engine checkout automatically, and its dataset
+loaders find a `data/` directory via `MANTISSA_CNN_DATA` (the demo points this
+at the sibling `cnn/data/` for you).
+
+## Quickstart
+
+```sh
+# datasets are mantissa-cnn's; nothing downloads implicitly — fetch once:
+python -m mantissa_cnn.datasets download mnist
+```
+
+```python
+from mantissa_cnn import datasets
+from mantissa_embed import Embedder, models
+
+Xtr, ytr, Xte, yte = datasets.subset("mnist", 6000, 2000, seed=0)
+
+emb = Embedder(models.small_cnn_embedder(embed_dim=16), loss="triplet")  # or "contrastive"
+emb.fit(Xtr, ytr, epochs=8, batch_size=64, lr=0.05, verbose=True)
+
+Z = emb.embed(Xte)                       # (2000, 16) embedding vectors
+idx, dist = emb.retrieve(Xte[0], Z, k=5) # 5 nearest test images to query 0
+same = emb.verify(Xte[0], Xte[1], threshold=1.0)   # same identity? (bool)
+```
+
+Or compose your own trunk from mantissa-cnn's layers — any Conv/Pool/Flatten
+stack ending in `Dense(embed_dim, act="identity")`:
+
+```python
+from mantissa_cnn import Conv2D, MaxPool2D, Flatten, Dense
+from mantissa_embed import Embedder
+
+emb = Embedder(
+    [Conv2D(16, 3, pad=1), MaxPool2D(2), Flatten(), Dense(32)],  # 32-D embedding
+    loss="contrastive", margin=1.0, seed=0)
+```
+
+## The API
+
+`Embedder(layers, loss="triplet"|"contrastive", margin=None, seed=0, backend="mantissa")`,
+then:
+
+| method | does | returns |
+|---|---|---|
+| `fit(X, y, epochs, batch_size, lr, verbose)` | trains the trunk by metric learning; `y` only decides same/different | `self` (`history_["loss"]` per epoch) |
+| `embed(X)` | one forward pass, chunked | `(n, embed_dim)` embeddings |
+| `retrieve(query, gallery, k)` | k nearest gallery items in embedding space (numpy `argpartition`, no sklearn) | `(indices, distances)`, nearest-first |
+| `verify(a, b, threshold=None)` | embedding distance between `a` and `b`; with `threshold`, a boolean same/different | distance, or bool |
+
+`retrieve` and `verify` accept raw images **or** a pre-computed `(., embed_dim)`
+matrix, so a fixed gallery is embedded once and reused across queries.
+
+Deliberately minimal, like the rest of the family: NCHW float32 images, plain
+SGD, the two classic losses, plain Euclidean distances. No autograd graph, no
+optimizer zoo, no ANN index. The trunk's convolutions run in C on zero-copy
+float32 buffers; the losses are memory-bound reductions over embedding vectors
+and honestly stay in numpy (`mantissa_embed.losses`, importable and gradient-
+checked on their own). Layers allocate scratch once per batch shape and reuse
+it.
+
+## Results
+
+A `small_cnn_embedder` (52,528 params, 16-D embedding) trained on a 6k-image
+MNIST subset with the triplet loss and the mantissa C engine (8 epochs, triplet
+loss **0.090 → 0.016**), then embedding the held-out 2k test set. Reproduce with
+`python examples/embeddings_demo.py`.
+
+The embedding separates the digits with no label ever entering the loss — colour
+is the true digit, shown only for the plot:
+
+![MNIST test embeddings, 2-D PCA, coloured by true digit — visible per-digit clusters](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/embedding_manifold.png)
+
+And nearest-neighbour retrieval returns same-digit images (green border = a
+correct match, i.e. the neighbour's true digit equals the query's):
+
+![retrieval gallery: five query digits, each with its five nearest neighbours in embedding space](https://raw.githubusercontent.com/tekinertekin/mantissa-embed/main/assets/retrieval_gallery.png)
+
+## License
+
+MIT — © Tekin Ertekin. Base package:
+[mantissa-cnn](https://github.com/tekinertekin/mantissa-cnn); engine:
+[mantissa](https://github.com/tekinertekin/mantissa) — same author, MIT.

mantissa_embed-0.1.0/mantissa_embed.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+mantissa_embed/__init__.py
+mantissa_embed/losses.py
+mantissa_embed/model.py
+mantissa_embed/models.py
+mantissa_embed.egg-info/PKG-INFO
+mantissa_embed.egg-info/SOURCES.txt
+mantissa_embed.egg-info/dependency_links.txt
+mantissa_embed.egg-info/requires.txt
+mantissa_embed.egg-info/top_level.txt

mantissa_embed-0.1.0/mantissa_embed.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mantissa_embed-0.1.0/mantissa_embed.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.20
+mantissa-cnn>=0.2.2
+
+[dev]
+pytest>=7
+
+[viz]
+matplotlib>=3.5

mantissa_embed-0.1.0/mantissa_embed.egg-info/top_level.txt

@@ -0,0 +1 @@
+mantissa_embed

mantissa_embed-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mantissa-embed"
+version = "0.1.0"
+description = "CNN metric learning on the mantissa C engine: image embeddings for similarity, verification and retrieval"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Tekin Ertekin" }]
+dependencies = [
+    "numpy>=1.20",
+    # Trains a Conv2D/MaxPool2D/Flatten/Dense trunk with the same custom
+    # forward/backward loop the rest of the family uses, so it runs on the
+    # mantissa C engine (or the pure-numpy backend). mantissa-cnn transitively
+    # pulls in mantissa-nn and the mantissa-core engine. For the dev layout,
+    # `pip install -e ../cnn ../mantissa-nn ../mantissa` first.
+    "mantissa-cnn>=0.2.2",
+]
+
+[project.optional-dependencies]
+viz = ["matplotlib>=3.5"]
+dev = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/tekinertekin/mantissa-embed"
+Base = "https://github.com/tekinertekin/mantissa-cnn"
+Engine = "https://github.com/tekinertekin/mantissa"
+
+[tool.setuptools]
+packages = ["mantissa_embed"]
+
+[tool.pytest.ini_options]
+filterwarnings = [
+    # numpy 2.x on Apple Accelerate emits spurious FPE RuntimeWarnings from the
+    # BLAS matmul kernel even on finite inputs (same issue documented across
+    # the family: mantissa-cnn / mantissa-autoencoder pyproject).
+    "ignore:.*encountered in matmul:RuntimeWarning",
+]

mantissa_embed-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+