How inseq-team/inseq works
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.