traceopt-ai/traceml

Problem CONTRIBUTING.md contains four copied starter tasks. Several are already implemented, while the remaining list can become stale whenever issue status, scope, or assignment changes. The root contributor guide and the documentation contributor page also provide different installation scopes without identifying which one is canonical. Finally, implemented integration issues #189 and #190 remain open under contributor-facing labels. Changes Remove the copied starter-task list from CONTRIBUTING.md. Do not mention individual starter issue numbers in contributor documentation. Link only to live, unassigned issue filters: open good first issue tasks open help wanted tasks Make CONTRIBUTING.md the canonical setup guide. Change the standard setup to pip install -e ".[dev,torch]". Make docs/developer_guide/contributing.md link to the canonical guide. Explain that documentation work additionally needs lightning, hf, and docs; remove the inaccurate “all extras” wording. Close or upd

Summary TraceML's differentiating diagnosis is cross-rank: naming which rank is dragging a distributed job and why. No current demo path shows it without the user setting up a multi-process run themselves. TraceML's own architecture (one aggregator process, N training ranks reporting over TCP) maps naturally onto containers, so a docker compose up can demonstrate a live rank-straggler diagnosis end to end, on a CPU-only laptop. Proposed approach Add a docker-compose.yml at the repository root (per the decision recorded on #241) with two services built from the existing demo image: aggregator: runs traceml serve --aggregator-bind-host 0.0.0.0 --aggregator-port 29765 --nnodes 1 --nproc-per-node 2 --mode summary. trainer: runs examples/distributed/ddp_rank_straggler_demo.py with 2 ranks via torchrun, pointing at the aggregator with TRACEML_AGGREGATOR_HOST=aggregator and TRACEML_AGGREGATOR_PORT=29765, with --scenario input-straggler. The straggler example already falls back to the gloo

Summary The #223 container is CPU-only by design, which was the right first scope. But the diagnoses that matter most to TraceML's core audience (H2D transfer timing, GPU memory pressure, per-rank telemetry on multi-GPU boxes) never appear in a CPU demo. A GPU-capable image variant lets anyone with an NVIDIA host or cloud GPU instance run the same one-command demo and see those sections populated. Proposed approach Add a second Dockerfile (for example Dockerfile.gpu) rather than overloading the CPU one with build arguments; the two bases differ too much for one file to stay readable. Base it on a CUDA image. Two workable options: nvcr.io/nvidia/pytorch:<yy.mm>-py3 (NGC): PyTorch preinstalled and validated against the bundled CUDA/cuDNN/NCCL, so the layer we add is just TraceML. Larger pull, and it comes from NVIDIA's registry rather than Docker Hub. nvidia/cuda:<ver>-runtime-ubuntu22.04 plus a pip install of the matching torch CUDA wheel: the pattern most comparable projects use,

Summary The #223 demo container runs in --mode=summary and prints a text report. That proves the diagnosis works, but a first-time user never sees the live dashboard, which is a large part of what TraceML actually offers. A documented dashboard-mode run turns the same container into a visual product tour: docker run, open a browser, watch the diagnosis appear live. Proposed approach Install the dashboard extra in the image: change the Dockerfile install to .[torch,dashboard] so nicegui and plotly are present. Keep --mode=summary as the default CMD so the existing zero-flag behavior from #223 is unchanged. Add an EXPOSE 8765 hint and document the dashboard run in the README: docker run --rm -p 8765:8765 traceml-demo \ traceml run examples/diagnosis/dataloader_bottleneck_demo.py --mode=dashboard --args --scenario slow Verify the dashboard is reachable from the host through the published port. If it currently binds only to 127.0.0.1 inside the container, wire the existing bind-add

Summary The demo container from #223 must be built locally today: clone the repository, then docker build an image of about 3 GB before anything runs. Publishing a pre-built, version-tagged image removes both steps, so trying TraceML becomes a single docker run with no checkout. Proposed approach Add a GitHub Actions workflow (for example .github/workflows/docker-publish.yml) that builds the existing root Dockerfile and pushes the image on every version tag. Publish to GHCR as ghcr.io/traceopt-ai/traceml-demo, since pushing there needs only the built-in GITHUB_TOKEN and no extra registry account. Docker Hub is a fine alternative if broader discoverability matters more; the workflow shape is the same with docker/build-push-action. Tag with the release version plus latest (for example traceml-demo:0.3.5 and traceml-demo:latest). Build for linux/amd64 at minimum; add linux/arm64 via buildx if the runner budget allows, since Apple Silicon hosts are common for evaluation. Update the README