Metadata-Version: 2.4
Name: tlhub
Version: 0.3.3
Summary: Local TORCH_TRACE run hub with artifact browsing and diffing.
Author: Bobren
License-Expression: MIT
Project-URL: Homepage, https://github.com/bobrenjc93/tlhub
Project-URL: Repository, https://github.com/bobrenjc93/tlhub
Project-URL: Issues, https://github.com/bobrenjc93/tlhub/issues
Keywords: pytorch,torch,torch.compile,torch_trace,fx,inductor
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# tlhub

`tlhub` is a local hub for `TORCH_TRACE` runs.

Instead of manually setting `TORCH_TRACE`, running a program, and then feeding the logs into `tlparse`, `tlhub` folds that loop into one tool:

1. Wraps a command and sets `TORCH_TRACE` for it.
2. Indexes the resulting trace logs into browsable artifacts.
3. Keeps a local daemon-backed UI where runs can be viewed, compared, diffed, and deleted.

`tlhub` does not reuse `tlparse`'s HTML renderer. It parses the structured trace logs directly and renders its own viewer, but it now targets the same major report surfaces as `tlparse`: compile summaries, stack trie, failures and restarts, raw JSONL, export diagnostics, provenance tracking, vLLM views, and multi-rank analysis.

## Install

```bash
python3 -m pip install tlhub
```

From source:

```bash
python3 -m pip install -e .
```

## Quick start

Prefix any command with `tlhub`:

```bash
tlhub python train.py
```

That will:

- create a new run directory under `TLHUB_HOME` or `~/.local/share/tlhub`
- set `TORCH_TRACE` for the wrapped command
- check for the background daemon and start it if needed
- ingest the resulting trace logs
- print a run URL you can open in the browser

Open the dashboard without running a command:

```bash
tlhub
```

Stop the daemon:

```bash
tlhub --stop
```

There are no user-facing subcommands. Run deletion and cross-run comparison happen in the web UI.

If you are tunneling or reverse-proxying the local daemon, set `BASE_URL` to rewrite the
printed and browser-opened URLs while keeping the server bound to `127.0.0.1`:

```bash
BASE_URL=https://proxy.example.com/reviewer?via=ssh tlhub python train.py
```

`tlhub` will substitute the runtime port into that URL. The web UI also preserves the
configured path prefix and query string across links, forms, and redirects.

## Viewer parity targets

The viewer now exposes the main `tlparse` surfaces in `tlhub` form:

- run dashboard
- per-run compile directory
- compile-detail pages with stack, output files, compile metrics, custom op info, symbolic shape specialization, created symbols, unbacked symbols, and guard-added-fast data
- stack trie over compile stacks
- failures and restarts summary
- `raw.jsonl` shortraw-style output with the string table prepended
- export diagnostics plus guard detail pages
- provenance-tracking pages that align pre-grad graphs, post-grad graphs, and generated code via node mappings
- vLLM-specific summary pages with piecewise split graphs, compile config, and per-subgraph artifact listings
- multi-rank diagnostics:
  - compile id divergence
  - cache-pattern divergence
  - collective divergence
  - tensor-meta divergence
  - runtime delta summaries
  - execution-order summaries
- combined and derived report artifacts such as:
  - `chromium_events.json`
  - `runtime_estimations.json`
  - `chromium_trace_with_runtime.json`
  - `collective_schedules.json`
  - `collectives_parity.json`
  - `execution_order_report.json`
  - `compile_directory.json`

The diffing workflow is built into the UI. You can either:

- compare two runs and let `tlhub` line up artifacts by family plus occurrence index
- pick any two artifacts manually and diff them directly

This is especially useful for FX graphs, Inductor output code, and report JSON. FX-graph diffs also get a graph-aware semantic view so added, removed, and retargeted nodes are visible before you drop to raw line diffs.

## What gets indexed

The ingester understands the same raw `TORCH_TRACE` log shape that `tlparse` reads:

- glog-formatted structured log lines
- JSON envelopes
- tab-indented payload bodies following `has_payload`
- string-table (`"str"`) entries used by stack frames

It extracts and stores artifacts such as:

- graph payloads like `dynamo_output_graph`, `aot_*_graph`, and `inductor_*_graph`
- `graph_dump`
- `inductor_output_code`
- `dynamo_guards`
- generic `artifact` payloads with `string` or `json` encoding
- `memoizer_artifacts`
- `dump_file`
- `exported_program`
- synthetic report outputs derived from the run

Artifacts are grouped by a stable family key plus occurrence index so that matching outputs from two runs can be lined up and diffed.

## Web UI

The local UI provides:

- a run dashboard
- a report section for `raw.jsonl` and derived diagnostics
- compile-detail pages
- export-guard detail pages
- provenance detail pages
- per-run artifact browsing
- artifact-family matching across two runs
- arbitrary artifact-to-artifact diffing
- run deletion

For graph-like text artifacts, the viewer records lightweight summaries such as node counts and op buckets to make diffs easier to scan. Synthetic reports are also first-class artifacts, so you can diff analysis outputs across runs, not just raw payloads.

## Daemon behavior

The daemon is local-only and binds to `127.0.0.1`.

Every normal `tlhub` invocation checks whether the daemon is already up and starts it automatically when needed. `tlhub --stop` is the only normal daemon-management command.

`tlhub` is also upgrade-aware: the daemon records the package version it was started from, and a newer `tlhub` client will automatically stop and replace an older daemon on the next invocation.

## Tests

```bash
python3 -m unittest discover -s tests -v
```

## Publish

Build and validate the distribution locally:

```bash
uv build
uv run --with twine python -m twine check dist/*
```

Publish directly from your machine:

```bash
uv publish
```

The repo also includes a GitHub Actions workflow at `.github/workflows/publish.yml` that publishes on tags like `v0.1.0`.

Before using the workflow, configure PyPI Trusted Publishing for:

- owner or user: `bobrenjc93`
- repository: `tlhub`
- workflow: `publish.yml`
- environment: `pypi`

Release flow:

1. Update `src/tlhub/__init__.py` with the new version.
2. Commit and push `main`.
3. Create and push a matching tag such as `v0.1.0`.
