Merge branch 'master' into perf/gfql-fused-tolower-one-sided

Author: lmeyerov

CHANGELOG.md

@@ -1,10 +1,20 @@
 #!/usr/bin/env python3
 """FAIR GFQL-vs-Ladybug: run Ladybug's benchmark ops as GFQL Cypher MATCH...RETURN
-(the row pipeline), NOT dataframe shortcuts. Compares against LadybugDB's PUBLISHED
-5M/20M numbers (their figures, their hardware — a cross-machine comparison; treat
-ratios as indicative). Ladybug best (5M/20M, ms): full_scan 3789, range 7.5,
-point 0.3, count 3.3, out_degree100 59.8, scan_rel_props 15722,
-scan_rel_rowid 14562. Kuzu count 46.
+(the row pipeline), NOT dataframe shortcuts. Op shapes follow
+https://github.com/LadybugDB/kuzu-ladybug-benchmark.
+
+The `LADYBUG` reference column below is a MEASUREMENT, not a literal: LadybugDB 0.18.1,
+embedded, on the same host and in the same session as the GFQL arm, on the same generated
+5M-node / 20M-edge graph, warm medians (2 warmups + 5 timed runs, median across two
+position-balanced slots), timed at Ladybug's FASTEST result-producing scope of the four
+measured (zero-copy Arrow / polars / pandas / row iterator) -- Arrow for every scan,
+the row iterator for the single-row point lookup -- because GFQL returns a materialized
+columnar frame and choosing a slower scope for the competitor is not a comparison. Result values were digest-identical
+across the two engines on every op. Runner, raw JSON and full provenance:
+pyg-bench `benchmarks/ladybug_scan/` and `results/ladybug-scan-20260728/`.
+
+Numbers here are from dgx-spark (GB10); on another box, re-run the pyg-bench lane rather
+than reusing these.
 
 FAIRNESS: each engine is benchmarked on a graph built in ITS OWN NATIVE frame type
 (pandas/polars/cuDF), built ONCE outside the timing loop. An earlier version built the
@@ -49,8 +59,9 @@ def build(engine):
     "scan_rel_props": "MATCH (a)-[o]->(b) RETURN a.id, b.id, o.since",
     "scan_rel_rowid": "MATCH (a)-[r]->(b) RETURN a.id, b.id",
 }
-LADYBUG = {"full_scan": 3789, "range": 7.5, "point": 0.3, "count": 3.3,
-           "scan_rel_props": 15722, "scan_rel_rowid": 14562}
+# LadybugDB 0.18.1, dgx-spark, 2026-07-28, Arrow materialization (see module docstring).
+LADYBUG = {"full_scan": 364.28, "range": 7.57, "point": 0.30, "count": 3.08,
+           "scan_rel_props": 1925.61, "scan_rel_rowid": 1449.13}
 
 def _size(res):
     df = getattr(res, "_nodes", None)

benchmarks/gfql/bench_ladybug_cypher.py

@@ -26,7 +26,13 @@ POLARS_TEST_FILES=(
     graphistry/tests/compute/gfql/test_engine_polars_chain.py
     graphistry/tests/compute/gfql/test_engine_polars_row_pipeline.py
     graphistry/tests/compute/gfql/test_engine_polars_binding_rows.py
+    # engine-parametrized (pandas/polars/cudf/polars-gpu); the pandas params also run in
+    # test-gfql-core, but only this lane has polars installed
+    graphistry/tests/compute/gfql/test_varlen_bounded_engine_parity_1787.py
     graphistry/tests/compute/gfql/test_engine_polars_with_match_reentry.py
+    # engine-parametrized: its pandas params run in test-gfql-core, but the polars params
+    # only ever run here (the file has no module-level importorskip, so nothing else flags it)
+    graphistry/tests/compute/gfql/test_exec_context_scoping.py
     graphistry/tests/compute/gfql/test_engine_polars_cypher_conformance.py
     graphistry/tests/compute/gfql/test_engine_polars_conformance_matrix.py
     graphistry/tests/compute/gfql/test_polars_string_predicate_nonstring.py
@@ -38,6 +44,7 @@ POLARS_TEST_FILES=(
     graphistry/tests/compute/gfql/test_seeded_typed_hop_fastpath.py
     graphistry/tests/compute/gfql/test_residual_polars_native.py
     graphistry/tests/compute/gfql/cypher/test_grouped_aggregate_fused_polars.py
+    graphistry/tests/compute/gfql/cypher/test_grouped_aggregate_lowcard_count.py
     # module-level `importorskip("polars")` files that previously ran in no lane at all
     graphistry/tests/compute/gfql/test_engine_polars_narrow_combine.py
     graphistry/tests/compute/gfql/test_engine_polars_semi_key_dedup.py

bin/test-polars.sh

@@ -20,7 +20,9 @@ ignore_roles =
     py:attr,
     py:exc,
     py:obj,
-    py:data
+    py:data,
+    bench,
+    bench-diag
 
 # Ignore Sphinx-specific directives
 ignore_directives =
@@ -43,7 +45,9 @@ ignore_directives =
     glossary,
     productionlist,
     include,
-    graphviz
+    graphviz,
+    bench-provenance,
+    bench-disclosures
 
 # Ignore common informational messages
 ignore_messages = (Hyperlink target "[^"]*" is not referenced\.$)

docs/.rstcheck.cfg

@@ -0,0 +1,102 @@
+{
+  "contract_version": 1,
+  "title": "pyg-bench published docs numbers",
+  "summary": [
+    "The boundary between this repository and the pygraphistry docs. pyg-bench MEASURES and",
+    "PUBLISHES; pygraphistry pretty-prints. Everything a consumer is allowed to assume about",
+    "published/docs-numbers.json is written down here, checked on the producer side before the",
+    "artifact is written, and re-verified independently on the consumer side before it renders.",
+    "Two independent implementations of these rules is the point: a shared library would fail",
+    "the same way on both sides of the boundary."
+  ],
+  "artifact_path": "published/docs-numbers.json",
+  "top_level_required": [
+    "contract_version",
+    "schema_version",
+    "generated_by",
+    "generated_at",
+    "policy",
+    "runs",
+    "cells"
+  ],
+  "policy_required": ["max_age_days", "managed_docs"],
+  "run_required": [
+    "measured_at",
+    "host",
+    "perf_lock_held",
+    "quiet_host",
+    "reps",
+    "pygraphistry_commit",
+    "pyg_bench_commit",
+    "runtime",
+    "dataset",
+    "artifact",
+    "row_validation"
+  ],
+  "cell_required": [
+    "run",
+    "workload",
+    "engine",
+    "value",
+    "unit",
+    "decimals",
+    "status",
+    "comparison_allowed",
+    "board_quotable",
+    "disclosures"
+  ],
+  "cell_status": ["ok", "partial", "adapter_workaround", "result_mismatch"],
+  "cell_unit": ["ms", "s", "x"],
+  "key_pattern": "^[a-z0-9][a-z0-9_]*(\\.[a-z0-9][a-z0-9_]*)+$",
+  "date_pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$",
+  "max_decimals": 4,
+  "invariants": [
+    {
+      "id": "cell_names_a_known_run",
+      "rule": "every cell.run must be a key of runs",
+      "why": "a number whose provenance record is absent is an unprovenanced number"
+    },
+    {
+      "id": "quotable_implies_comparable",
+      "rule": "board_quotable implies comparison_allowed",
+      "why": "a diagnostic-only figure must never reach a board"
+    },
+    {
+      "id": "quotable_implies_ok",
+      "rule": "board_quotable implies status == 'ok'",
+      "why": "partial / adapter_workaround / result_mismatch cells are not results"
+    },
+    {
+      "id": "caveat_travels_with_the_number",
+      "rule": "status != 'ok' or comparison_allowed is false implies disclosures is non-empty",
+      "why": "a bare ratio without its asterisk launders the caveat"
+    },
+    {
+      "id": "ratios_are_comparisons",
+      "rule": "unit 'x' implies comparison_allowed",
+      "why": "a ratio between two numbers that were never established as comparable is not a speedup"
+    },
+    {
+      "id": "value_is_rounded_as_published",
+      "rule": "value == round(value, decimals), value is finite and >= 0, 0 <= decimals <= max_decimals",
+      "why": "the consumer prints value verbatim; rounding must not happen at render time"
+    },
+    {
+      "id": "engine_is_named",
+      "rule": "cell.engine is a non-empty string",
+      "why": "pandas and polars are not interchangeable and the reader must be told which one ran"
+    },
+    {
+      "id": "measurement_is_dated",
+      "rule": "run.measured_at matches date_pattern",
+      "why": "staleness is checked against the MEASUREMENT date, not the export date"
+    }
+  ],
+  "consumer_obligations": [
+    "Refuse to render a key the artifact does not contain — a missing number is a build failure, never blank text.",
+    "Refuse to render a cell whose run.measured_at is older than policy.max_age_days.",
+    "Refuse to render a non-board_quotable cell as a bare number; it may appear only through a role that labels it diagnostic-only.",
+    "Render every referenced cell's disclosures and its run's provenance on the same page.",
+    "Re-verify every invariant above before rendering, with an implementation that does not import this repository."
+  ]
+}