tripletlib 0.1.0__tar.gz

tripletlib-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 templateprotection
+
+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.

tripletlib-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tripletlib
+Version: 0.1.0
+Summary: A lightweight library for training and evaluating embedding models with triplet loss
+Author: Ted Kane
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == "examples"
+Requires-Dist: pandas; extra == "examples"
+Dynamic: license-file
+
+# TripletLib
+
+TripletLib is a lightweight Python library for training and evaluating embedding models using **triplet loss**. It is designed to help you build models that learn meaningful embeddings for images, time series, or any vector data, enabling tasks like verification, retrieval, or classification based on similarity.
+
+## What is Triplet Loss?
+
+A "triplet" is a set of 3 samples of data `(anchor, positive, negative)`. The `anchor` is a data sample from a specific class, the `positive` is another sample from the *same* class, and the `negative` is a sample from an entirely different class.
+Triplet loss is a type of metric learning objective that trains an embedding model to map inputs into a vector space such that:
+
+- Samples from the **same class** (e.g., anchor and positive) are close together.
+- Samples from **different classes** (e.g., anchor and negative) are far apart.
+
+This is particularly useful for tasks like biometric identification (e.g., face recognition), where traditional classification cannot generalize to unseen classes (new faces).
+
+## Features
+
+- Base `EmbeddingModel` class with a built-in training loop.
+- `TripletDataset` wrapper to automatically generate triplets from any dataset.
+- Utilities for evaluating embeddings with **EER** and **AUC** metrics.
+- Compatible with PyTorch and supports GPU acceleration.
+
+## Installation
+
+You can install TripletLib via pip:
+
+```bash
+pip install tripletlib
+```
+## Usage
+```python
+import torch
+from tripletlib.triplet_utils import EmbeddingModel, TripletDataset
+from torch.utils.data import DataLoader
+
+# Example: using a simple linear embedding model
+class LinearEmbeddingModel(EmbeddingModel):
+    def __init__(self, input_size, embedding_dim=64, lr=1e-3, margin=1.0, device="cpu"):
+        super().__init__(embedding_dim, margin=margin, device=device)
+        self.fc = torch.nn.Sequential(
+            torch.nn.Linear(input_size, 128),
+            torch.nn.ReLU(),
+            torch.nn.Linear(128, embedding_dim)
+        )
+        self.optimizer = torch.optim.Adam(self.parameters(), lr=lr)
+
+    def forward(self, x):
+        x = self.fc(x)
+        return torch.nn.functional.normalize(x, p=2, dim=1)
+
+# Prepare your dataset as a list of (feature, label) tuples
+train_dataset = [(torch.randn(10), label) for label in range(5) for _ in range(20)]
+triplet_train = TripletDataset(train_dataset)
+dataloader_train = DataLoader(triplet_train, batch_size=16, shuffle=True)
+
+# Instantiate and train the model
+model = LinearEmbeddingModel(input_size=10, embedding_dim=64, lr=1e-3)
+history = model.fit(dataloader_train, epochs=5)
+```
+
+## Examples
+You can find examples of real usages in `/examples`, including:
+- Keystroke Dynamics: Comparing typing patterns to determine if they are from the same individual.
+- More to come...
+

tripletlib-0.1.0/README.md

@@ -0,0 +1,64 @@
+# TripletLib
+
+TripletLib is a lightweight Python library for training and evaluating embedding models using **triplet loss**. It is designed to help you build models that learn meaningful embeddings for images, time series, or any vector data, enabling tasks like verification, retrieval, or classification based on similarity.
+
+## What is Triplet Loss?
+
+A "triplet" is a set of 3 samples of data `(anchor, positive, negative)`. The `anchor` is a data sample from a specific class, the `positive` is another sample from the *same* class, and the `negative` is a sample from an entirely different class.
+Triplet loss is a type of metric learning objective that trains an embedding model to map inputs into a vector space such that:
+
+- Samples from the **same class** (e.g., anchor and positive) are close together.
+- Samples from **different classes** (e.g., anchor and negative) are far apart.
+
+This is particularly useful for tasks like biometric identification (e.g., face recognition), where traditional classification cannot generalize to unseen classes (new faces).
+
+## Features
+
+- Base `EmbeddingModel` class with a built-in training loop.
+- `TripletDataset` wrapper to automatically generate triplets from any dataset.
+- Utilities for evaluating embeddings with **EER** and **AUC** metrics.
+- Compatible with PyTorch and supports GPU acceleration.
+
+## Installation
+
+You can install TripletLib via pip:
+
+```bash
+pip install tripletlib
+```
+## Usage
+```python
+import torch
+from tripletlib.triplet_utils import EmbeddingModel, TripletDataset
+from torch.utils.data import DataLoader
+
+# Example: using a simple linear embedding model
+class LinearEmbeddingModel(EmbeddingModel):
+    def __init__(self, input_size, embedding_dim=64, lr=1e-3, margin=1.0, device="cpu"):
+        super().__init__(embedding_dim, margin=margin, device=device)
+        self.fc = torch.nn.Sequential(
+            torch.nn.Linear(input_size, 128),
+            torch.nn.ReLU(),
+            torch.nn.Linear(128, embedding_dim)
+        )
+        self.optimizer = torch.optim.Adam(self.parameters(), lr=lr)
+
+    def forward(self, x):
+        x = self.fc(x)
+        return torch.nn.functional.normalize(x, p=2, dim=1)
+
+# Prepare your dataset as a list of (feature, label) tuples
+train_dataset = [(torch.randn(10), label) for label in range(5) for _ in range(20)]
+triplet_train = TripletDataset(train_dataset)
+dataloader_train = DataLoader(triplet_train, batch_size=16, shuffle=True)
+
+# Instantiate and train the model
+model = LinearEmbeddingModel(input_size=10, embedding_dim=64, lr=1e-3)
+history = model.fit(dataloader_train, epochs=5)
+```
+
+## Examples
+You can find examples of real usages in `/examples`, including:
+- Keystroke Dynamics: Comparing typing patterns to determine if they are from the same individual.
+- More to come...
+

tripletlib-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tripletlib"
+version = "0.1.0"
+description = "A lightweight library for training and evaluating embedding models with triplet loss"
+authors = [
+    { name = "Ted Kane" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+
+dependencies = [
+    "torch",
+    "numpy",
+    "scikit-learn",
+    "scipy",
+]
+
+[project.optional-dependencies]
+examples = ["matplotlib", "pandas"]

tripletlib-0.1.0/setup.cfg

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

tripletlib-0.1.0/tripletlib/__init__.py

@@ -0,0 +1,2 @@
+from .triplet_utils import *
+from .evaluation_utils import *

tripletlib-0.1.0/tripletlib/evaluation_utils.py

@@ -0,0 +1,77 @@
+import numpy as np
+import torch
+from scipy.interpolate import interp1d
+from scipy.optimize import brentq
+from sklearn.metrics import roc_auc_score, roc_curve
+
+
+def compute_eer_from_scores(y_true, y_scores):
+    """
+    Compute Equal Error Rate (EER) from true labels and predicted scores.
+
+    Args:
+        y_true (array-like): True binary labels (0 or 1).
+        y_scores (array-like): Predicted scores or probabilities.
+
+    Returns:
+        eer (float): Equal Error Rate.
+        eer_threshold (float): Score threshold corresponding to EER.
+    """
+    # Compute FPR, TPR, thresholds
+    fpr, tpr, thresholds = roc_curve(y_true, y_scores, pos_label=1)
+
+    eer = brentq(lambda x: 1. - x - interp1d(fpr, tpr)(x), 0., 1.)
+    eer_threshold = interp1d(fpr, thresholds)(eer)
+    return 1-eer, eer_threshold
+
+
+def compute_eer_from_triplets(anchor_emb, positive_emb, negative_emb):
+    """
+    Compute EER from a batch of triplet embeddings.
+
+    Args:
+        anchor_emb (torch.Tensor): [batch_size, embedding_dim]
+        positive_emb (torch.Tensor): [batch_size, embedding_dim]
+        negative_emb (torch.Tensor): [batch_size, embedding_dim]
+
+    Returns:
+        eer (float): Equal Error Rate.
+        eer_threshold (float): Distance threshold corresponding to EER.
+    """
+    y_true, y_scores = compute_dists_from_triplets(anchor_emb, positive_emb, negative_emb)
+    eer, eer_threshold = compute_eer_from_scores(y_true, y_scores)
+    return eer, eer_threshold
+
+
+def compute_auc_from_triplets(anchor_emb, positive_emb, negative_emb):
+    """
+    Compute ROC AUC from a batch of triplet embeddings.
+
+    Args:
+        anchor_emb (torch.Tensor): [batch_size, embedding_dim]
+        positive_emb (torch.Tensor): [batch_size, embedding_dim]
+        negative_emb (torch.Tensor): [batch_size, embedding_dim]
+
+    Returns:
+        auc (float): Area Under the ROC Curve.
+    """
+    y_true, y_scores = compute_dists_from_triplets(anchor_emb, positive_emb, negative_emb)
+
+    # Compute ROC AUC
+    auc = roc_auc_score(y_true, y_scores)
+    return auc
+
+
+def compute_dists_from_triplets(anchor_emb, positive_emb, negative_emb):
+    anchor_emb = anchor_emb.view(anchor_emb.size(0), -1)
+    positive_emb = positive_emb.view(positive_emb.size(0), -1)
+    negative_emb = negative_emb.view(negative_emb.size(0), -1)
+
+    # Compute Euclidean distances
+    pos_distances = torch.norm(anchor_emb - positive_emb, p=2, dim=1).cpu().detach().numpy()
+    neg_distances = torch.norm(anchor_emb - negative_emb, p=2, dim=1).cpu().detach().numpy()
+
+    # Labels: 1 for positive (same class), 0 for negative (different class)
+    y_alike = np.concatenate([np.ones_like(pos_distances), np.zeros_like(neg_distances)])
+    total_dists = np.concatenate([pos_distances, neg_distances])
+    return y_alike, total_dists

tripletlib-0.1.0/tripletlib/triplet_utils.py

@@ -0,0 +1,193 @@
+from abc import ABC, abstractmethod
+import random
+
+import numpy as np
+import torch
+from torch.utils.data import Dataset
+from tqdm import tqdm
+
+from .evaluation_utils import compute_eer_from_triplets, compute_auc_from_triplets, compute_dists_from_triplets
+
+
+class EmbeddingModel(torch.nn.Module, ABC):
+    """
+    Base class for models trained with triplet loss.
+    Subclasses must implement forward() to compute embeddings.
+    """
+
+    def __init__(self, embedding_dim, margin=1.0, device="cpu"):
+        super().__init__()
+        self.embedding_dim = embedding_dim
+        self.device = device
+
+        # Triplet loss (standard margin-based)
+        self.criterion = torch.nn.TripletMarginLoss(margin=margin, p=2)
+
+    @abstractmethod
+    def forward(self, x):
+        """
+        Compute embeddings for input batch x.
+        Must be implemented by subclasses.
+        """
+        pass
+
+    def fit(self, dataloader_train, dataloader_val=None, epochs=10, model_out_path='model_out.pth') -> dict[
+        str, list[float]]:
+        """
+        Train the model using triplet loss.
+
+        Args:
+            dataloader_train: iterable yielding (anchor, positive, negative) batches
+            dataloader_val: iterable yielding (anchor, positive, negative) batches
+            epochs: number of training epochs
+            model_out_path: output path for the model
+
+        Returns:
+            history: a dictionary containing historical performance metrics of the model across all epochs
+        """
+
+        history = dict()
+        history['aucs_train'] = []
+        history['aucs_val'] = []
+        history['losses_train'] = []
+        history['losses_val'] = []
+        history['eers_train'] = []
+        history['eers_val'] = []
+
+        self.to(self.device)
+        self.train()
+
+        for epoch in range(epochs):
+            epoch_loss_train = 0.0
+            epoch_auc_train = 0.0
+            epoch_eer_train = 0.0
+            for (anchor, positive, negative) in tqdm(dataloader_train, total=len(dataloader_train),
+                                                     desc='Training Loop'):
+                anchor, positive, negative = (
+                    anchor.to(self.device),
+                    positive.to(self.device),
+                    negative.to(self.device),
+                )
+
+                # Forward pass: compute embeddings
+                anchor_emb = self.forward(anchor)
+                pos_emb = self.forward(positive)
+                neg_emb = self.forward(negative)
+
+                # Compute loss
+                loss = self.criterion(anchor_emb, pos_emb, neg_emb)
+
+                # Backprop
+                self.optimizer.zero_grad()
+                loss.backward()
+                self.optimizer.step()
+
+                epoch_loss_train += loss.item()
+                epoch_auc_train += compute_auc_from_triplets(anchor_emb, pos_emb, neg_emb)
+                epoch_eer_train += compute_eer_from_triplets(anchor_emb, pos_emb, neg_emb)[0]
+
+            mean_loss_train = epoch_loss_train / len(dataloader_train)
+            mean_auc_train = epoch_auc_train / len(dataloader_train)
+            mean_eer_train = epoch_eer_train / len(dataloader_train)
+            history['eers_train'].append(mean_eer_train)
+            history['aucs_train'].append(mean_auc_train)
+            history['losses_train'].append(mean_loss_train)
+            print(f"Epoch {epoch + 1}: Train Loss: {mean_loss_train:.4f}")
+
+            if dataloader_val is not None:
+                self.eval()
+                epoch_loss_val = 0.0
+                epoch_auc_val = 0.0
+                epoch_eer_val = 0.0
+                with torch.no_grad():
+                    for (anchor, positive, negative) in tqdm(dataloader_val, total=len(dataloader_val),
+                                                             desc='Validation Loop'):
+                        anchor, positive, negative = (
+                            anchor.to(self.device),
+                            positive.to(self.device),
+                            negative.to(self.device),
+                        )
+
+                        # Forward pass: compute embeddings
+                        anchor_emb = self.forward(anchor)
+                        pos_emb = self.forward(positive)
+                        neg_emb = self.forward(negative)
+
+                        # Compute loss
+                        loss = self.criterion(anchor_emb, pos_emb, neg_emb)
+
+                        epoch_loss_val += loss.item()
+                        epoch_auc_val += compute_auc_from_triplets(anchor_emb, pos_emb, neg_emb)
+                        epoch_eer_val += compute_eer_from_triplets(anchor_emb, pos_emb, neg_emb)[0]
+
+                mean_loss_val = epoch_loss_val / len(dataloader_val)
+                mean_auc_val = epoch_auc_val / len(dataloader_val)
+                mean_eer_val = epoch_eer_val / len(dataloader_val)
+                history['eers_val'].append(mean_eer_val)
+                history['aucs_val'].append(mean_auc_val)
+                history['losses_val'].append(mean_loss_val)
+                print(f"Epoch {epoch + 1}: Validation Loss: {mean_loss_val:.4f}")
+
+            torch.save(self.state_dict(), model_out_path)
+        return history
+
+    def predict_triplet_distances(self, dataloader):
+        total_alike = []
+        total_dists = []
+        with torch.no_grad():
+            for (anchor, positive, negative) in tqdm(dataloader, total=len(dataloader),
+                                                     desc='Evaluation Loop'):
+                anchor, positive, negative = (
+                    anchor.to(self.device),
+                    positive.to(self.device),
+                    negative.to(self.device),
+                )
+
+                # Forward pass: compute embeddings
+                anchor_emb = self.forward(anchor)
+                pos_emb = self.forward(positive)
+                neg_emb = self.forward(negative)
+                y_alike, dists = compute_dists_from_triplets(anchor_emb, pos_emb, neg_emb)
+                total_alike.extend(y_alike)
+                total_dists.extend(dists)
+
+        return np.array(total_alike), np.array(total_dists)
+
+
+class TripletDataset(Dataset):
+    def __init__(self, base_dataset):
+        """
+        Wraps a basic dataset to generate triplets.
+
+        Args:
+            base_dataset: base dataset to be wrapped
+        """
+        self.base_dataset = base_dataset
+
+        # Build index lists for each class
+        self.class_to_indices = {}
+        for idx, (_, label) in enumerate(self.base_dataset):
+            if label not in self.class_to_indices:
+                self.class_to_indices[label] = []
+            self.class_to_indices[label].append(idx)
+
+        self.labels = [label for _, label in self.base_dataset]
+
+    def __getitem__(self, index):
+        anchor_sample, anchor_label = self.base_dataset[index]
+
+        # Positive: random sample with the same label (different index)
+        positive_index = index
+        while positive_index == index:  # TODO: This can get stuck forever, make sure it's possible.
+            positive_index = random.choice(self.class_to_indices[anchor_label])
+        positive_sample, _ = self.base_dataset[positive_index]
+
+        # Negative: random sample from a different label
+        negative_label = random.choice([label for label in self.class_to_indices.keys() if label != anchor_label])
+        negative_index = random.choice(self.class_to_indices[negative_label])
+        negative_sample, _ = self.base_dataset[negative_index]
+
+        return anchor_sample, positive_sample, negative_sample
+
+    def __len__(self):
+        return len(self.base_dataset)

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

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: tripletlib
+Version: 0.1.0
+Summary: A lightweight library for training and evaluating embedding models with triplet loss
+Author: Ted Kane
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch
+Requires-Dist: numpy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Provides-Extra: examples
+Requires-Dist: matplotlib; extra == "examples"
+Requires-Dist: pandas; extra == "examples"
+Dynamic: license-file
+
+# TripletLib
+
+TripletLib is a lightweight Python library for training and evaluating embedding models using **triplet loss**. It is designed to help you build models that learn meaningful embeddings for images, time series, or any vector data, enabling tasks like verification, retrieval, or classification based on similarity.
+
+## What is Triplet Loss?
+
+A "triplet" is a set of 3 samples of data `(anchor, positive, negative)`. The `anchor` is a data sample from a specific class, the `positive` is another sample from the *same* class, and the `negative` is a sample from an entirely different class.
+Triplet loss is a type of metric learning objective that trains an embedding model to map inputs into a vector space such that:
+
+- Samples from the **same class** (e.g., anchor and positive) are close together.
+- Samples from **different classes** (e.g., anchor and negative) are far apart.
+
+This is particularly useful for tasks like biometric identification (e.g., face recognition), where traditional classification cannot generalize to unseen classes (new faces).
+
+## Features
+
+- Base `EmbeddingModel` class with a built-in training loop.
+- `TripletDataset` wrapper to automatically generate triplets from any dataset.
+- Utilities for evaluating embeddings with **EER** and **AUC** metrics.
+- Compatible with PyTorch and supports GPU acceleration.
+
+## Installation
+
+You can install TripletLib via pip:
+
+```bash
+pip install tripletlib
+```
+## Usage
+```python
+import torch
+from tripletlib.triplet_utils import EmbeddingModel, TripletDataset
+from torch.utils.data import DataLoader
+
+# Example: using a simple linear embedding model
+class LinearEmbeddingModel(EmbeddingModel):
+    def __init__(self, input_size, embedding_dim=64, lr=1e-3, margin=1.0, device="cpu"):
+        super().__init__(embedding_dim, margin=margin, device=device)
+        self.fc = torch.nn.Sequential(
+            torch.nn.Linear(input_size, 128),
+            torch.nn.ReLU(),
+            torch.nn.Linear(128, embedding_dim)
+        )
+        self.optimizer = torch.optim.Adam(self.parameters(), lr=lr)
+
+    def forward(self, x):
+        x = self.fc(x)
+        return torch.nn.functional.normalize(x, p=2, dim=1)
+
+# Prepare your dataset as a list of (feature, label) tuples
+train_dataset = [(torch.randn(10), label) for label in range(5) for _ in range(20)]
+triplet_train = TripletDataset(train_dataset)
+dataloader_train = DataLoader(triplet_train, batch_size=16, shuffle=True)
+
+# Instantiate and train the model
+model = LinearEmbeddingModel(input_size=10, embedding_dim=64, lr=1e-3)
+history = model.fit(dataloader_train, epochs=5)
+```
+
+## Examples
+You can find examples of real usages in `/examples`, including:
+- Keystroke Dynamics: Comparing typing patterns to determine if they are from the same individual.
+- More to come...
+

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

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+tripletlib/__init__.py
+tripletlib/evaluation_utils.py
+tripletlib/triplet_utils.py
+tripletlib.egg-info/PKG-INFO
+tripletlib.egg-info/SOURCES.txt
+tripletlib.egg-info/dependency_links.txt
+tripletlib.egg-info/requires.txt
+tripletlib.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,8 @@
+torch
+numpy
+scikit-learn
+scipy
+
+[examples]
+matplotlib
+pandas

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

@@ -0,0 +1 @@
+tripletlib