This document defines a simple, extensible visualization scheme for the Lula Platform.
- Provide a stable mental model: graph + timeline + artifacts.
- Make every run inspectable via a single JSON trace artifact.
- Keep the first implementation file-based (no DB required).
The orchestrator can export a Mermaid graph for the current topology.
- Export source:
export_mermaid() - CLI:
uv run python -m lg_orch.main export-graph
Render by pasting the output into any Mermaid renderer.
Each run emits a trace file (JSON) containing an ordered event list.
- Trace implementation:
write_run_trace() - Node events emitted in:
ingest(),policy_gate(),context_builder(),router(),planner(),executor(),verifier(),reporter()
Event kinds:
node: transitions and node-level metadatatools: batched tool calls executed by the runner
Example trace location:
artifacts/runs/run-<run_id>.json
Console-style runtime view:
uv run python -m lg_orch.main run "<request>" --view console --trace
Trace dashboard renderer:
uv run python -m lg_orch.main trace-view artifacts/runs/run-<run_id>.jsonuv run python -m lg_orch.main trace-view artifacts/runs/run-<run_id>.json --format html --output artifacts/site/run-<run_id>.html
Static site renderer:
uv run python -m lg_orch.main trace-site artifacts/runs --output-dir artifacts/site- Open
artifacts/site/index.htmlin a browser.
Artifacts are referenced from the trace and/or exist on disk:
- patches/diffs (future)
- verification reports (future)
- runner stdout/stderr envelopes (present in
tool_results) - copied raw trace JSON under
artifacts/site/traces/whentrace-siteis used
Tracing is enabled by runtime profile.
- Dev:
configs/runtime.dev.toml - Stage:
configs/runtime.stage.toml - Prod:
configs/runtime.prod.toml
Keys:
[trace]
enabled = true
output_dir = "artifacts/runs"- Add an HTTP API exposing:
/v1/runslist/v1/runs/{run_id}trace
- Evolve the static site into a served web UI with filtering, replay, and richer artifact browsing