# omoindrot/tensorflow-triplet-loss architecture

> Architecture diagram of the GitHub repository omoindrot/tensorflow-triplet-loss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omoindrot/tensorflow-triplet-loss
- Repository: https://github.com/omoindrot/tensorflow-triplet-loss

## Overview

##### Project type and purpose
- This is a research‐oriented, full Python machine‐learning pipeline for training and evaluating triplet‐loss embeddings on datasets (MNIST by default).
- Key features: data ingestion, model definition (including triplet‐loss with online mining), training loop, hyperparameter search, evaluation, and embedding visualization.

##### File structure
- Top‐level scripts:
– train.py: orchestrates training using parameters from a JSON file (in experiments/*).
– evaluate.py: loads a saved model and computes evaluation metrics.
– visualize_embeddings.py: projects trained embeddings (e.g., via t-SNE) for TensorBoard.
– search_hyperparams.py: launches multiple train runs across hyperparameter configurations.
- Directories:
– model/: contains core ML code (input_fn.py, model_fn.py, triplet_loss.py, mnist_dataset.py, utils.py) and associated unit tests.
– experiments/: holds subfolders for each experiment’s hyperparameter file (params.json) and model_dir.
– data/: placeholder for raw or custom datasets.
- Config files & environments:
– requirements_cpu.txt, requirements_gpu.txt for dependency management.
– .pylintrc, .travis.yml, .gitignore for linting, CI, and VCS settings.

##### Extract insights from the README
- The heart of the system is the triplet loss implementations (batch‐all and batch‐hard) in model/triplet_loss.py.
- Training relies on TensorFlow Estimator‐style patterns: an input function, a model function, and monitored training & summary directories.
- The experiments directory plus params.json drive reproducible, parameterized runs.

##### Main components & interactions
a. Data Ingestion Layer
– data/ (raw files) or built‐in MNIST via model/mnist_dataset.py
– input_fn.py transforms raw data into TensorFlow Dataset objects with batching.
b. Model and Loss
– model_fn.py builds the computation graph: embedding network + triplet‐loss functions from triplet_loss.py.
– triplet_loss.py implements online triplet mining and two loss variants.
c. Training Orchestration
– train.py reads params.json, sets up a model directory, initializes training via tf.estimator or custom loop.
– logs training summaries (loss, fraction_positive) to model_dir for TensorBoard.
d. Hyperparameter Search
– search_hyperparams.py iterates over parameter grids, launching multiple train.py runs in parallel or sequentially, each with its own experiment folder.
e. Evaluation & Visualization
– evaluate.py loads checkpoint from a given model_dir to compute final metrics on test data.
– visualize_embeddings.py reads embeddings and uses t-SNE (from utils.py) to project them; writes summary for TensorBoard.
f. External Tools
– TensorBoard reads from experiment folders to display scalars (loss, fraction_positive) and embedding projector visuals.

##### Architectural patterns & design principles
- Modular ML pipeline: separation of concerns between data, model, loss, and orchestration.
- Config‐driven experiments: parameters live in JSON, enabling reproducibility and grid search.
- Use of standard TensorFlow abstractions (input_fn, model_fn, summaries) to promote portability.

##### Checklist
[ ] All major modules (Data, Input, Model, Loss, Training, Hyperparam Search, Evaluation, Visualization) are present and labeled.
[ ] Config files (params.json) and outputs (checkpoints, summaries) are explicit.
[ ] Integration points to TensorBoard and external scripts are annotated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Ingestion Layer
    subgraph "Data Ingestion Layer"
        data["data/"]:::data
        mnist["Built-in MNIST\n(model/mnist_dataset.py)"]:::data
        input_fn["Input Function\n(model/input_fn.py)"]:::data
    end

    data --> input_fn
    mnist --> input_fn

    %% Model and Loss
    subgraph "Model & Loss"
        model_fn["Model Function\n(model/model_fn.py)"]:::model
        triplet_loss["Triplet Loss\n(model/triplet_loss.py)"]:::model
    end

    input_fn --> model_fn
    model_fn --> triplet_loss

    %% Training Orchestration
    subgraph "Orchestration"
        train["Training Script\n(train.py)"]:::orchestr
        search_hp["Hyperparameter Search\n(search_hyperparams.py)"]:::orchestr
    end

    triplet_loss --> train
    search_hp --> train

    %% Experiments Directory
    experiments["Experiments Directory\n(experiments/)"]:::data
    train --> experiments

    %% Evaluation & Visualization
    subgraph "Evaluation & Visualization"
        evaluate["Evaluation Script\n(evaluate.py)"]:::evalviz
        visualize["Visualization Script\n(visualize_embeddings.py)"]:::evalviz
        utils["Utilities\n(model/utils.py)"]:::model
    end

    experiments --> evaluate
    experiments --> visualize
    visualize --> utils

    %% External Tools
    tensorboard["TensorBoard"]:::external
    experiments --> tensorboard

    %% Testing
    subgraph "Testing"
        test["Unit Test\n(test_triplet_loss.py)"]:::orchestr
    end
    test --> triplet_loss

    %% Configuration & CI
    subgraph "Configuration & CI"
        req_cpu["requirements_cpu.txt"]:::config
        req_gpu["requirements_gpu.txt"]:::config
        pylintrc[".pylintrc"]:::config
        travis[".travis.yml"]:::config
        gitignore[".gitignore"]:::config
    end

    %% Click Events
    click data "https://github.com/omoindrot/tensorflow-triplet-loss/tree/master/data/"
    click mnist "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/mnist_dataset.py"
    click input_fn "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/input_fn.py"
    click model_fn "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/model_fn.py"
    click triplet_loss "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/triplet_loss.py"
    click train "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/train.py"
    click search_hp "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/search_hyperparams.py"
    click experiments "https://github.com/omoindrot/tensorflow-triplet-loss/tree/master/experiments/"
    click evaluate "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/evaluate.py"
    click visualize "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/visualize_embeddings.py"
    click utils "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/utils.py"
    click test "https://github.com/omoindrot/tensorflow-triplet-loss/blob/master/model/tests/test_triplet_loss.py"

    %% Styles
    classDef data fill:#cce5ff,stroke:#1f77b4,color:#1f1f1f;
    classDef model fill:#d4edda,stroke:#2ca02c,color:#1f1f1f;
    classDef orchestr fill:#fff3cd,stroke:#ff7f0e,color:#1f1f1f;
    classDef evalviz fill:#e2d6f7,stroke:#9467bd,color:#1f1f1f;
    classDef external fill:#f2f2f2,stroke:#7f7f7f,color:#1f1f1f;
    classDef config fill:#e8e8e8,stroke:#6c757d,color:#1f1f1f;
```
