Metadata-Version: 2.4
Name: compilerlens
Version: 0.1.1
Summary: Inspect model compilation and trace compiler-recorded lineage into LLVM and assembly
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/Soumyaworks/CompilerLens
Project-URL: Issues, https://github.com/Soumyaworks/CompilerLens/issues
Project-URL: Documentation, https://github.com/Soumyaworks/CompilerLens#readme
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich<16,>=13
Requires-Dist: numpy<3,>=2
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: uvicorn<1,>=0.30
Requires-Dist: torch==2.13.0
Requires-Dist: iree-base-compiler==3.11.0
Requires-Dist: iree-base-runtime==3.11.0
Requires-Dist: iree-turbine==3.9.0
Requires-Dist: transformers==5.16.1
Requires-Dist: huggingface-hub<2,>=1
Dynamic: license-file

# CompilerLens

CompilerLens is an interactive explorer for AI compiler pipelines. It compiles a PyTorch or
Hugging Face model through IREE and presents the resulting Torch, MLIR, LLVM IR, and x86-64
stages in one navigable interface.

<p align="center">
  <img src="docs/images/CompilerLens_frontpage.png" alt="CompilerLens landing page with Hugging Face model search, the MLIR lowering pipeline, and Compiler Playground" width="100%">
</p>

<p align="center"><em>Search and compile Hugging Face models, follow the lowering path, or experiment in the Compiler Playground.</em></p>

## Table of Contents

- [Key Capabilities](#key-capabilities)
- [System Architecture and Repository Layout](#system-architecture-and-repository-layout)
- [System Requirements](#system-requirements)
- [CLI Quick Start](#cli-quick-start)
- [Installation from Source](#installation-from-source)
- [Running CompilerLens Locally](#running-compilerlens-locally)
- [Compiling Models from the Web Interface](#compiling-models-from-the-web-interface)
- [Supported Model Architectures](#supported-model-architectures)
- [Repository Compilation Script](#repository-compilation-script)
- [Compiler Playground and Benchmarking](#compiler-playground-and-benchmarking)
- [Validation and Testing](#validation-and-testing)
- [Troubleshooting](#troubleshooting)
- [Contributions](#contributions)
- [Citation](#citation)
- [License](#license)

## Key Capabilities

- A searchable timeline of compiler stages and passes
- An interactive model architecture map linked to the operations each module exports
- Side-by-side textual and semantic diffs
- Compiler evidence linked directly to the IR that produced it
- Compiler-recorded operation lineage from framework-level operations through LLVM IR and assembly
- A landing-page search flow that compiles a Hugging Face model and adds it as a workload
- A Compiler Playground for changing selected compiler options and benchmarking the result
- An installable CLI for capturing, inspecting, tracing, comparing, and benchmarking saved runs
- A bundled browser viewer for opening CLI captures without a separate frontend setup

## System Architecture and Repository Layout

CompilerLens separates model acquisition, compilation, artifact construction, and
visualization. The normalized artifact is the contract between the Python compiler pipeline and
the TypeScript frontend.

### End-to-end data flow

```mermaid
%%{init: {"theme":"base","themeVariables":{"background":"#080c12","primaryTextColor":"#e5e7eb","lineColor":"#64748b","fontFamily":"ui-monospace, SFMono-Regular, Menlo, monospace","clusterBkg":"#0b111b","clusterBorder":"#334155","edgeLabelBackground":"#111827"},"flowchart":{"curve":"linear","nodeSpacing":36,"rankSpacing":48}}}%%
flowchart TB
    subgraph Entry["1 · CLI and web entry points"]
        direction LR
        CLI["CLI · compile<br/>HF model · packaged example · Python factory"]
        Import["CLI · import<br/>Existing compiler dumps"]
        Search["Web · Model search<br/>Compile and explore a Hugging Face model"]
        Controls["Web · Compiler Playground<br/>Choose model, stage, and flags"]
    end

    subgraph Service["2 · Shared services and web orchestration"]
        direction LR
        Explore["FastAPI · Explore job<br/>POST /explore"]
        Shared["Shared capture service<br/>Parameters · progress · run manifest"]
        Compile["FastAPI · Playground job<br/>POST /compile"]
    end

    subgraph Preparation["3 · Model preparation and export"]
        direction TB
        Resolve["Hugging Face Hub or cache<br/>Resolve revision · load model · build inputs"]
        Local["Packaged example or Python factory<br/>Build module and example tensors"]
        Export["PyTorch export + IREE Turbine AOT<br/>Capture module ownership · emit Torch MLIR"]
        Mode{"Capture or Playground?"}

        Resolve --> Export
        Local --> Export
        Export --> Mode
    end

    subgraph Compilation["4 · IREE compilation, analysis, and results"]
        direction LR

        subgraph Persistent["Saved capture · CLI and web Explore"]
            direction TB
            Capture["IREE pipeline capture<br/>iree-compile + iree-opt · debug information"]
            Dumps[("Captured compiler files<br/>MLIR · pass logs · LLVM IR · assembly · objects")]
            Analyze["LLVM analysis + Python artifact construction<br/>Instruction reports · source joins · architecture · diffs"]
            Run[("Self-contained run<br/>Artifacts · lineage · saved tensors · versions and hashes")]
            Terminal["CLI · inspect / trace / diff<br/>Terminal tables, IR, and JSON"]
            SavedBenchmark["CLI · bench<br/>IREE runtime + saved input tensors"]
            Explorer["Browser · CLI view or web library<br/>Architecture · Pipeline · Operation Lineage"]

            Capture --> Dumps --> Analyze --> Run
            Run --> Terminal
            Run -->|view or web publication| Explorer
            Run -.-> SavedBenchmark -.-> Terminal
        end

        subgraph TemporaryPath["Compiler Playground · selected stages"]
            direction TB
            Selected["Focused IREE compilation<br/>Selected IR stage + executable VMFB"]
            Temporary[("Job files · jobs/job-id/<br/>Selected IR · VMFB · benchmark inputs")]
            JobState[("In-memory job state<br/>Status · signals · output paths")]
            Benchmark["Optional web benchmark<br/>iree-benchmark-module"]
            Results["Playground interface<br/>Generated IR · signals · timing"]

            Selected --> Temporary --> JobState --> Results
            Temporary -.-> Benchmark -.-> JobState
        end
    end

    CLI --> Shared
    Search --> Explore --> Shared
    Controls --> Compile
    Shared --> Resolve
    Shared --> Local
    Compile --> Resolve
    Import -->|copy existing dumps into a new run| Dumps
    Mode -->|CLI or web Explore| Capture
    Mode -->|Web Playground| Selected

    class CLI,Import,Search,Controls,Terminal,Explorer,Results ui
    class Explore,Shared,Compile api
    class Resolve,Local model
    class Export,Capture,Selected,Benchmark,SavedBenchmark compiler
    class Mode decision
    class Dumps,Run persistent
    class Temporary,JobState transient
    class Analyze analysis

    classDef ui fill:#10243e,stroke:#4f9cf9,color:#edf6ff,stroke-width:2px
    classDef api fill:#24183d,stroke:#9b87f5,color:#f4f0ff,stroke-width:2px
    classDef model fill:#332315,stroke:#f59e0b,color:#fff7ed,stroke-width:2px
    classDef compiler fill:#321827,stroke:#ec6fa5,color:#fff1f7,stroke-width:2px
    classDef decision fill:#202938,stroke:#94a3b8,color:#f8fafc,stroke-width:2px
    classDef persistent fill:#0f2b24,stroke:#34d399,color:#ecfdf5,stroke-width:2px
    classDef transient fill:#2c230e,stroke:#eabf4f,color:#fffbeb,stroke-width:2px
    classDef analysis fill:#0d2931,stroke:#35b9c9,color:#ecfeff,stroke-width:2px

    style Entry fill:#0b172a,stroke:#27496f,stroke-width:1px,color:#bfdbfe
    style Service fill:#17122b,stroke:#4c3b78,stroke-width:1px,color:#ddd6fe
    style Preparation fill:#24170f,stroke:#70451d,stroke-width:1px,color:#fed7aa
    style Compilation fill:#090e16,stroke:#334155,stroke-width:1px,color:#cbd5e1
    style Persistent fill:#0a1e1a,stroke:#1f6f58,stroke-width:1px,color:#a7f3d0
    style TemporaryPath fill:#1d180b,stroke:#735d16,stroke-width:1px,color:#fde68a
```

Blue nodes are user-facing CLI and browser surfaces; violet nodes coordinate work;
orange nodes prepare models; pink nodes execute compiler or runtime tools; teal nodes
analyze compiler output; green nodes store saved captures; amber nodes hold Playground
files and job state. Solid arrows show the main flow; dashed arrows show optional benchmarking.

The CLI and web model search use the same capture service:

1. Choose a Hugging Face model, or use a packaged example or local Python factory through the CLI.
2. Prepare the model and actual input tensors, resolve the model revision, and export through
   PyTorch and IREE Turbine while capturing model-module ownership.
3. Run IREE and retain MLIR stages, pass logs, LLVM snapshots, assembly, and object files.
4. Analyze LLVM snapshots with the C++ pass and join compiler source locations in Python.
   Build architecture mappings, operation lineage, diffs, and the browser artifact. See the
   [LLVM component guide](llvm/README.md) for the analysis details and coverage limits.
5. Save a self-contained run. CLI captures use `--out` or a fresh directory under
   `compilerlens-runs/`; web Explore uses `runs/<job-id>/` in the configured workspace.
6. Inspect or trace the saved run in the terminal, benchmark its captured inputs, or open it
   in the existing browser viewer with `compilerlens view`. Web Explore also publishes its
   artifact and workload entry to the browser library under `frontend/public/artifacts/`.

`compilerlens import` starts from existing dumps and builds a new analyzed run without
recompiling the model. The static developer workflow can also build browser artifacts from
existing dumps using `npm run artifact`.

The Compiler Playground exports the selected Hugging Face model and compiles requested stages
into `jobs/<job-id>/`. It exposes IR, compiler signals, and optional timings directly through
job state. Restarting the API loses that in-memory state; generated files remain on disk.
The saved-capture path retains artifacts that remain available in the workload library.

### Model architecture to compiler bridge

Each workload first opens an interactive module hierarchy. The explorer shows model facts,
parameter counts, observed tensor shapes, exported Torch operations, and compiler-stage
coverage. Selecting a module reveals where its operations survive across the lowering phases;
**Trace through compiler** opens that module's source operation directly in Operation Lineage.

<p align="center">
  <img src="docs/images/model_architecture.png" alt="CompilerLens model architecture explorer showing the six transformer blocks of EleutherAI Pythia 70M, module details, and compiler-stage coverage" width="100%">
</p>

<p align="center"><em>Pythia 70M's transformer structure connected directly to its compiler-stage lineage.</em></p>

For newly compiled Hugging Face models, module ownership comes from `torch.export`'s
`nn_module_stack` metadata and is accepted only when the complete decomposed FX operation stream
matches the Torch MLIR stream. Older workloads without this sidecar receive a clearly labelled,
compiler-derived operation topology; CompilerLens does not invent layer ownership.

### Interactive pipeline workspace

Each compiled workload opens as a configurable workspace. Developers can inspect the original
PyTorch source beside any captured IR stage, follow the phase rail from frontend lowering to
binary output, compare representations, and trace compiler evidence back to the stage that
produced it.

<p align="center">
  <img src="docs/images/pipeline-explorer.png" alt="CompilerLens pipeline workspace for EleutherAI Pythia 70M showing PyTorch source, Torch MLIR, target assembly, and compiler evidence" width="100%">
</p>

<p align="center"><em>The Pythia 70M pipeline viewed across framework source, compiler IR, target assembly, and evidence.</em></p>

### Artifact contract

Each workload is represented by one normalized JSON document containing:

- Model and compilation metadata
- Ordered compiler stages with complete IR text
- Operation summaries and histograms
- Track-aware stage diffs
- Compiler evidence with source-stage references
- Source-to-stage operation lineage
- Model hierarchy, tensor shapes, parameter counts, and module-to-compiler mappings
- Explicit notes for incomplete or unavailable compiler data

The Python schema is defined in `compilerlens/ingest/schema.py` and mirrored by
`frontend/src/api/artifact.ts`. A schema change must update both definitions and increment the
artifact version.

### Runtime modes

| Mode | Entry point | API required | Persistence | Primary purpose |
|---|---|---:|---|---|
| Static explorer | `npm run artifact` + `npm run dev` | No | Generated artifact files | Explore existing compiler dumps |
| Web model search | Model search field on the landing page | Yes | Dumps and artifact are retained | Add a Hugging Face model end to end |
| Compiler Playground | **Open the Compiler Playground** | Yes | Job files; status in memory | Test compiler options and selected stages |
| CLI capture and analysis | `compilerlens compile` / `import` / `inspect` / `trace` | No | Self-contained run directory | Capture, query, compare, and benchmark models |
| Bundled viewer | `compilerlens view RUN` | Started by the command | Reads saved runs | Explore CLI captures in the browser |
| Repository compilation script | `scripts/compile_hf_model.py` | No | Dumps under `examples/` | Generate dumps for the static developer workflow |

### Repository layout

```text
CompilerLens/
├── compilerlens/                Installable Python implementation
│   ├── cli.py                  compile/import/inspect/trace/diff/bench/view/doctor
│   ├── services.py             Shared capture and import orchestration
│   ├── lineage.py              LLVM report processing and source/assembly joins
│   ├── queries.py              Queries over saved runs
│   ├── storage.py              Durable run files and workspace selection
│   ├── server.py               Serve the bundled viewer and API
│   ├── backend/                API, IREE compiler runner and benchmarking
│   ├── models/                 Hugging Face detection, loading and architecture capture
│   ├── ingest/                 Artifact construction, parsers and operation lineage
│   └── examples/               Packaged matmul, linear/ReLU and transformer examples
├── llvm/                       C++ LLVM analysis, plugin, driver, tests and IREE hook
├── backend/, models/, ingest/  Compatibility imports for checkout commands
├── frontend/                   React viewer, build configuration and browser checks
├── scripts/                    Legacy model compiler, release build and install checks
├── docs/                       CLI guide, release checklist and screenshots
├── examples/                   Existing fixtures and legacy script output
├── runs/                       Generated CLI/web captures (not tracked)
├── tests/                      Python regression tests
├── pyproject.toml              Package metadata and runtime dependencies
├── requirements.txt            Pinned development environment
└── README.md                   Project overview and setup
```

## System Requirements

- Linux x86-64; the tested package wheel requires glibc 2.35 or newer
- Python 3.10 is the validated interpreter
- Internet access for installation and uncached Hugging Face models
- Enough disk space for compiler dumps; even small models can produce tens or hundreds of MB
- For frontend development from source: Node.js 20.19+ or 22.12+; Node 22 is recommended

The package includes the IREE compiler/runtime dependencies and a prebuilt LLVM analyzer.
The installed CLI and bundled viewer do not require Node.js, CMake, or an LLVM SDK. Building
that analyzer from source requires the tools listed in the [CLI development guide](docs/CLI.md#builddevelop-the-native-pass).

## CLI Quick Start

Use the installed CLI to capture a model, inspect its compiler stages, and open the same
browser viewer. A repository checkout is not required.

### Create an environment and install

Version `0.1.1` targets Linux x86-64 with Python 3.10 and glibc 2.35+. The commands
below install it from **TestPyPI**. Production PyPI publication and installation testing
are pending; see the [release checklist](docs/RELEASING.md) for validation status.

```bash
mkdir compilerlens-demo
cd compilerlens-demo
python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

# Download CompilerLens from TestPyPI.
python -m pip download --no-deps --only-binary=:all: \
  --index-url https://test.pypi.org/simple/ \
  --dest wheels compilerlens==0.1.1

# Install the wheel and resolve its dependencies from the normal indexes.
python -m pip install \
  --index-url https://pypi.org/simple/ \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  wheels/compilerlens-0.1.1-py3-none-manylinux_2_35_x86_64.whl

python -m pip check
compilerlens doctor
```

Downloading the package separately keeps TestPyPI out of dependency resolution. The PyTorch
CPU index supplies CPU builds. Once a production release is published, installation can use
`python -m pip install compilerlens` with the documented dependency indexes.

### Compile, inspect, and open the viewer

Start with the packaged matmul example, which needs no Hugging Face model download:

```bash
compilerlens compile --example matmul --out runs/matmul --lineage required
compilerlens inspect runs/matmul
compilerlens inspect runs/matmul --show stages
compilerlens trace runs/matmul --module model --to asm
compilerlens view runs/matmul --port 8000
```

Open `http://127.0.0.1:8000` to explore the captured model architecture, compiler pipeline,
and operation lineage. Stop the viewer with Ctrl+C. Choose a new output directory for each
capture; CompilerLens refuses to overwrite an existing run.

To capture a Hugging Face model:

```bash
compilerlens compile sshleifer/tiny-gpt2 --seq-len 8 --out runs/tiny-gpt2
```

### Primary commands

| Command | Purpose |
|---|---|
| `compilerlens doctor` | Check compiler tools, the LLVM analyzer, and bundled viewer assets |
| `compilerlens compile` | Capture a Hugging Face model, packaged example, or local Python factory |
| `compilerlens import DUMPS --out RUN` | Turn existing compiler dumps into a saved run |
| `compilerlens inspect RUN` | Inspect architecture, stages, evidence, operations, IR, or object sections |
| `compilerlens trace RUN` | Follow module/source associations into LLVM and assembly, or query them in reverse |
| `compilerlens diff RUN --from STAGE --to STAGE` | Compare compatible stages within a run |
| `compilerlens bench RUN` | Benchmark with the saved input tensors |
| `compilerlens view RUN` | Serve the saved run in the bundled browser viewer |

See the **[detailed CLI guide](docs/CLI.md)** for selectors, JSON output, offline capture,
local Python factories, object-address lookup, and build instructions. The
[release checklist](docs/RELEASING.md) records TestPyPI validation and publication steps.
Version `0.1.1` includes the `llvm/` source-directory rename and consistent lineage
terminology, while preserving the ability to read saved runs from version `0.1.0`.

## Installation from Source

Use this workflow to develop CompilerLens or run the frontend directly from the checkout.
For the packaged CLI and viewer, follow the [CLI quick start](#cli-quick-start).

From the repository root:

```bash
python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

cd frontend
npm ci
npm run artifact
cd ..
```

`npm run artifact` converts the compiler dumps under `examples/` into the JSON artifacts used
by the website. Run it again after changing ingest code or adding a model from the command line.

## Running CompilerLens Locally

Start the API from the repository root:

```bash
source .venv/bin/activate
python -m backend.api.run_server
```

In a second terminal, start the frontend:

```bash
cd frontend
npm run dev
```

Open the **Local** URL printed by Vite after `npm run dev` (for example,
`http://localhost:5173`). Vite may choose a different port when 5173 is already occupied.
Keep both processes running while using model search or the Compiler Playground. The existing,
pre-generated workload viewer only needs the frontend.

If port 8000 is already in use, an API server is probably running in another terminal. Reuse
that process or stop it before starting another one.

## Compiling Models from the Web Interface

1. Open the landing page.
2. Enter a Hugging Face repository ID in the prominent model search field.
3. Select **Compile & explore** or press Enter.

The API downloads the model, exports it through Turbine, captures the model hierarchy and
compiler stages, creates the normalized artifact, updates the landing-page index, and opens the
new architecture explorer. From there, select a module to inspect its compiler coverage, trace
one of its operations, or open the complete pipeline.

Successful compilations are added to the artifact library, where every card summarizes the
model family, architecture type, stage count, operation count, and available compiler insights.

<p align="center">
  <img src="docs/images/compiled-workloads.png" alt="CompilerLens compiled workload library with Pythia, GPT-2, BERT, RoBERTa, and Matmul pipelines" width="100%">
</p>

<p align="center"><em>Compiled workloads remain available as explorable pipeline artifacts.</em></p>

Good small models to try:

```text
hf-internal-testing/tiny-random-BertModel
hf-internal-testing/tiny-random-DistilBertModel
sshleifer/tiny-gpt2
prajjwal1/bert-tiny
```

The web flow currently accepts models below 100 million parameters. Compatibility depends on
whether the installed PyTorch, Transformers, and IREE versions can export every operation in
the model.

## Supported Model Architectures

The automatic wrapper currently supports:

- Encoder-only text models returning `last_hidden_state`
- Decoder-only text models returning `logits`
- Inputs shaped as `input_ids` plus a static 4D floating-point attention mask

Vision, audio, multimodal, and encoder-decoder models need additional input wrappers and are
rejected instead of being compiled with an incorrect signature. Sequence length is fixed at
compile time; the website uses 16 tokens for a compact first run.

## Repository Compilation Script

For the installed package, use the [CLI quick start](#cli-quick-start). The repository also
provides a developer script for generating dumps and rebuilding the static artifact library:

```bash
source .venv/bin/activate
python scripts/compile_hf_model.py prajjwal1/bert-tiny --seq-len 16
cd frontend
npm run artifact
```

Useful options:

```bash
python scripts/compile_hf_model.py MODEL_ID --dry-run
python scripts/compile_hf_model.py MODEL_ID --revision COMMIT_SHA
python scripts/compile_hf_model.py MODEL_ID --out-dir /path/to/output
python scripts/compile_hf_model.py MODEL_ID --full
python -m models.prefetch MODEL_ID [MODEL_ID ...]
```

`--full` disables dump trimming and can generate several GB of data. The default mode retains
the stages needed by the UI while removing embedded weight payloads and redundant pass dumps.

## Compiler Playground and Benchmarking

Choose **Open the Compiler Playground** from the landing page to:

- Compile selected stages
- Compare allowlisted compiler options such as target CPU and optimization level
- Inspect the resulting IR and compiler signals
- Run an explicit whole-model benchmark

The model selector combines a small set of baseline models with persisted captures found under
`examples/*/model_info.json` and `runs/*/model_info.json`. Reopening the Playground refreshes this list,
so models added through landing-page search or the command-line compiler appear automatically.

Playground jobs are stored in memory and disappear when the API restarts. Hugging Face models
compiled through landing-page search are persisted under `runs/<job-id>/`, with viewer artifacts
published to `frontend/public/artifacts/`. Installed builds use the user cache workspace by
default; `COMPILERLENS_WORKSPACE` overrides it.

## Validation and Testing

Run the backend syntax checks and frontend production build:

```bash
source .venv/bin/activate
python -m py_compile compilerlens/backend/api/app.py compilerlens/backend/api/run_server.py compilerlens/ingest/build.py compilerlens/ingest/schema.py compilerlens/models/architecture.py compilerlens/ingest/architecture.py
python -m unittest discover -s tests -v

cd frontend
npm run build
```

For browser-level checks, leave `npm run dev` running and execute:

```bash
cd frontend
npx playwright install chromium   # first run only
npm run verify
```

## Troubleshooting

- `iree-compile not found`: activate `.venv` before starting the API or compiler script.
- API unavailable in the UI: confirm `python -m backend.api.run_server` is listening on port
  8000.
- Hugging Face download failure: check the model ID, network access, authentication for gated
  repositories, and available disk space.
- Export or compilation failure: the architecture may use PyTorch operations unsupported by
  the current IREE pipeline. The API terminal contains the detailed compiler traceback.
- Frontend has no workloads: run `cd frontend && npm run artifact`.

## Contributions

Contributions are welcome. Create a focused branch, follow the installation instructions, and
run the relevant validation before opening a pull request:

```bash
cd frontend
npm run build
npm run verify   # requires the Vite development server and Playwright Chromium
```

For compiler or backend changes, also run the Python syntax checks listed in
[Validation and Testing](#validation-and-testing). Please include a concise description of the
change, testing performed, and screenshots for visible UI changes.

## Citation

If CompilerLens is useful in your work, please cite:

```bibtex
@software{compilerlens2026,
  author = {Varshney, Ananya and Banerjee, Soumya},
  title = {CompilerLens: An Interactive AI Compiler Visualization Explorer},
  year = {2026}
}
```

## License

CompilerLens is available under the Apache License 2.0. See [LICENSE](LICENSE) for the complete
terms.
