# bethgelab/foolbox architecture

> Architecture diagram of the GitHub repository bethgelab/foolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bethgelab/foolbox
- Repository: https://github.com/bethgelab/foolbox

## Overview

##### Project type and purpose
- This is an open-source Python library (“Foolbox”) for running adversarial attacks on machine-learning models (PyTorch, TensorFlow, JAX) via a unified API.
- Its goal is to provide state-of-the-art gradient-based and decision-based attacks, distance metrics, criteria, and utilities to benchmark model robustness.

##### High-level analysis of the file structure
- Top-level directories:
- `.github/` (CI/CD workflows for tests, docs, PyPI, funding)
- `foolbox/` (core library modules: attacks, criteria, distances, models, utils, zoo)
- `examples/` (usage scripts demonstrating attacks on ResNet, MNIST, etc.)
- `docs/` (Sphinx documentation)
- `guide/` (VuePress user guide)
- `tests/` (pytest suite)
- `performance/` (benchmark notebooks and data)
- Packaging/config: `setup.py`, `pyproject.toml`, `MANIFEST.in`, `setup.cfg`, `requirements.txt`
- Key patterns: modular attack classes inheriting from a base; a wrapper layer for multiple backends; separation of core library vs examples vs docs vs tests vs CI.

##### Important insights from README
- Built on top of EagerPy to abstract over multiple frameworks.
- Attack API: user creates a backend-specific `Model` wrapper, picks an attack from `foolbox.attacks`, passes images/labels/epsilons.
- Documentation and guide are published via ReadTheDocs and GitHub Pages (VuePress).
- Continuous integration runs tests, builds docs, and publishes to PyPI.

##### Main components & their relationships
a. User layer
- **User code / Examples / Notebook** – calls
- **Foolbox API** (`foolbox/__init__.py`) → selects
b. Attack orchestration
- **Attack classes** (`foolbox/attacks/*.py`)
- **Criteria** (`foolbox/criteria.py`)
- **Distances** (`foolbox/distances.py`)
- **Gradient estimators & devutils** (`foolbox/gradient_estimators.py`, `foolbox/devutils.py`)
- These reference
c. Model abstraction
- **Model wrappers** for PyTorch, TensorFlow, JAX (`foolbox/models/*.py`)
- Underlying: **EagerPy** abstraction
- Which dispatches to the actual **backend frameworks**: PyTorch, TF, JAX
d. Auxiliary modules
- **Zoo** (`foolbox/zoo/`): model loader, weight fetcher, git cloner
- **Plot & TensorBoard logging** (`foolbox/plot.py`, `foolbox/tensorboard.py`)
- **Utilities & types** (`foolbox/utils.py`, `foolbox/types.py`)
e. Infrastructure & pipelines
- **Tests** (`tests/`) run via pytest in CI
- **Docs** (`docs/` + `guide/`) built by Sphinx and VuePress, published to ReadTheDocs and GitHub Pages
- **CI workflows** (`.github/workflows/`): tests, docs, PyPI deploy
- **Packaging** (`setup.py`, `pyproject.toml`, `MANIFEST.in`)

##### Architectural patterns & design principles
- **Modularity**: each attack, distance, and model wrapper lives in its own module.
- **Abstraction layer**: EagerPy hides backend differences.
- **Open/Closed**: new attacks or criteria can be added via subclassing.
- **Separation of concerns**: core code vs examples vs documentation vs tests vs CI.

##### Essential elements
- Clear component names matching directory names (e.g., `foolbox.attacks`, `foolbox.models.pytorch`)
- CI/CD flow linking `.github/workflows` to PyPI and ReadTheDocs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer" 
        direction TB
        Examples["Examples & Notebooks"]:::ext
        Performance["Performance Notebooks"]:::ext
    end

    %% Core API
    subgraph "Foolbox Core Library"
        direction TB
        API["foolbox/__init__.py"]:::core
        subgraph "Attack Orchestration"
            direction TB
            Attacks["foolbox/attacks/"]:::core
            Criteria["foolbox/criteria.py"]:::core
            Distances["foolbox/distances.py"]:::core
            GradEst["foolbox/gradient_estimators.py"]:::core
            DevUtils["foolbox/devutils.py"]:::core
        end
    end

    %% Model Abstraction
    subgraph "Model Abstraction"
        direction TB
        Models["foolbox/models/"]:::core
        EagerPy["EagerPy"]:::backend
    end

    %% Backend Frameworks
    subgraph "Backend Frameworks"
        direction TB
        PyTorch["PyTorch"]:::backend
        TensorFlow["TensorFlow"]:::backend
        JAX["JAX"]:::backend
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        direction TB
        Zoo["foolbox/zoo/"]:::core
        Plot["foolbox/plot.py"]:::core
        TensorBoard["foolbox/tensorboard.py"]:::core
        Utils["foolbox/utils.py"]:::core
        Types["foolbox/types.py"]:::core
    end

    %% Infrastructure
    subgraph "Infrastructure & CI/CD"
        direction TB
        Tests["tests/"]:::infra
        CI_Tests[".github/workflows/tests.yml"]:::infra
        CI_Docs[".github/workflows/docs.yml"]:::infra
        CI_Guide[".github/workflows/guide.yml"]:::infra
        CI_PyPI[".github/workflows/pypi.yml"]:::infra
        Docs["docs/"]:::infra
        Guide["guide/"]:::infra
        Packaging["Packaging & Config"]:::infra
    end

    %% Packaging Files
    setup["setup.py"]:::infra
    pyproject["pyproject.toml"]:::infra
    setupcfg["setup.cfg"]:::infra
    manifest["MANIFEST.in"]:::infra
    requirements["requirements.txt"]:::infra
    readthedocs["readthedocs.yml"]:::infra

    %% Relationships
    Examples -->|uses API| API
    Performance -->|benchmarks via API| API
    API -->|selects attack| Attacks
    Attacks -->|uses criteria| Criteria
    Attacks -->|uses distance| Distances
    Attacks -->|invokes gradient| GradEst
    Attacks -->|uses dev utilities| DevUtils
    API -->|wraps model| Models
    Models -->|dispatches to| EagerPy
    EagerPy -->|calls| PyTorch
    EagerPy -->|calls| TensorFlow
    EagerPy -->|calls| JAX
    API -->|loads pretrained| Zoo
    API -->|plots results| Plot
    API -->|logs to TB| TensorBoard
    API -->|utility functions| Utils
    API -->|type definitions| Types
    Tests -->|test core| API
    Tests -->|test attacks| Attacks
    Tests -->|test criteria| Criteria
    Tests -->|test distances| Distances
    CI_Tests -->|runs| Tests
    CI_Docs -->|builds| Docs
    CI_Guide -->|builds| Guide
    CI_PyPI -->|publishes| Packaging
    Packaging -->|includes| setup
    Packaging -->|includes| pyproject
    Packaging -->|includes| setupcfg
    Packaging -->|includes| manifest
    Packaging -->|includes| requirements
    Packaging -->|includes| readthedocs

    %% Click Events
    click Examples "https://github.com/bethgelab/foolbox/tree/master/examples/"
    click Performance "https://github.com/bethgelab/foolbox/tree/master/performance/"
    click API "https://github.com/bethgelab/foolbox/blob/master/foolbox/__init__.py"
    click Attacks "https://github.com/bethgelab/foolbox/tree/master/foolbox/attacks/"
    click Criteria "https://github.com/bethgelab/foolbox/blob/master/foolbox/criteria.py"
    click Distances "https://github.com/bethgelab/foolbox/blob/master/foolbox/distances.py"
    click GradEst "https://github.com/bethgelab/foolbox/blob/master/foolbox/gradient_estimators.py"
    click DevUtils "https://github.com/bethgelab/foolbox/blob/master/foolbox/devutils.py"
    click Models "https://github.com/bethgelab/foolbox/tree/master/foolbox/models/"
    click Zoo "https://github.com/bethgelab/foolbox/tree/master/foolbox/zoo/"
    click Plot "https://github.com/bethgelab/foolbox/blob/master/foolbox/plot.py"
    click TensorBoard "https://github.com/bethgelab/foolbox/blob/master/foolbox/tensorboard.py"
    click Utils "https://github.com/bethgelab/foolbox/blob/master/foolbox/utils.py"
    click Types "https://github.com/bethgelab/foolbox/blob/master/foolbox/types.py"
    click CI_Tests "https://github.com/bethgelab/foolbox/blob/master/.github/workflows/tests.yml"
    click CI_Docs "https://github.com/bethgelab/foolbox/blob/master/.github/workflows/docs.yml"
    click CI_Guide "https://github.com/bethgelab/foolbox/blob/master/.github/workflows/guide.yml"
    click CI_PyPI "https://github.com/bethgelab/foolbox/blob/master/.github/workflows/pypi.yml"
    click Docs "https://github.com/bethgelab/foolbox/tree/master/docs/"
    click Guide "https://github.com/bethgelab/foolbox/tree/master/guide/"
    click Tests "https://github.com/bethgelab/foolbox/tree/master/tests/"
    click setup "https://github.com/bethgelab/foolbox/blob/master/setup.py"
    click pyproject "https://github.com/bethgelab/foolbox/blob/master/pyproject.toml"
    click setupcfg "https://github.com/bethgelab/foolbox/blob/master/setup.cfg"
    click manifest "https://github.com/bethgelab/foolbox/blob/master/MANIFEST.in"
    click requirements "https://github.com/bethgelab/foolbox/blob/master/requirements.txt"
    click readthedocs "https://github.com/bethgelab/foolbox/blob/master/readthedocs.yml"

    %% Styles
    classDef core fill:#D0E7FF,stroke:#3399FF,color:#000
    classDef backend fill:#DFF0D8,stroke:#3C763D,color:#000
    classDef infra fill:#FCF8E3,stroke:#8A6D3B,color:#000
    classDef ext fill:#F0F0F0,stroke:#999999,color:#000
```
