feat(hop): add hop ranges and labeling

.github/workflows/ci.yml

@@ -119,8 +119,6 @@ jobs:
         ./bin/lint.sh
 
     - name: Type check
-      env:
-        PYTHON_VERSION: ${{ matrix.python-version }}
       run: |
         source pygraphistry/bin/activate
         ./bin/typecheck.sh

.gitignore

@@ -14,6 +14,8 @@ pypirc
 # Distribution / packaging
 .Python
 env/
+.venv/
+.hypothesis/
 build/
 develop-eggs/
 dist/

CHANGELOG.md

@@ -8,12 +8,22 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ## [Development]
 <!-- Do Not Erase This Section - Used for tracking unreleased changes -->
 
+### Added
+- **Compute / hop**: `hop()` supports `min_hops`/`max_hops` traversal bounds plus optional hop labels for nodes, edges, and seeds, and post-traversal slicing via `output_min_hops`/`output_max_hops` to keep outputs compact while traversing wider ranges.
+- **Docs / hop**: Added bounded-hop walkthrough notebook (`docs/source/gfql/hop_bounds.ipynb`), cheatsheet and GFQL spec updates, and examples showing how to combine hop ranges, labels, and output slicing.
+- **GFQL / reference**: Extended the pandas reference enumerator and parity tests to cover hop ranges, labeling, and slicing so GFQL correctness checks include the new traversal shapes.
 ### Fixed
-- **GFQL:** `Chain` now validates on construction (matching docs) and rejects invalid hops immediately; pass `validate=False` to defer validation when assembling advanced flows (fixes #860).
+- **Compute / hop**: Exact-hop traversals now prune branches that do not reach `min_hops`, avoid reapplying min-hop pruning in reverse passes, keep seeds in wavefront outputs, and reuse forward wavefronts when recomputing labels so edge/node hop labels stay aligned (fixes 3-hop branch inclusion issues and mislabeled slices).
+- **GFQL**: `Chain` now validates on construction (matching docs) and rejects invalid hops immediately; pass `validate=False` to defer validation when assembling advanced flows (fixes #860).
 - **GFQL / eq:** `eq()` now accepts strings in addition to numeric/temporal values (use `isna()`/`notna()` for nulls); added coverage across validator, schema validation, JSON, and GFQL runtime (fixes #862).
-
 ### Docs
-- **GFQL validation:** Clarified `Chain` constructor validation defaults, `validate=False` defer option, validation phases, and guidance for large/nested ASTs to reduce redundant validation (issue #860).
+- **GFQL validation**: Clarified `Chain` constructor validation defaults, `validate=False` defer option, validation phases, and guidance for large/nested ASTs to reduce redundant validation (issue #860).
+### Tests
+- **GFQL / hop**: Expanded `test_compute_hops.py` and GFQL parity suites to assert branch pruning, bounded outputs, label collision handling, and forward/reverse slice behavior.
+- **Reference enumerator**: Added oracle parity tests for hop ranges and output slices to guard GFQL integrations.
+### Infra
+- **CI / docs-only**: Skip Python lint/type/test matrices when the tip commit only touches docs/markdown/notebooks, and warm a shared HuggingFace cache with pinned CPU torch for AI jobs to avoid HF throttling.
+- **Tooling**: `bin/lint.sh` / `bin/typecheck.sh` resolve interpreters consistently (uv → python -m → bare) without forcing PYTHON_VERSION, keeping developer and CI runs aligned.
 
 ## [0.46.0 - 2025-12-01]
 
@@ -39,6 +49,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Tests
 - **CI / Python**: Expand GitHub Actions coverage to Python 3.13 + 3.13/3.14 for CPU lint/type/test jobs, while pinning RAPIDS-dependent CPU/GPU suites to <=3.13 until NVIDIA publishes 3.14 wheels (ensures lint/mypy/pytest signal on the latest interpreter without breaking RAPIDS installs).
+- **CI / Lint & Types**: Split lint/type runners from resolution: `bin/flake8.sh`/`bin/mypy.sh` are now minimal and respect `FLAKE8_CMD`/`MYPY_CMD`; `bin/lint.sh`/`bin/typecheck.sh` resolve `uvx` → `python -m …` → bare tool, relying on `mypy.ini`’s interpreter default instead of forcing 3.8. CI still uses `.[test]` installs and the matrix interpreters.
 - **GFQL**: Added deterministic + property-based oracle tests (triangles, alias reuse, cuDF conversions, Hypothesis) plus parity checks ensuring pandas GFQL chains match the oracle outputs.
 - **Layouts**: Added comprehensive test coverage for `circle_layout()` and `group_in_a_box_layout()` with partition support (CPU/GPU)
 

README.md

@@ -11,7 +11,6 @@
 [![Uptime Robot status](https://img.shields.io/uptimerobot/status/m787548531-e9c7b7508fc76fea927e2313?label=hub.graphistry.com)](https://status.graphistry.com/) [<img src="https://img.shields.io/badge/slack-Graphistry%20chat-orange.svg?logo=slack">](https://join.slack.com/t/graphistry-community/shared_invite/zt-53ik36w2-fpP0Ibjbk7IJuVFIRSnr6g)
 [![Twitter Follow](https://img.shields.io/twitter/follow/graphistry)](https://twitter.com/graphistry)
 
-
 <table style="width:100%;">
   <tr valign="top">
     <td align="center"><a href="https://hub.graphistry.com/graph/graph.html?dataset=Facebook&splashAfter=true" target="_blank"><img src="https://i.imgur.com/z8SIh2E.png" title="Click to open."></a>
@@ -34,7 +33,6 @@ PyGraphistry is an open source Python library for data scientists and developers
 
   *[View all connectors →](https://pygraphistry.readthedocs.io/en/latest/notebooks/plugins.connectors.html)*
 
-
 * [**Prototype locally and deploy remotely:**](https://www.graphistry.com/get-started) Prototype from notebooks like Jupyter and Databricks using local CPUs & GPUs, and then power production dashboards & pipelines with Graphistry Hub and your own self-hosted servers.
 
 * [**Query graphs with GFQL:**](https://pygraphistry.readthedocs.io/en/latest/gfql/index.html) Use GFQL, the first dataframe-native graph query language, to ask relationship questions that are difficult for tabular tools and without requiring a database.
@@ -45,14 +43,10 @@ PyGraphistry is an open source Python library for data scientists and developers
 
 * [**Columnar & GPU acceleration:**](https://pygraphistry.readthedocs.io/en/latest/performance.html) CPU-mode ingestion and wrangling is fast due to native use of Apache Arrow and columnar analytics, and the optional RAPIDS-based GPU mode delivers 100X+ speedups.
 
-
 From global 10 banks, manufacturers, news agencies, and government agencies, to startups, game companies, scientists, biotechs, and NGOs, many teams are tackling their graph workloads with Graphistry.
 
-
-
 ## Gallery
 
-
 The [notebook demo gallery](https://pygraphistry.readthedocs.io/en/latest/demos/for_analysis.html) shares many more live visualizations, demos, and integration examples
 
 <table>
@@ -68,8 +62,6 @@ The [notebook demo gallery](https://pygraphistry.readthedocs.io/en/latest/demos/
     </tr>
 </table>
 
-
-
 ## Install
 
 Common configurations:
@@ -98,7 +90,6 @@ Common configurations:
 
 For further options, see the [installation guides](https://pygraphistry.readthedocs.io/en/latest/install/index.html)
 
-
 ## Visualization quickstart
 
 Quickly go from raw data to a styled and interactive Graphistry graph visualization:
@@ -129,7 +120,6 @@ g1_styled.plot()
 
 Explore [10 Minutes to Graphistry Visualization](https://pygraphistry.readthedocs.io/en/latest/visualization/10min.html) for more visualization examples and options
 
-
 ## PyGraphistry[AI] & GFQL quickstart - CPU & GPU
 
 **CPU graph pipeline** combining graph ML, AI, mining, and visualization:
@@ -175,45 +165,42 @@ g4.plot()
 
 Explore [10 Minutes to PyGraphistry](https://pygraphistry.readthedocs.io/en/latest/10min.html) for a wider variety of graph processing.
 
-
 ## PyGraphistry documentation
 
 * [Main PyGraphistry documentation](https://pygraphistry.readthedocs.io/en/latest/)
 * 10 Minutes to: [PyGraphistry](https://pygraphistry.readthedocs.io/en/latest/10min.html), [Visualization](https://pygraphistry.readthedocs.io/en/latest/visualization/10min.html), [GFQL](https://pygraphistry.readthedocs.io/en/latest/gfql/about.html)
 * Get started: [Install](https://pygraphistry.readthedocs.io/en/latest/install/index.html), [UI Guide](https://hub.graphistry.com/docs/ui/index/), [Notebooks](https://pygraphistry.readthedocs.io/en/latest/demos/for_analysis.html)
 * Performance: [PyGraphistry CPU+GPU](https://pygraphistry.readthedocs.io/en/latest/performance.html) & [GFQL CPU+GPU](https://pygraphistry.readthedocs.io/en/latest/gfql/performance.html)
 * API References
-    - [PyGraphistry API Reference](https://pygraphistry.readthedocs.io/en/latest/api/index.html): [Visualization & Compute](https://pygraphistry.readthedocs.io/en/latest/visualization/index.html), [PyGraphistry Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/cheatsheet.html)
-    - [GFQL Documentation](https://pygraphistry.readthedocs.io/en/latest/gfql/index.html):  [GFQL Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/gfql/quick.html) and [GFQL Operator Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/gfql/predicates/quick.html)
-    - [Plugins](https://pygraphistry.readthedocs.io/en/latest/plugins.html): Databricks, Splunk, Neptune, Neo4j, RAPIDS, and more
-    - Web: [iframe](https://hub.graphistry.com/docs/api/1/rest/url/#urloptions),  [JavaScript](https://hub.graphistry.com/static/js-docs/index.html?path=/docs/introduction--docs), [REST](https://hub.graphistry.com/docs/api/1/rest/auth/)
+  * [PyGraphistry API Reference](https://pygraphistry.readthedocs.io/en/latest/api/index.html): [Visualization & Compute](https://pygraphistry.readthedocs.io/en/latest/visualization/index.html), [PyGraphistry Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/cheatsheet.html)
+  * [GFQL Documentation](https://pygraphistry.readthedocs.io/en/latest/gfql/index.html):  [GFQL Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/gfql/quick.html) and [GFQL Operator Cheatsheet](https://pygraphistry.readthedocs.io/en/latest/gfql/predicates/quick.html)
+  * [Plugins](https://pygraphistry.readthedocs.io/en/latest/plugins.html): Databricks, Splunk, Neptune, Neo4j, RAPIDS, and more
+  * Web: [iframe](https://hub.graphistry.com/docs/api/1/rest/url/#urloptions),  [JavaScript](https://hub.graphistry.com/static/js-docs/index.html?path=/docs/introduction--docs), [REST](https://hub.graphistry.com/docs/api/1/rest/auth/)
 
 ## Graphistry ecosystem
 
-- **Graphistry server:**
-  - Launch - [Graphistry Hub, Graphistry cloud marketplaces, and self-hosting](https://www.graphistry.com/get-started)
-  - Self-hosting: [Administration (including Docker)](https://github.com/graphistry/graphistry-cli) & [Kubernetes](https://github.com/graphistry/graphistry-helm)
-
-- **Graphistry client APIs:**
-  - Web: [iframe](https://hub.graphistry.com/docs/api/1/rest/url/#urloptions), [JavaScript](https://hub.graphistry.com/static/js-docs/index.html?path=/docs/introduction--docs), [REST](https://hub.graphistry.com/docs/api/1/rest/auth/)
-  - [PyGraphistry](https://pygraphistry.readthedocs.io/en/latest/index.html)
-  - [Graphistry for Microsoft PowerBI](https://hub.graphistry.com/docs/powerbi/pbi/)
+* **Graphistry server:**
+  * Launch - [Graphistry Hub, Graphistry cloud marketplaces, and self-hosting](https://www.graphistry.com/get-started)
+  * Self-hosting: [Administration (including Docker)](https://github.com/graphistry/graphistry-cli) & [Kubernetes](https://github.com/graphistry/graphistry-helm)
 
-- **Additional projects**:
-  - [Louie.ai](https://louie.ai/): GenAI-native notebooks & dashboards to talk to your databases & Graphistry
-  - [graph-app-kit](https://github.com/graphistry/graph-app-kit): Streamlit Python dashboards with batteries-include graph packages
-  - [cu-cat](https://chat.openai.com/chat): Automatic GPU feature engineering
+* **Graphistry client APIs:**
+  * Web: [iframe](https://hub.graphistry.com/docs/api/1/rest/url/#urloptions), [JavaScript](https://hub.graphistry.com/static/js-docs/index.html?path=/docs/introduction--docs), [REST](https://hub.graphistry.com/docs/api/1/rest/auth/)
+  * [PyGraphistry](https://pygraphistry.readthedocs.io/en/latest/index.html)
+  * [Graphistry for Microsoft PowerBI](https://hub.graphistry.com/docs/powerbi/pbi/)
 
+* **Additional projects**:
+  * [Louie.ai](https://louie.ai/): GenAI-native notebooks & dashboards to talk to your databases & Graphistry
+  * [graph-app-kit](https://github.com/graphistry/graph-app-kit): Streamlit Python dashboards with batteries-include graph packages
+  * [cu-cat](https://chat.openai.com/chat): Automatic GPU feature engineering
 
 ## Community and support
 
-- [Blog](https://www.graphistry.com/blog) for tutorials, case studies, and updates
-- [Slack](https://join.slack.com/t/graphistry-community/shared_invite/zt-53ik36w2-fpP0Ibjbk7IJuVFIRSnr6g): Join the Graphistry Community Slack for discussions and support
-- [Twitter](https://twitter.com/graphistry) & [LinkedIn](https://www.linkedin.com/company/graphistry): Follow for updates
-- [GitHub Issues](https://github.com/graphistry/pygraphistry/issues) open source support
-- [Graphistry ZenDesk](https://graphistry.zendesk.com/) dedicated enterprise support
+* [Blog](https://www.graphistry.com/blog) for tutorials, case studies, and updates
+* [Slack](https://join.slack.com/t/graphistry-community/shared_invite/zt-53ik36w2-fpP0Ibjbk7IJuVFIRSnr6g): Join the Graphistry Community Slack for discussions and support
+* [Twitter](https://twitter.com/graphistry) & [LinkedIn](https://www.linkedin.com/company/graphistry): Follow for updates
+* [GitHub Issues](https://github.com/graphistry/pygraphistry/issues) open source support
+* [Graphistry ZenDesk](https://graphistry.zendesk.com/) dedicated enterprise support
 
 ## Contribute
 
 See [CONTRIBUTING](https://pygraphistry.readthedocs.io/en/latest/CONTRIBUTING.html) and [DEVELOP](https://pygraphistry.readthedocs.io/en/latest/DEVELOP.html) for participating in PyGraphistry development, or reach out to our team
-

bin/flake8.sh

@@ -1,29 +1,14 @@
 #!/bin/bash
 set -e
 
-# Try to find the best Python version available
-PYTHON_BIN=""
-for ver in 3.14 3.13 3.12 3.11 3.10 3.9 3.8; do
-    if command -v python$ver &> /dev/null; then
-        PYTHON_BIN=python$ver
-        break
-    fi
-done
+# Minimal resolution: env override or host flake8
+FLAKE8_CMD_ARR=(${FLAKE8_CMD:-flake8})
 
-if [ -z "$PYTHON_BIN" ]; then
-    echo "No suitable Python version found (3.8-3.14)"
+if ! "${FLAKE8_CMD_ARR[@]}" --version &> /dev/null; then
+    echo "flake8 not found. Set FLAKE8_CMD or install flake8 on PATH."
     exit 1
 fi
 
-echo "Using Python: $PYTHON_BIN"
-$PYTHON_BIN --version
-
-# Install flake8 if not available
-if ! $PYTHON_BIN -m flake8 --version &> /dev/null; then
-    echo "Installing flake8..."
-    $PYTHON_BIN -m pip install flake8 --user
-fi
-
 # Get the script directory and repo root
 SCRIPT_DIR="$( cd "$( dirname -- "${BASH_SOURCE[0]}" )" && pwd )"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -44,7 +29,7 @@ echo "Running flake8 on: $TARGET"
 
 # Quick syntax error check
 echo "=== Running quick syntax check ==="
-$PYTHON_BIN -m flake8 \
+"${FLAKE8_CMD_ARR[@]}" \
     $TARGET \
     --count \
     --select=E9,F63,F7,F82 \
@@ -53,7 +38,7 @@ $PYTHON_BIN -m flake8 \
 
 # Full lint check
 echo "=== Running full lint check ==="
-$PYTHON_BIN -m flake8 \
+"${FLAKE8_CMD_ARR[@]}" \
     $TARGET \
     --exclude=graphistry/graph_vector_pb2.py,graphistry/_version.py \
     --count \
@@ -62,4 +47,4 @@ $PYTHON_BIN -m flake8 \
     --max-line-length=127 \
     --statistics
 
-echo "Flake8 check completed successfully!"
+echo "Flake8 check completed successfully!"

bin/lint.sh

@@ -4,25 +4,15 @@ set -ex
 # Run from project root
 # Non-zero exit code on fail
 
-flake8 --version
-
-# Quick syntax errors
-flake8 \
-    graphistry \
-    --count \
-    --select=E9,F63,F7,F82 \
-    --show-source \
-    --statistics
-
-# Deeper check
-flake8 \
-  graphistry \
-  --exclude graphistry/graph_vector_pb2.py,graphistry/_version.py \
-  --count \
-  --ignore=C901,E121,E122,E123,E124,E125,E128,E131,E144,E201,E202,E203,E231,E251,E265,E301,E302,E303,E401,E501,E722,F401,W291,W293,W503 \
-  --max-complexity=10 \
-  --max-line-length=127 \
-  --statistics
+# Resolve flake8 command, then delegate to runner (prefer uvx, then venv)
+if command -v uvx >/dev/null 2>&1; then
+  FLAKE8_CMD="uvx flake8"
+elif command -v python >/dev/null 2>&1; then
+  FLAKE8_CMD="python -m flake8"
+else
+  FLAKE8_CMD="flake8"
+fi
+FLAKE8_CMD="$FLAKE8_CMD" ./bin/flake8.sh "$@"
 
 # Check for relative imports with '..' using flake8-quotes or custom regex
 # This will fail if any relative imports with .. are found

bin/mypy.sh

@@ -1,27 +1,18 @@
 #!/bin/bash
 set -e
 
-# Try to find the best Python version available
-PYTHON_BIN=""
-for ver in 3.14 3.13 3.12 3.11 3.10 3.9 3.8; do
-    if command -v python$ver &> /dev/null; then
-        PYTHON_BIN=python$ver
-        break
-    fi
-done
+# Minimal resolution: env override or host mypy
+MYPY_CMD_ARR=(${MYPY_CMD:-mypy})
 
-if [ -z "$PYTHON_BIN" ]; then
-    echo "No suitable Python version found (3.8-3.14)"
-    exit 1
+MYPY_EXTRA_ARGS_ARR=()
+if [ -n "${MYPY_EXTRA_ARGS:-}" ]; then
+    read -r -a MYPY_EXTRA_ARGS_ARR <<< "$MYPY_EXTRA_ARGS"
 fi
 
-echo "Using Python: $PYTHON_BIN"
-$PYTHON_BIN --version
-
-# Install mypy if not available
-if ! $PYTHON_BIN -m mypy --version &> /dev/null; then
-    echo "Installing mypy..."
-    $PYTHON_BIN -m pip install mypy --user
+# Ensure mypy exists rather than installing (works in CI & avoids PEP 668)
+if ! "${MYPY_CMD_ARR[@]}" --version &> /dev/null; then
+    echo "mypy not found. Set MYPY_CMD or install mypy on PATH."
+    exit 1
 fi
 
 # Get the script directory and repo root
@@ -33,32 +24,21 @@ cd "$REPO_ROOT"
 
 # Check if specific files were passed as arguments
 if [ $# -eq 0 ]; then
-    # No arguments, run on entire graphistry directory using config file
-    TARGET=""
-    CONFIG_ARG="--config-file mypy.ini"
+    TARGET_ARGS=("graphistry")
 else
-    # Use provided arguments
-    TARGET="$@"
-    # Still use config file for consistency
-    CONFIG_ARG="--config-file mypy.ini"
+    TARGET_ARGS=("$@")
 fi
+CONFIG_ARGS=(--config-file mypy.ini)
 
 echo "Running mypy..."
-if [ -z "$TARGET" ]; then
-    echo "Checking entire graphistry directory with mypy.ini config"
-else
-    echo "Checking: $TARGET"
-fi
+echo "Checking: ${TARGET_ARGS[*]}"
 
 # Show mypy version
-$PYTHON_BIN -m mypy --version
+"${MYPY_CMD_ARR[@]}" --version
 
 # Run mypy with config file
-# If no target specified, mypy will use the paths defined in mypy.ini
-if [ -z "$TARGET" ]; then
-    $PYTHON_BIN -m mypy $CONFIG_ARG graphistry
-else
-    $PYTHON_BIN -m mypy $CONFIG_ARG $TARGET
-fi
+CMD=( "${MYPY_CMD_ARR[@]}" "${MYPY_EXTRA_ARGS_ARR[@]}" "${CONFIG_ARGS[@]}" )
+CMD+=( "${TARGET_ARGS[@]}" )
+"${CMD[@]}"
 
-echo "Mypy check completed!"
+echo "Mypy check completed!"

bin/typecheck.sh

@@ -4,11 +4,12 @@ set -ex
 # Run from project root
 # Non-zero exit code on fail
 
-mypy --version
-
-if [ -n "$PYTHON_VERSION" ]; then
-  SHORT_VERSION=$(echo "$PYTHON_VERSION" | cut -d. -f1,2)
-  mypy --python-version "$SHORT_VERSION" --config-file mypy.ini graphistry
+# Resolve mypy command, then delegate to runner (prefer uvx, then venv)
+if command -v uvx >/dev/null 2>&1; then
+  MYPY_CMD="uvx mypy"
+elif command -v python >/dev/null 2>&1; then
+  MYPY_CMD="python -m mypy"
 else
-  mypy --config-file mypy.ini graphistry
+  MYPY_CMD="mypy"
 fi
+MYPY_CMD="$MYPY_CMD" ./bin/mypy.sh "$@"

docs/docker/build-docs.sh

@@ -55,6 +55,7 @@ esac
 NOTEBOOKS_TO_VALIDATE=(
     "/docs/test_notebooks/test_graphistry_import.ipynb"
     "/docs/source/demos/gfql/temporal_predicates.ipynb"
+    "/docs/source/gfql/hop_bounds.ipynb"
 )
 
 for notebook in "${NOTEBOOKS_TO_VALIDATE[@]}"; do
@@ -94,4 +95,4 @@ else:
         echo "$(basename $notebook) execution completed successfully"
     fi
 fi
-done
+done