# 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:

```bash
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:

```bash
.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:

```bash
# 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](ARCHITECTURE.md) 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:

```csv
Id,op_id,lane,core,ssa_name
```

```csv
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`](raptor_graph_explorer/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

```bash
.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.