Raptor/tools/raptor_graph_explorer

Raptor Graph Explorer

Python 3.13+ tool for exploring Raptor Spatial dataflow CSVs in a browser. It streams reports into SQLite, aggregates operations/cores/node kinds, and provides bounded raw-lane inspection. Compiler output remains unchanged.

Install and run

From the repository root, create a Python 3.13+ environment if .venv does not exist:

python3.13 -m venv .venv

For a new or existing environment, verify the version before installing. Select a compatible environment if this check fails; do not reuse an older Python:

.venv/bin/python -c 'import sys; assert sys.version_info >= (3, 13), "Python 3.13+ required"'
.venv/bin/python -m pip install -e 'tools/raptor_graph_explorer[dev]'
.venv/bin/raptor-graph-explorer build /path/to/raptor/reports --output /tmp/raptor_graph
.venv/bin/raptor-graph-explorer serve /tmp/raptor_graph --port 8765

Open http://127.0.0.1:8765. The server is read-only, has no authentication, and is intended for local use. Browser dependencies load from pinned CDNs and require network access on first use; preprocessing and inspection work offline.

Other commands:

# Build and serve a directory, CSV pair, or ZIP archive.
.venv/bin/raptor-graph-explorer run /path/to/reports.zip --output /tmp/raptor_graph
# Print counts, mappings, motifs, and diagnostics.
.venv/bin/raptor-graph-explorer inspect /tmp/raptor_graph

build and run accept multiple input paths and discover reports recursively. --overwrite replaces an existing output. build --strict rejects data-integrity errors; otherwise valid pairs and unambiguous rows are retained. Outputs are graph.sqlite and manifest.json. Rebuild outputs if the tool reports an unsupported schema version.

See architecture and API guarantees for identity, expansion, mapping/motif analysis, ingestion constraints, and the endpoint reference.

Input contract

Pair files by the complete prefix before .nodes.csv and .edges.csv. Required headers:

Id,op_id,lane,core,ssa_name

Source,Target,Weight,Type,stage,source_lane,target_lane,channel_id

Explicit operation IDs and lanes take precedence over parsed node IDs. Missing numeric values remain missing; malformed values produce diagnostics. Extra columns are preserved. Edges resolve only within their report; unknown endpoints are diagnosed and omitted. Unsafe ZIP paths are rejected.

Graph lanes, physical fragment slots, scheduled lanes, cores, and channels are distinct identities. Spatial3 reports contain explicit communication only; isolated nodes are valid and no dependencies are inferred from SSA text.

Views and analysis

• Operation: aggregates by operation and supports lane expansion, exact mapping details, and structural motifs.
• Core / Node kind: summarize placement and operation kinds.
• Raw instances: displays source nodes and valid edges, including isolated nodes; spatial4 reports select this view automatically.

The viewer first loads an operation aggregate. Search, filters, expansion, selection details, and layout controls support focused inspection. Raw and expanded graphs cap raw nodes plus incident raw edges at 5,000; exceeding it returns an error rather than a partial graph. Use an aggregate view or increase create_app(..., expansion_cap=...) when the machine can handle it.

Lane mappings use all normalized pairs, without sampling. Classes include scalar/batch relations, identity, constant offset, permutation, broadcast, fan-in, stencil, irregular, and unknown. Small matrices show exact sparse points; large ones use a bounded 64×64 density view.

Motifs identify structural single-entry/single-exit split/rejoin regions on the operation graph's SCC condensation. exact_diamond, rhomboid, and split_rejoin describe progressively broader forms; a diamond-shaped drawing alone is not evidence of a motif. Cycles remain marked.

API and limits

Read-only FastAPI endpoints expose manifests, report summaries, aggregate graphs/details, mappings, matrices, motifs, and raw pages. See api.py for routes and create_app limits. Raw pages default to 100 rows and cap at 500; subgraph depth caps at five. Aggregate graph endpoints return the complete aggregate, so very large operation counts can still be expensive.

Tests and troubleshooting

.venv/bin/python -m pytest tools/raptor_graph_explorer/tests
RAPTOR_GRAPH_SLOW=1 .venv/bin/python -m pytest \
  tools/raptor_graph_explorer/tests/test_aggregation.py -m slow

The opt-in test generates 100 operations, 1,000 lanes, and 100,000 raw edges.

• No complete pairs: check matching prefixes and both CSV suffixes.
• Strict build failed: inspect diagnostics from a build without --strict.
• Raw/expanded display returns 400: use aggregation or adjust the cap.
• Blank viewer with working APIs: check browser CDN access and console.
• No motifs: valid when no structural split/rejoin region exists.