Merge pull request #895 from graphistry/split/letref-list-bindings

GFQL let: list bindings + letrec ref

Author: lmeyerov

CHANGELOG.md

@@ -10,6 +10,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Fixed
 - **Tests / GFQL**: Fixed cuDF compatibility in test files by using `to_set()` helper instead of `.tolist()` (cuDF doesn't support `tolist()`)
+- **GFQL / let-ref**: Documented and tested existing letrec semantics for ref; list bindings now accept implicit Chains.
 - **GFQL / schema**: Apply call() schema effects during validation so enrichments like `get_degrees` are recognized by downstream filters, and prioritize boundary-call validation before schema errors.
 - **GFQL / filters**: Treat boolean literal filters on object-typed columns as booleans instead of numeric mismatches.
 

docs/source/gfql/about.rst

@@ -440,17 +440,18 @@ GFQL's Let bindings enable you to sequence complex graph programs as directed ac
 
 ::
 
-    from graphistry import let, ref, call, Chain
+    from graphistry import let, ref, call, n, e_forward, e, gt
 
     result = g.gfql(let({
         # Stage 1: Find suspicious accounts
-        'suspicious_accounts': [n({'risk_score': gt(80), 'created_recent': True})],
+        'suspicious_accounts': n({'risk_score': gt(80), 'created_recent': True}),
 
         # Stage 2: Trace money flows from suspicious accounts
-        'money_flows': ref('suspicious_accounts', [
+        'money_flows': [
+            n({'risk_score': gt(80), 'created_recent': True}),
             e_forward({'type': 'transfer', 'amount': gt(10000)}, hops=3),
             n()
-        ]),
+        ],
 
         # Stage 3: Compute PageRank to find central nodes
         'ranked': ref('money_flows', [

docs/source/gfql/builtin_calls.rst

@@ -29,7 +29,7 @@ Call operations are invoked using the ``call()`` function within GFQL chains or
         'persons': n({'type': 'person'}),
         'with_degrees': ref('persons', [call('get_degrees', {'col': 'degree'})]),
         'high_degree': ref('with_degrees', [n({'degree': gt(10)})]),
-        'connected': ref('high_degree', [e_forward(), n()])
+        'connected': ref('with_degrees', [n({'degree': gt(10)}), e_forward(), n()])
     }))
 
 All Call operations:

docs/source/gfql/overview.rst

@@ -181,16 +181,17 @@ GFQL Let approach (declarative DAG with named bindings):
 
 .. code-block:: python
 
-    from graphistry import let, ref, Chain
+    from graphistry import let, ref, n, e_forward, ge
 
     # GFQL Let: Define a DAG of named operations
     result = g.gfql(let({
-        'persons': [n({'type': 'person'})],
+        'persons': n({'type': 'person'}),
         'adults': ref('persons', [n({'age': ge(18)})]),  # Reference and filter persons
-        'connections': ref('adults', [
+        'connections': [
+            n({'type': 'person', 'age': ge(18)}),
             e_forward({'type': 'knows'}),
             n()  # Find connections from adults
-        ])
+        ]
     }))
 
     # Access any named result from the DAG

docs/source/gfql/quick.rst

@@ -339,20 +339,21 @@ Remote Mode
 Let Bindings and DAG Patterns
 -----------------------------
 
-Use Let bindings to create directed acyclic graph (DAG) patterns with named operations:
+Use Let bindings to create directed acyclic graph (DAG) patterns with named operations. Lists are treated as implicit Chains.
 
 - **Basic Let with named bindings:**
 
   .. code-block:: python
 
-      from graphistry import let, ref, Chain
+      from graphistry import let, ref, n, e_forward, gt
 
       result = g.gfql(let({
-          'suspects': [n({'risk_score': gt(80)})],
-          'connections': ref('suspects', [
+          'suspects': n({'risk_score': gt(80)}),
+          'connections': [
+              n({'risk_score': gt(80)}),
               e_forward({'type': 'transaction'}),
               n()
-          ])
+          ]
       }))
 
       # Access results by name
@@ -363,14 +364,15 @@ Use Let bindings to create directed acyclic graph (DAG) patterns with named oper
 
   .. code-block:: python
 
-      from graphistry import Chain
+      from graphistry import let, ref, n, e_forward, gt
 
       result = g.gfql(let({
-          'high_value': [n({'balance': gt(100000)})],
-          'large_transfers': ref('high_value', [
+          'high_value': n({'balance': gt(100000)}),
+          'large_transfers': [
+              n({'balance': gt(100000)}),
               e_forward({'type': 'transfer', 'amount': gt(10000)}),
               n()
-          ]),
+          ],
           'suspicious': ref('large_transfers', [
               n({'created_recent': True, 'verified': False})
           ])
@@ -469,7 +471,8 @@ Reference graphs on remote servers for distributed computing:
           'high_risk': ref('remote_data', [
               n({'risk_score': gt(95)})
           ]),
-          'connections': ref('high_risk', [
+          'connections': ref('remote_data', [
+              n({'risk_score': gt(95)}),
               e_forward({'type': 'transaction'}),
               n()
           ])

docs/source/gfql/spec/llm_guide.md

@@ -39,7 +39,7 @@
 
 ## Quick Example: Fraud Detection
 
-**Dense:** `let({'suspicious': n({'risk_score': gt(80)}), 'flows': ref('suspicious', [e_forward(min_hops=1, max_hops=3), n()]), 'ranked': ref('flows', [call('compute_cugraph', {'alg': 'pagerank'})]), 'viz': ref('ranked', [call('encode_point_color', {...}), call('encode_point_icon', {...})])})`
+**Dense:** `let({'suspicious': n({'risk_score': gt(80)}), 'flows': [n({'risk_score': gt(80)}), e_forward(min_hops=1, max_hops=3), n()], 'ranked': ref('flows', [call('compute_cugraph', {'alg': 'pagerank'})]), 'viz': ref('ranked', [call('encode_point_color', {...}), call('encode_point_icon', {...})])})`
 
 **JSON:**
 ```json
@@ -51,9 +51,9 @@
       "chain": [{"type": "Node", "filter_dict": {"risk_score": {"type": "GT", "val": 80}}}]
     },
     "flows": {
-      "type": "ChainRef",
-      "ref": "suspicious",
+      "type": "Chain",
       "chain": [
+        {"type": "Node", "filter_dict": {"risk_score": {"type": "GT", "val": 80}}},
         {"type": "Edge", "direction": "forward", "min_hops": 1, "max_hops": 3, "to_fixed_point": false,
          "edge_match": {"amount": {"type": "GT", "val": 10000}}},
         {"type": "Node", "filter_dict": {}}

docs/source/gfql/spec/python_embedding.md

@@ -332,16 +332,17 @@ GFQL supports directed acyclic graph (DAG) patterns using Let bindings, which al
 ### Let Bindings
 
 ```python
-from graphistry import let, ref, n, e_forward
+from graphistry import let, ref, n, e_forward, ge
 
 # Define DAG patterns with named bindings
 result = g.gfql(let({
     'persons': n({'type': 'person'}),
     'adults': ref('persons', [n({'age': ge(18)})]),
-    'connections': ref('adults', [
+    'connections': [
+        n({'type': 'person', 'age': ge(18)}),
         e_forward({'type': 'knows'}),
-        ref('adults')  # Find connections between adults
-    ])
+        n({'type': 'person', 'age': ge(18)})
+    ]
 }))
 
 # Access individual binding results
@@ -352,7 +353,9 @@ connection_edges = result._edges[result._edges['connections']]
 
 ### Ref (Reference to Named Bindings)
 
-The `ref()` function creates references to named bindings within a Let:
+The `ref()` function creates references to named bindings within a Let.
+Ref chains run on the referenced graph; bindings created by `n()` contain nodes only,
+so edge traversals need a binding that preserves edges (for example, via a list or `Chain([...])`).
 
 ```python
 # Basic reference - just the binding result
@@ -361,13 +364,21 @@ result = g.gfql(let({
     'extended': ref('base')  # Just references 'base'
 }))
 
-# Reference with additional operations
+# Reference with additional operations (node-only refinements)
 result = g.gfql(let({
     'suspects': n({'risk_score': gt(80)}),
-    'lateral_movement': ref('suspects', [
+    'verified': ref('suspects', [
+        n({'verified': True})
+    ])
+}))
+
+# For traversals, inline the seed filter into a list or Chain binding
+result = g.gfql(let({
+    'lateral_movement': [
+        n({'risk_score': gt(80)}),
         e_forward({'type': 'ssh', 'failed_attempts': gt(5)}),
         n({'type': 'server'})
-    ])
+    ]
 }))
 ```
 
@@ -380,10 +391,11 @@ result = g.gfql(let({
     'high_value': n({'balance': gt(100000)}),
 
     # Find transactions from high-value accounts
-    'large_transfers': ref('high_value', [
+    'large_transfers': [
+        n({'balance': gt(100000)}),
         e_forward({'type': 'transfer', 'amount': gt(10000)}),
         n()
-    ]),
+    ],
 
     # Find suspicious patterns
     'suspicious': ref('large_transfers', [
@@ -413,8 +425,12 @@ Call operations can be used within Let bindings for complex workflows:
 
 ```python
 result = g.gfql(let({
-    # Initial filtering
-    'suspects': n({'flagged': True}),
+    # Initial filtering with edges preserved for graph algorithms
+    'suspects': Chain([
+        n({'flagged': True}),
+        e_undirected(),
+        n({'flagged': True})
+    ]),
 
     # Compute PageRank on subgraph
     'ranked': ref('suspects', [

docs/source/gfql/spec/wire_protocol.md

@@ -183,9 +183,12 @@ let({
 
 ### ChainRef Operation
 
+ChainRef executes on the referenced graph; bindings used for edge traversal should retain edges
+(for example, from an ``Edge`` or ``Chain`` binding).
+
 **Python**:
 ```python
-ref('base_nodes', [
+ref('base_graph', [
     e_forward({'weight': gt(0.5)}),
     n({'status': 'active'})
 ])
@@ -195,7 +198,7 @@ ref('base_nodes', [
 ```json
 {
   "type": "ChainRef",
-  "ref": "base_nodes",
+  "ref": "base_graph",
   "chain": [
     {
       "type": "Edge",

graphistry/compute/ast.py

@@ -885,7 +885,7 @@ class ASTLet(ASTObject):
 
     Parameters
     ----------
-    bindings : Dict[str, Union[ASTObject, Chain, Plottable]]
+    bindings : Dict[str, Union[ASTObject, Chain, List[ASTObject], Plottable]]
         Mapping from binding names to graph operations (AST objects or Plottables).
 
     Raises
@@ -902,12 +902,12 @@ class ASTLet(ASTObject):
     """
     bindings: Dict[str, Union['ASTObject', 'Chain', Plottable]]
 
-    def __init__(self, bindings: Dict[str, Union['ASTObject', 'Chain', Plottable, Dict[str, Any]]], validate: bool = True) -> None:
+    def __init__(self, bindings: Dict[str, Union['ASTObject', 'Chain', List['ASTObject'], Plottable, Dict[str, Any]]], validate: bool = True) -> None:
         """Initialize Let with named bindings.
 
-        :param bindings: Dictionary mapping names to GraphOperation instances or JSON dicts.
+        :param bindings: Dictionary mapping names to GraphOperation instances, lists (implicit Chains), or JSON dicts.
                         JSON dicts must have a 'type' field indicating the AST object type.
-        :type bindings: Dict[str, Union[ASTObject, Chain, Plottable, Dict[str, Any]]]
+        :type bindings: Dict[str, Union[ASTObject, Chain, List[ASTObject], Plottable, Dict[str, Any]]]
         :param validate: Whether to validate the bindings immediately
         :type validate: bool
         """
@@ -916,7 +916,24 @@ def __init__(self, bindings: Dict[str, Union['ASTObject', 'Chain', Plottable, Di
         # Process mixed JSON/native objects
         processed_bindings: Dict[str, Any] = {}
         for name, value in bindings.items():
-            if isinstance(value, dict):
+            if isinstance(value, list):
+                # Treat list bindings as implicit Chain operations
+                from graphistry.compute.chain import Chain  # noqa: F401, F811
+                chain_ops: List[ASTObject] = []
+                for op in value:
+                    if isinstance(op, dict):
+                        if 'type' not in op:
+                            raise ValueError(f"JSON binding '{name}' missing 'type' field")
+                        obj_type = op.get('type')
+                        if obj_type == 'Chain':
+                            raise ValueError(
+                                f"Binding '{name}' contains nested Chain in list; use Chain(...) directly"
+                            )
+                        chain_ops.append(from_json(op, validate=False))
+                    else:
+                        chain_ops.append(op)
+                processed_bindings[name] = Chain(chain_ops, validate=False)  # type: ignore
+            elif isinstance(value, dict):
                 # JSON dict - check type and convert if valid
                 if 'type' not in value:
                     raise ValueError(f"JSON binding '{name}' missing 'type' field")

graphistry/compute/chain_let.py

@@ -254,7 +254,13 @@ def execute_node(name: str, ast_obj: Union[ASTObject, 'Chain', 'Plottable'], g:
         if ast_obj.chain:
             # Import chain function to execute the operations
             from .chain import chain as chain_impl
-            chain_result = chain_impl(referenced_result, ast_obj.chain, EngineAbstract(engine.value), policy=policy, context=context)
+            chain_result = chain_impl(
+                referenced_result,
+                ast_obj.chain,
+                EngineAbstract(engine.value),
+                policy=policy,
+                context=context
+            )
             # ASTRef with chain should return the filtered result directly
             result = chain_result
         else: