How lexsi-labs/dlbacktrace works
1. What this repo is
DLBacktrace is a Python library for model explainability, with two main runtime paths: a generic PyTorch backtrace engine and a Mixture-of-Experts (MoE) backtrace engine. The package is designed to be imported and used in-process, but it also exposes CLI/server entry points.
2. Top-level architecture
The repository is split around dl_backtrace/pytorch_backtrace and dl_backtrace/moe_pytorch_backtrace. The first handles broad PyTorch models; the second contains model-family-specific logic for GPT-OSS, JetMoE, OLMoE, and Qwen3-MoE. This is the key architectural boundary in the repo.
3. Primary data flow for standard models
For ordinary PyTorch models, the flow is: user model + input tensors → DLBacktrace → graph/tracing capture → execution engine runs the forward pass → relevance propagation computes layerwise attribution → results are saved and optionally visualized. The README’s predict(), evaluation(), and run_task() calls map directly onto that flow.
4. Generic tracing and execution core
The pytorch_backtrace/dlbacktrace/core package is the heart of the system. It includes:
- graph_builder for turning a model run into an execution graph,
- execution_engine_noncache for non-cached forward execution,
- trace_utils, io_utils, and reproducibility for runtime control,
- relevance_propagation and compiled_propagation for backpropagating importance,
- relevance_saver and visualization modules for persistence and display.
This is the main “engine room” that an architecture diagram should show.
5. Operation coverage and tensor semantics
The generic engine explicitly supports a large set of PyTorch operations: linear, convolution, pooling, embeddings, LSTM, normalization, reshape/view, concatenation, indexing, and negative-index tensor manipulation. aten_operations.py and activation.py indicate that the framework normalizes low-level tensor ops into explainable units instead of treating only high-level layers as special cases.
6. CUDA acceleration boundary
Performance-critical operators are implemented under pytorch_backtrace/dlbacktrace/utils/cuda_utils. This directory contains per-op CUDA implementations, each typically organized into original_version, pytorch_version, and refactored_version, plus some compiled C++/CUDA extension subtrees such as Linear_v3, SelfAttention, Embedded, and pooling kernels. The architecture here is “Python orchestration + optional custom CUDA kernels.”
7. Determinism and runtime control
The generic pipeline includes deterministic execution setup and reproducibility helpers. That matters architecturally because the library is not just doing attribution; it is also controlling random seeds, CUDA behavior, and runtime settings so the traced relevance results are stable across runs.
8. MoE subsystem
The MoE package has its own backtrace pipeline because routing/expert selection must be handled differently from standard dense models. moe_pytorch_backtrace/backtrace/backtrace.py is the main entry point, with supported_models.py, model_utils.py, and model-specific modules for GPT-OSS, JetMoE, OLMoE, and Qwen3-MoE. The output is not only token/layer relevance, but also expert-level relevance across routed layers.
9. MoE-specific data flow
For MoE models, the flow is: Hugging Face model + tokenizer inputs → model-family adapter → routing/expert capture → backtrace over experts and layers → generated outputs and expert relevance maps. The helper_cuda and model-specific cuda_utils directories suggest that some expert-routing calculations are also accelerated with custom kernels or specialized tensor logic.
10. High-level task wrappers
The README’s run_task() and the DLBAutoSampler show that the repo includes higher-level orchestration above raw attribution. These wrappers handle text classification and generation workflows, sampling strategies like greedy/beam/top-k/top-p, and token-level relevance tracking. In a diagram, they sit above the core tracing engine as convenience/application-layer orchestration.
11. External dependencies that shape the architecture
The repository is built around Python 3.8+, PyTorch 2.6+, and, for many models, the Hugging Face Transformers ecosystem. CUDA is a major runtime dependency for acceleration, while plotting/visualization libraries support reporting rather than core execution.
12. Packaging, docs, and delivery
The repo is packaged as a distributable Python project (pyproject.toml, MANIFEST.in, requirements.txt) and includes MkDocs-based documentation plus GitHub Actions for release and docs publishing. These are important for delivery and support, but they are peripheral to the runtime architecture itself.
Main entry points: dlbacktrace.py DLBacktrace · backtrace.py MoE backtrace · graph_builder.py Graph build · execution_engine_noncache.py Exec engine
Components 21
PyTorch backtrace
Generic tracing and relevance propagation for standard PyTorch models.
- DLBacktrace · Main Python-facing API for generic PyTorch explanations.
dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py - Graph build · Turns a model run into an execution graph.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py - Exec engine · Runs traced forward execution without cache.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py - Trace utils · Tracing, IO, and reproducibility helpers.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/trace_utils.py - Relevance · Layerwise relevance propagation and compiled propagation.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_propagation.py - Save results · Persists attribution outputs for later use.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_saver.py - Visuals · Token relevance and model-aware visualization helpers.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/visualization.py - Op semantics · Normalizes ATen and activation-level tensor operations for explainability.
dl_backtrace/pytorch_backtrace/dlbacktrace/aten_operations.py - CUDA ops · Per-operation CUDA implementations and compiled extensions.
dl_backtrace/pytorch_backtrace/dlbacktrace/utils/cuda_utils - Auto sampler · Higher-level task orchestration and sampling for runs.
dl_backtrace/pytorch_backtrace/dlbacktrace/core/dlb_auto_sampler.py
MoE backtrace
Model-family-specific backtrace pipeline for routed expert models.
- MoE backtrace · Entry point for routed expert-model explanations.
dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py - Model adapters · GPT-OSS, JetMoE, OLMoE, and Qwen3-MoE adapters.
dl_backtrace/moe_pytorch_backtrace/backtrace/core/model_utils.py - MoE core · Shared routing, helper, and auto-sampler logic for MoE tracing.
dl_backtrace/moe_pytorch_backtrace/backtrace/core/helper.py - MoE CUDA · Model-specific CUDA/tensor helpers for expert routing and scoring.
dl_backtrace/moe_pytorch_backtrace/backtrace/utils/cuda_utils - Supported models · Lists the MoE model families handled by the backtrace pipeline.
dl_backtrace/moe_pytorch_backtrace/backtrace/supported_models.py
Delivery
CLI, server entrypoints, packaging, and documentation.
- dl_backtrace · Top-level package entrypoint and namespace.
dl_backtrace/__init__.py - CLI entry · Module entrypoint for command-line use.
dl_backtrace/__main__.py - CLI engine · Command-line orchestration layer.
dl_backtrace/cli/engine.py - Server API · Server-facing entrypoint for running the library as a service.
dl_backtrace/cli/server.py - Docs · MkDocs-based guides, architecture notes, and examples.
docs/index.md - Packaging · Project metadata and packaging for Python distribution.
pyproject.toml
Connections 22
- dl_backtrace → DLBacktrace: exports · Package namespace exposes the main explainability API.
- dl_backtrace → MoE backtrace: exports · Package namespace also exposes the MoE pipeline.
- CLI entry → CLI engine: invokes · Module entrypoint dispatches to CLI orchestration.
- CLI engine → DLBacktrace: runs · CLI workflows drive the generic backtrace API.
- Server API → DLBacktrace: serves · Server entrypoint wraps the main explanation pipeline.
- DLBacktrace → Graph build: builds · Captures a model execution graph from the input run.
- Graph build → Exec engine: feeds · Graph construction hands off to forward execution.
- Exec engine → Op semantics: normalizes · Execution uses operation semantics to interpret tensor ops.
- Exec engine → CUDA ops: accelerates · Optional custom kernels speed up heavy operators.
- Graph build → Trace utils: controls · Tracing utilities manage IO, determinism, and runtime state.
- Trace utils → Relevance: stabilizes · Relevance computation depends on reproducible runtime settings.
- Relevance → Save results: persists · Attribution outputs are saved for later inspection.
- Relevance → Visuals: renders · Relevance maps feed visual reporting helpers.
- Auto sampler → DLBacktrace: orchestrates · Higher-level workflows wrap the core explanation engine.
- MoE backtrace → Model adapters: adapts · Main MoE entrypoint delegates to model-family adapters.
- MoE backtrace → MoE core: coordinates · Shared MoE pipeline logic handles routing and backtrace flow.
- MoE core → Supported models: checks · Core pipeline gates behavior on supported model families.
- MoE core → MoE CUDA: accelerates · MoE-specific routing and scoring can use custom CUDA helpers.
- Model adapters → MoE CUDA: uses · Model adapters rely on family-specific tensor and kernel logic.
- Docs → DLBacktrace: documents · Documentation describes the generic API and workflow.
- Docs → MoE backtrace: documents · Documentation also covers the MoE architecture and usage.
- Packaging → DLBacktrace: packages · Project metadata builds the distributable Python library.