# qdata/textattack architecture

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

- Interactive diagram: https://gitdiagram.com/qdata/textattack
- Repository: https://github.com/qdata/textattack

## Overview

##### Main components
- User Interface/CLI Layer: The entry point for users is via the command-line (see files like textattack/__main__.py and the commands submodule). This layer parses user commands (attack, augment, train, list, etc.) and routes them to the appropriate modules.
- Core Framework / Attack Engine: This includes the central “textattack” package that houses various modules:
– Attack Recipes & Attack Components: Modules under textattack/attack.py, attack_recipes, attacker.py and goal_functions define how an attack is structured.
– Constraint Modules: Found in textattack/constraints (and its subdirectories, e.g., for grammaticality, overlap, semantics) that enforce which adversarial perturbations are allowed.
– Transformation Modules: Within textattack/transformations (and its submodules like word swaps, word insertions, etc.) that generate candidate perturbations.
– Search Methods: Located in textattack/search_methods (e.g., greedy search, genetic algorithms, beam search) which explore the space of adversarial examples.
– Logging and Results: Under textattack/loggers and textattack/attack_results handle output logging, summaries, and metrics.
– Augmentation and Training: Modules dedicated to data augmentation (textattack/augmentation) and model training (textattack/train and related examples).
– Datasets and Model Wrappers: Modules like textattack/models, dataset arguments, and integration files (also see examples for dataset handling and HuggingFace integration).

##### Relationships and interactions between the components
- The CLI layer receives a user command (for attacking, augmenting, or training). It then instantiates the necessary components from the core framework.
- The attack flow is modular: The Controller (or Attack Runner) combines a Goal Function, a set of Constraints, and one or more Transformations. It then applies a Search Method to drive changes in the “AttackedText” instance.
- There are clear dependencies between these components, e.g.: the Transformation module produces candidate perturbations that are examined by the Constraints module, and if those satisfy the Goal Function then the Search Method can mark the attack as successful.
- For augmentation, similar patterns exist: the Augmenter uses a Transformation pipeline and constraints to generate text variants; sometimes this is combined with an external language model (via HuggingFace wrappers) for prompt augmentation.

##### Important architectural patterns and technologies
- Modular design: each “attack” is decomposed into its own subcomponents, making it easy to swap in new constraints, transformations, or search strategies.
- Model-agnostic abstraction: The framework is designed to work with arbitrary models (including models from HuggingFace), thanks to its abstraction around model interfaces (model wrappers).
- Extensibility: The clear separation between goal functions, constraints, transformations, and search methods supports extension (e.g., adding new attack recipes is as simple as adding a new module under attack_recipes).
- Documentation & Testing: The project includes comprehensive documentation (docs/) and tests (tests/), indicating robust quality practices that can be shown as ancillary components.

– User/CLI Interface
– Core Attack Engine (with subcomponents: goal functions, constraints, transformations, search methods)
– Augmentation Module
– Model & Dataset Management (with integration to external libraries such as HuggingFace)
– Logging and Reporting
– From the CLI to the Attack Engine
– Between the transformational components (candidate generation → constraint filtering → goal evaluation)
– From the Attack Engine to Logging & Output
– External interfaces (CLI, configuration, model loading)
– Core algorithmic components (attacks, constraints, transformations)
– Support components (documentation, testing, CI workflows)

##### Detail-level
– The top layer: User Input (CLI command, interactive usage)
– The orchestration layer: Attack Controller / Runner coordinating components
– The component layer: modules for constraints, transformations, searches, logging, etc.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input / CLI Layer
    subgraph "User Input / CLI"
        CLI_Main["CLI: textattack/__main__.py"]:::cli
        CLI_CLI["CLI: textattack/commands/textattack_cli.py"]:::cli
    end

    %% Core Attack Engine Layer
    subgraph "Core Attack Engine"
        AttackEngine["Attack Engine: textattack/attack.py"]:::core
        Attacker["Attacker (Attack Runner): textattack/attacker.py"]:::core
        AttackRecipes["Attack Recipes: textattack/attack_recipes"]:::core
        Constraints["Constraints Modules: textattack/constraints"]:::core
        Transformations["Transformation Modules: textattack/transformations"]:::core
        SearchMethods["Search Methods: textattack/search_methods"]:::core
    end

    %% Logging & Reporting Layer
    subgraph "Logging & Reporting"
        Loggers["Loggers: textattack/loggers"]:::support
        AttackResults["Attack Results: textattack/attack_results"]:::support
    end

    %% Augmentation Module Layer
    subgraph "Augmentation Module"
        Augmentation["Augmentation: textattack/augmentation"]:::core
        AugmentArgs["Augment Args: textattack/augment_args.py"]:::core
    end

    %% Model & Dataset Management Layer
    subgraph "Model & Dataset Management"
        Models["Models: textattack/models"]:::support
        Datasets["Datasets: textattack/datasets"]:::support
        DatasetArgs["Dataset Args: textattack/dataset_args.py"]:::support
        ModelArgs["Model Args: textattack/model_args.py"]:::support
    end

    %% External & Support Infrastructure
    subgraph "External & Support Infrastructure"
        CI["CI/CD: GitHub Workflows"]:::external
        Docs["Documentation: docs/"]:::external
        Tests["Testing: tests/"]:::external
        HuggingFace["HuggingFace Integration"]:::external
    end

    %% Connections from User Input to Core Attack Engine
    CLI_Main --> Attacker
    CLI_CLI  --> Attacker

    %% Connections within Core Attack Engine
    Attacker -->|"uses"| AttackRecipes
    Attacker -->|"applies"| Transformations
    Attacker -->|"validates with"| Constraints
    Attacker -->|"explores using"| SearchMethods
    AttackEngine --> Attacker

    %% Connections from Core Engine to Logging & Reporting
    Attacker -->|"logs to"| Loggers
    Attacker -->|"reports via"| AttackResults

    %% Augmentation Module connections
    Augmentation -->|"utilizes"| Transformations
    Augmentation -->|"applies"| Constraints
    Augmentation --> AugmentArgs
    %% Model & Dataset support for Augmentation
    Models --> Augmentation
    Datasets --> Augmentation

    %% External dependencies for Model & Dataset Management
    HuggingFace --> Models
    HuggingFace --> Datasets

    %% External infrastructure supports overall system
    CI --> Attacker
    Docs --> Attacker
    Tests --> Attacker

    %% Styling classes
    classDef cli fill:#f4a261,stroke:#000,stroke-width:2px;
    classDef core fill:#2a9d8f,stroke:#000,stroke-width:2px;
    classDef support fill:#e9c46a,stroke:#000,stroke-width:2px;
    classDef external fill:#e76f51,stroke:#000,stroke-width:2px;

    %% Click Events
    click CLI_Main "https://github.com/qdata/textattack/blob/master/textattack/__main__.py"
    click CLI_CLI "https://github.com/qdata/textattack/blob/master/textattack/commands/textattack_cli.py"
    click AttackEngine "https://github.com/qdata/textattack/blob/master/textattack/attack.py"
    click Attacker "https://github.com/qdata/textattack/blob/master/textattack/attacker.py"
    click AttackRecipes "https://github.com/qdata/textattack/tree/master/textattack/attack_recipes"
    click Constraints "https://github.com/qdata/textattack/tree/master/textattack/constraints"
    click Transformations "https://github.com/qdata/textattack/tree/master/textattack/transformations"
    click SearchMethods "https://github.com/qdata/textattack/tree/master/textattack/search_methods"
    click Loggers "https://github.com/qdata/textattack/tree/master/textattack/loggers"
    click AttackResults "https://github.com/qdata/textattack/tree/master/textattack/attack_results"
    click Augmentation "https://github.com/qdata/textattack/tree/master/textattack/augmentation"
    click AugmentArgs "https://github.com/qdata/textattack/blob/master/textattack/augment_args.py"
    click Models "https://github.com/qdata/textattack/tree/master/textattack/models"
    click Datasets "https://github.com/qdata/textattack/tree/master/textattack/datasets"
    click DatasetArgs "https://github.com/qdata/textattack/blob/master/textattack/dataset_args.py"
    click ModelArgs "https://github.com/qdata/textattack/blob/master/textattack/model_args.py"
```
