Move perf-benchmark CODE out of pygraphistry into pyg-bench; keep only contract-validated RESULTS for docs

[lmeyerov]

The rule

Performance-benchmark code does not belong in this repo. Only results, for docs.

Owner, 2026-07-28, on merging #1826:

those scripts should live in pyg-bench, generate there & copy into pygraphistry, and then we have data contracts on both sides to ensure right format … perf benchmarks CODE do NOT belong in pygraphistry, just results for docs

Why it matters

A benchmark script living next to shipped product code is measurement machinery with no reproducible environment and no separation from the thing it measures. It invites editing the measurement to fit the claim — and this campaign has already produced three concrete instances of numbers that were wrong for exactly that class of reason:

• q9's "14.2×" compared GFQL's canonical query against a different Kuzu query (an OPTIONAL MATCH degree-product rewrite). Honest same-query ratio: 1.26×. Fixed in docs(gfql): reconcile the OLAP q9 figure and re-measure LadybugDB #1826.
• LadybugDB's "~65×" was a drain-scope figure; at Ladybug's fastest materialization full_scan is 6.18× and two of six cells flip to losses. Fixed in docs(gfql): reconcile the OLAP q9 figure and re-measure LadybugDB #1826.
• q8's board win is a cross-call Plottable memo that does not survive ordinary one-shot API use (GFQL: two-hop count returns a STALE answer after in-place frame mutation (degree-count memo setattrs onto the caller's Plottable, keyed by id() — the BLOCKER-1 pattern the same file forbids) #1825).

pyg-bench owns generation; pygraphistry renders and re-verifies what it is handed.

Scope

benchmarks/ currently holds 40 files on master, including bench_ladybug_cypher.py (which #1826 just touched), bench_ladybug.py, bench_graphframes.py, the filter_pagerank/ pipelines, and ~15 index_* benchmarks.

Proposed shape

1. Generation moves to pyg-bench. Scripts are ported, not copied — the pygraphistry copy is deleted so there is one source of truth.
2. Results cross the boundary as data, with a contract on both sides: an exporter schema in pyg-bench and consumer validation in pygraphistry. The manifests/docs_numbers_spec.json + docs(gfql): print the benchmark numbers pyg-bench publishes, and re-verify them #1818 mechanism is the existing pattern to extend; the Ladybug cells are already flagged as not yet exported through it.
3. Docs render only validated results — a figure with no contract-validated provenance does not get published.
4. benchmarks/ becomes legacy: nothing new lands there while migration proceeds.

Not a blocker

This is a follow-on. In-flight PRs are unaffected and should not be held for it.

Related

• docs(gfql): print the benchmark numbers pyg-bench publishes, and re-verify them #1818 — consumer side of the numbers contract (unmerged)
• GFQL: two-hop count returns a STALE answer after in-place frame mutation (degree-count memo setattrs onto the caller's Plottable, keyed by id() — the BLOCKER-1 pattern the same file forbids) #1825, GFQL: Cypher OLAP fast paths silently run on CPU under engine='polars-gpu' (bare LazyFrame.collect() bypasses the GPU-or-error contract) #1824 — defects found by this campaign's measurement work
• pyg-bench docs(default no key) #116 — the q9/Ladybug generation side, already merged there