# lexsi-labs/dlbacktrace architecture

> Architecture diagram of the GitHub repository lexsi-labs/dlbacktrace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lexsi-labs/dlbacktrace
- Repository: https://github.com/lexsi-labs/dlbacktrace

## Overview

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: [`dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py`](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py) (DLBacktrace), [`dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py`](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py) (MoE backtrace), [`dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py`](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py) (Graph build), [`dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py`](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py) (Exec engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime_pytorch["PyTorch backtrace"]
  node_node_dlb_facade["DLBacktrace<br/>facade<br/>[dlbacktrace.py]"]
  node_node_graph_builder["Graph build<br/>trace graph<br/>[graph_builder.py]"]
  node_node_execution_engine["Exec engine<br/>runtime"]
  node_node_trace_utils["Trace utils<br/>runtime control<br/>[trace_utils.py]"]
  node_node_relevance["Relevance<br/>attribution"]
  node_node_relevance_saver["Save results<br/>persistence<br/>[relevance_saver.py]"]
  node_node_visualization["Visuals<br/>visualization<br/>[visualization.py]"]
  node_node_ops_semantics["Op semantics<br/>op registry<br/>[aten_operations.py]"]
  node_node_cuda_kernels["CUDA ops<br/>accelerators"]
  node_node_auto_sampler["Auto sampler<br/>workflow"]
end

subgraph group_group_runtime_moe["MoE backtrace"]
  node_node_moe_backtrace["MoE backtrace<br/>facade<br/>[backtrace.py]"]
  node_node_moe_models["Model adapters<br/>model family<br/>[model_utils.py]"]
  node_node_moe_core["MoE core<br/>pipeline<br/>[helper.py]"]
  node_node_moe_cuda["MoE CUDA<br/>accelerators"]
  node_node_moe_supported["Supported models<br/>registry"]
end

subgraph group_group_delivery["Delivery"]
  node_node_package_init["dl_backtrace<br/>[__init__.py]"]
  node_node_cli_main["CLI entry<br/>entrypoint<br/>[__main__.py]"]
  node_node_cli_engine["CLI engine<br/>[engine.py]"]
  node_node_cli_server["Server API<br/>[server.py]"]
  node_node_docs["Docs<br/>documentation<br/>[index.md]"]
  node_node_packaging["Packaging<br/>distribution<br/>[pyproject.toml]"]
end

node_node_package_init -->|"exports"| node_node_dlb_facade
node_node_package_init -->|"exports"| node_node_moe_backtrace
node_node_cli_main -->|"invokes"| node_node_cli_engine
node_node_cli_engine -->|"runs"| node_node_dlb_facade
node_node_cli_server -->|"serves"| node_node_dlb_facade
node_node_dlb_facade -->|"builds"| node_node_graph_builder
node_node_graph_builder -->|"feeds"| node_node_execution_engine
node_node_execution_engine -->|"normalizes"| node_node_ops_semantics
node_node_execution_engine -->|"accelerates"| node_node_cuda_kernels
node_node_graph_builder -->|"controls"| node_node_trace_utils
node_node_trace_utils -->|"stabilizes"| node_node_relevance
node_node_relevance -->|"persists"| node_node_relevance_saver
node_node_relevance -->|"renders"| node_node_visualization
node_node_auto_sampler -->|"orchestrates"| node_node_dlb_facade
node_node_moe_backtrace -->|"adapts"| node_node_moe_models
node_node_moe_backtrace -->|"coordinates"| node_node_moe_core
node_node_moe_core -->|"checks"| node_node_moe_supported
node_node_moe_core -->|"accelerates"| node_node_moe_cuda
node_node_moe_models -->|"uses"| node_node_moe_cuda
node_node_docs -.->|"documents"| node_node_dlb_facade
node_node_docs -.->|"documents"| node_node_moe_backtrace
node_node_packaging -.->|"packages"| node_node_dlb_facade

click node_node_package_init "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/__init__.py"
click node_node_cli_main "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/__main__.py"
click node_node_cli_engine "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/cli/engine.py"
click node_node_cli_server "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/cli/server.py"
click node_node_dlb_facade "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py"
click node_node_graph_builder "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py"
click node_node_execution_engine "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py"
click node_node_trace_utils "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/trace_utils.py"
click node_node_relevance "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_propagation.py"
click node_node_relevance_saver "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_saver.py"
click node_node_visualization "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/visualization.py"
click node_node_ops_semantics "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/aten_operations.py"
click node_node_cuda_kernels "https://github.com/lexsi-labs/dlbacktrace/tree/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/utils/cuda_utils"
click node_node_auto_sampler "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/dlb_auto_sampler.py"
click node_node_moe_backtrace "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py"
click node_node_moe_models "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/core/model_utils.py"
click node_node_moe_core "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/core/helper.py"
click node_node_moe_cuda "https://github.com/lexsi-labs/dlbacktrace/tree/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/utils/cuda_utils"
click node_node_moe_supported "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/supported_models.py"
click node_node_docs "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/docs/index.md"
click node_node_packaging "https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/pyproject.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_dlb_facade,node_node_graph_builder,node_node_execution_engine,node_node_trace_utils,node_node_relevance,node_node_relevance_saver,node_node_visualization,node_node_ops_semantics,node_node_cuda_kernels,node_node_auto_sampler toneBlue
class node_node_moe_backtrace,node_node_moe_models,node_node_moe_core,node_node_moe_cuda,node_node_moe_supported toneAmber
class node_node_package_init,node_node_cli_main,node_node_cli_engine,node_node_cli_server,node_node_docs,node_node_packaging toneMint
```

## Components

### PyTorch backtrace

Generic tracing and relevance propagation for standard PyTorch models.

- [DLBacktrace](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py): facade · Main Python-facing API for generic PyTorch explanations. · `dl_backtrace/pytorch_backtrace/dlbacktrace/dlbacktrace.py`
- [Graph build](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py): trace graph · Turns a model run into an execution graph. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/graph_builder.py`
- [Exec engine](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py): runtime · Runs traced forward execution without cache. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/execution_engine_noncache.py`
- [Trace utils](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/trace_utils.py): runtime control · Tracing, IO, and reproducibility helpers. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/trace_utils.py`
- [Relevance](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_propagation.py): attribution · Layerwise relevance propagation and compiled propagation. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_propagation.py`
- [Save results](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_saver.py): persistence · Persists attribution outputs for later use. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/relevance_saver.py`
- [Visuals](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/visualization.py): visualization · Token relevance and model-aware visualization helpers. · `dl_backtrace/pytorch_backtrace/dlbacktrace/core/visualization.py`
- [Op semantics](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/aten_operations.py): op registry · Normalizes ATen and activation-level tensor operations for explainability. · `dl_backtrace/pytorch_backtrace/dlbacktrace/aten_operations.py`
- [CUDA ops](https://github.com/lexsi-labs/dlbacktrace/tree/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/utils/cuda_utils): accelerators · Per-operation CUDA implementations and compiled extensions. · `dl_backtrace/pytorch_backtrace/dlbacktrace/utils/cuda_utils`
- [Auto sampler](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/pytorch_backtrace/dlbacktrace/core/dlb_auto_sampler.py): workflow · 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](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py): facade · Entry point for routed expert-model explanations. · `dl_backtrace/moe_pytorch_backtrace/backtrace/backtrace.py`
- [Model adapters](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/core/model_utils.py): model family · GPT-OSS, JetMoE, OLMoE, and Qwen3-MoE adapters. · `dl_backtrace/moe_pytorch_backtrace/backtrace/core/model_utils.py`
- [MoE core](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/core/helper.py): pipeline · Shared routing, helper, and auto-sampler logic for MoE tracing. · `dl_backtrace/moe_pytorch_backtrace/backtrace/core/helper.py`
- [MoE CUDA](https://github.com/lexsi-labs/dlbacktrace/tree/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/utils/cuda_utils): accelerators · Model-specific CUDA/tensor helpers for expert routing and scoring. · `dl_backtrace/moe_pytorch_backtrace/backtrace/utils/cuda_utils`
- [Supported models](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/moe_pytorch_backtrace/backtrace/supported_models.py): registry · 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](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/__init__.py): package · Top-level package entrypoint and namespace. · `dl_backtrace/__init__.py`
- [CLI entry](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/__main__.py): entrypoint · Module entrypoint for command-line use. · `dl_backtrace/__main__.py`
- [CLI engine](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/cli/engine.py): cli · Command-line orchestration layer. · `dl_backtrace/cli/engine.py`
- [Server API](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/dl_backtrace/cli/server.py): server · Server-facing entrypoint for running the library as a service. · `dl_backtrace/cli/server.py`
- [Docs](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/docs/index.md): documentation · MkDocs-based guides, architecture notes, and examples. · `docs/index.md`
- [Packaging](https://github.com/lexsi-labs/dlbacktrace/blob/dlb_v2/pyproject.toml): distribution · Project metadata and packaging for Python distribution. · `pyproject.toml`

## Connections

- 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.
