# inseq-team/inseq architecture

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

- Interactive diagram: https://gitdiagram.com/inseq-team/inseq
- Repository: https://github.com/inseq-team/inseq

## Overview

##### Main components of the system
- Core Library (the "inseq" directory): This contains the main modules including:
- Attribution Methods (inseq/attr): Implements various gradient-based, internal-based, and perturbation-based methods.
- Command Interfaces (inseq/commands): Provides CLI wrappers and utilities for running attribution analyses.
- Models (inseq/models): Contains model wrappers and configurations (e.g. for encoder–decoder, decoder-only).
- Data Handling (inseq/data): Modules dealing with data aggregation, batching, and visualization utilities.
- Utilities (inseq/utils): Contains helper functions for error handling, caching, visualization, registry, etc.
- Documentation and Examples:
- Docs (docs/): Contains Sphinx documentation sources, static assets, and example HTML outputs.
- Examples (examples/): Jupyter notebooks and tutorials showing how to use the library.
- Testing:
- Tests (tests/): Unit tests covering different modules (attribution methods, commands, models, etc.)
- Build and Deployment:
- Docker (docker/): Dockerfile for containerized setups.
- CI/CD configurations (.github/workflows, Makefile, pre-commit configurations).

##### Relationships and interactions
- User Interaction Layer:
- Users can interface via the CLI (“inseq attribute”, “inseq attribute-dataset”, “inseq attribute-context”) or by calling the Python API (e.g. “inseq.load_model”, then “model.attribute”).
- These interactions rely on a consistent API that ties into the core modules.
- API / Core Engine:
- The CLI and direct Python API both call into core modules that abstract over model loading (often from Hugging Face) as well as the selection of attribution methods.
- Attribution methods are implemented in submodules that work by processing input texts, retrieving model predictions, and then backpropagating gradients (or performing other perturbation/inference steps).
- Aggregation and visualization utilities (in commands, data, and utils) take the raw attribution outputs and produce human-friendly outputs (HTML, notebook visuals, or CLI prints).
- External Dependencies:
- Hugging Face Transformers for model handling.
- PyTorch for backpropagation and gradient computations.
- Optionally Captum for certain attribution implementations.
- Docker and workflow tools help build, test, and deploy the system.

##### Important architectural patterns and design principles
- Modular Design: Core functionality is divided across sub-packages (attr, commands, data, models, utils) which makes it easy to extend and maintain.
- Extensibility: The framework supports adding new attribution methods or step functions (see README sections on supported methods and step functions).
- Separation of Concerns: Clear delineation between API/CLI interfaces, attribution logic, and visualization modules.

##### Relevant technologies
- Main languages/technologies: Python (with PyTorch), Docker for containerization, and standard CI/CD tools (GitHub Actions, Makefile).
- Frameworks/Libraries: Hugging Face Transformers, Captum (for interpretability reference), and possibly Jupyter for notebooks.

- Use clearly labeled nodes for each component:
- User Interface (CLI & Notebooks)
- API Module (inseq.load_model and model.attribute)
- Attribution Methods Module (with sub-components for gradient-based, attention-based, perturbation-based, etc.)
- Model Module (handling model wrappers/configurations)
- Data Aggregation & Visualization Module (Aggregator, Viz Helpers)
- External Dependencies (Hugging Face Transformers, PyTorch)
- Integration & Testing (CI/CD, Docker, Tests)
- From the API to the Attribution Methods Module to show how input text is processed and attributions computed.
- From Attribution Methods to Data Visualization to represent post-processing.
- For example, use blue for core modules, green for interfaces, and grey for infrastructure/CI files.

- Avoid over-complication – capture the module boundaries and their responsibilities as clearly as possible.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    UI["User Interface (CLI & Notebooks)"]:::ui
    API["API Module (Python API calls)"]:::ui
    UI -->|"invoke"| API

    %% Core Library Subgraph
    subgraph "Core Library (inseq)"
        CORE["Core Library"]:::core
        A["Attribution Methods"]:::core
        B["Command Interfaces"]:::core
        C["Models"]:::core
        D["Data Handling"]:::core
        E["Utilities"]:::core
        
        CORE --> A
        CORE --> B
        CORE --> C
        CORE --> D
        CORE --> E
    end

    %% API interactions with Core modules
    API -->|"calls"| B
    API -->|"calls"| A
    API -->|"loads"| C

    %% Internal Core relationships
    A -->|"processes"| D
    E -->|"supports"| A
    E -->|"supports"| C
    E -->|"supports"| D

    %% External Dependencies
    external["External Dependencies (Hugging Face, PyTorch, Captum)"]:::infra
    external -->|"provideModels"| C

    %% Integration & Testing Subgraph
    subgraph "Integration & Testing"
        F["Documentation"]:::infra
        G["Examples"]:::infra
        H["Tests"]:::infra
        I["Docker"]:::infra
        J["CI/CD & Build Configurations"]:::infra
    end

    %% Connections to Integration & Testing
    B -->|"testedBy"| H
    E -->|"aidsTesting"| H
    API -->|"integratesWithDoc"| F
    API -->|"integratesWithEx"| G
    API -->|"integratesWithDocker"| I
    API -->|"integratesWithCI"| J

    %% Styles
    classDef ui fill:#cfc,stroke:#333,stroke-width:2px;
    classDef core fill:#ccf,stroke:#333,stroke-width:2px;
    classDef infra fill:#eee,stroke:#333,stroke-width:2px;

    %% Click Events for Component Mapping
    click CORE "https://github.com/inseq-team/inseq/tree/main/inseq"
    click A "https://github.com/inseq-team/inseq/tree/main/inseq/attr"
    click B "https://github.com/inseq-team/inseq/tree/main/inseq/commands"
    click C "https://github.com/inseq-team/inseq/tree/main/inseq/models"
    click D "https://github.com/inseq-team/inseq/tree/main/inseq/data"
    click E "https://github.com/inseq-team/inseq/tree/main/inseq/utils"
    click F "https://github.com/inseq-team/inseq/tree/main/docs"
    click G "https://github.com/inseq-team/inseq/blob/main/examples/inseq_tutorial.ipynb"
    click H "https://github.com/inseq-team/inseq/tree/main/tests"
    click I "https://github.com/inseq-team/inseq/tree/main/docker"
    click J "https://github.com/inseq-team/inseq/blob/main/.github"
```
