feat(gfql): Consolidated GFQL core implementation - AST nodes, Let bindings, Call operations

.gitignore

@@ -94,3 +94,4 @@ docs/source/demos
 # AI assistant working directories
 AI_PROGRESS/
 PLAN.md
+test_env/

graphistry/compute/ASTSerializable.py

@@ -1,5 +1,5 @@
 from abc import ABC
-from typing import Dict, List, Optional, TYPE_CHECKING
+from typing import Dict, List, Optional, Sequence, TYPE_CHECKING
 
 from graphistry.utils.json import JSONVal, serialize_to_json_val
 
@@ -34,7 +34,14 @@ def validate(self, collect_all: bool = False) -> Optional[List['GFQLValidationEr
             self._validate_fields()
             # Validate children
             for child in self._get_child_validators():
-                child.validate(collect_all=False)
+                if hasattr(child, 'validate'):
+                    # Check if validate method accepts collect_all parameter
+                    import inspect
+                    sig = inspect.signature(child.validate)
+                    if 'collect_all' in sig.parameters:
+                        child.validate(collect_all=False)
+                    else:
+                        child.validate()
             return None
 
         # Collect all errors mode
@@ -54,9 +61,29 @@ def validate(self, collect_all: bool = False) -> Optional[List['GFQLValidationEr
 
         # Collect child validation errors
         for child in self._get_child_validators():
-            child_errors = child.validate(collect_all=True)
-            if child_errors:
-                errors.extend(child_errors)
+            if hasattr(child, 'validate'):
+                # Check if validate method accepts collect_all parameter
+                import inspect
+                sig = inspect.signature(child.validate)
+                if 'collect_all' in sig.parameters:
+                    child_errors = child.validate(collect_all=True)
+                    if child_errors:
+                        errors.extend(child_errors)
+                else:
+                    # Old-style validate without collect_all
+                    try:
+                        child.validate()
+                    except Exception as e:
+                        from graphistry.compute.exceptions import GFQLValidationError
+                        if isinstance(e, GFQLValidationError):
+                            errors.append(e)
+                        else:
+                            from graphistry.compute.exceptions import ErrorCode
+                            errors.append(GFQLValidationError(
+                                ErrorCode.E201,
+                                f"Validation error in child: {str(e)}",
+                                value=str(child)
+                            ))
 
         return errors
 
@@ -68,11 +95,11 @@ def _validate_fields(self) -> None:
         """
         pass
 
-    def _get_child_validators(self) -> List['ASTSerializable']:
+    def _get_child_validators(self) -> Sequence['ASTSerializable']:
         """Override in subclasses to return child AST nodes that need validation.
 
         Returns:
-            List of child AST nodes to validate
+            Sequence of child AST nodes to validate
         """
         return []
 

graphistry/compute/ComputeMixin.py

@@ -1,12 +1,17 @@
-import numpy as np, pandas as pd
+import numpy as np
+import pandas as pd
 from typing import Any, List, Union
 from inspect import getmodule
 
 from graphistry.Engine import Engine, EngineAbstract
 from graphistry.Plottable import Plottable
 from graphistry.util import setup_logger
 from .chain import chain as chain_base
-from .chain_remote import chain_remote as chain_remote_base, chain_remote_shape as chain_remote_shape_base
+from .gfql_unified import gfql as gfql_base
+from .chain_remote import (
+    chain_remote as chain_remote_base,
+    chain_remote_shape as chain_remote_shape_base
+)
 from .python_remote import (
     python_remote_g as python_remote_g_base,
     python_remote_table as python_remote_table_base,
@@ -460,16 +465,76 @@ def filter_edges_by_dict(self, *args, **kwargs):
     filter_edges_by_dict.__doc__ = filter_edges_by_dict_base.__doc__
 
     def chain(self, *args, **kwargs):
+        """
+        .. deprecated:: 2.XX.X
+           Use :meth:`gfql` instead for a unified API that supports both chains and DAGs.
+        """
+        import warnings
+        warnings.warn(
+            "chain() is deprecated. Use gfql() instead for a unified API.",
+            DeprecationWarning,
+            stacklevel=2
+        )
         return chain_base(self, *args, **kwargs)
-    chain.__doc__ = chain_base.__doc__
+    # Preserve original docstring after deprecation notice
+    chain.__doc__ = (chain.__doc__ or "") + "\n\n" + (chain_base.__doc__ or "")
+
+    # chain_let removed from public API - use gfql() instead
+    # (chain_let_base still available internally for gfql dispatch)
+
+    def gfql(self, *args, **kwargs):
+        return gfql_base(self, *args, **kwargs)
+    gfql.__doc__ = gfql_base.__doc__
 
     def chain_remote(self, *args, **kwargs) -> Plottable:
+        """
+        .. deprecated:: 2.XX.X
+           Use :meth:`gfql_remote` instead for a unified API that supports both chains and DAGs.
+        """
+        import warnings
+        warnings.warn(
+            "chain_remote() is deprecated. Use gfql_remote() instead for a unified API.",
+            DeprecationWarning,
+            stacklevel=2
+        )
         return chain_remote_base(self, *args, **kwargs)
-    chain_remote.__doc__ = chain_remote_base.__doc__
+    # Preserve original docstring after deprecation notice
+    chain_remote.__doc__ = (chain_remote.__doc__ or "") + "\n\n" + (chain_remote_base.__doc__ or "")
 
     def chain_remote_shape(self, *args, **kwargs) -> pd.DataFrame:
+        """
+        .. deprecated:: 2.XX.X
+           Use :meth:`gfql_remote_shape` instead for a unified API that supports both chains and DAGs.
+        """
+        import warnings
+        warnings.warn(
+            "chain_remote_shape() is deprecated. Use gfql_remote_shape() instead for a unified API.",
+            DeprecationWarning,
+            stacklevel=2
+        )
+        return chain_remote_shape_base(self, *args, **kwargs)
+    # Preserve original docstring after deprecation notice
+    chain_remote_shape.__doc__ = (chain_remote_shape.__doc__ or "") + "\n\n" + (chain_remote_shape_base.__doc__ or "")
+
+    def gfql_remote(self, *args, **kwargs) -> Plottable:
+        """Run GFQL query remotely.
+
+        This is the remote execution version of :meth:`gfql`. It supports both simple chains
+        and complex DAG patterns with Let bindings.
+
+        See :meth:`chain_remote` for detailed documentation (chain_remote is deprecated).
+        """
+        return chain_remote_base(self, *args, **kwargs)
+
+    def gfql_remote_shape(self, *args, **kwargs) -> pd.DataFrame:
+        """Get shape metadata for remote GFQL query execution.
+
+        This is the remote shape version of :meth:`gfql`. Returns metadata about the 
+        resulting graph without downloading the full data.
+
+        See :meth:`chain_remote_shape` for detailed documentation (chain_remote_shape is deprecated).
+        """
         return chain_remote_shape_base(self, *args, **kwargs)
-    chain_remote_shape.__doc__ = chain_remote_shape_base.__doc__
 
     def python_remote_g(self, *args, **kwargs) -> Any:
         return python_remote_g_base(self, *args, **kwargs)

graphistry/compute/__init__.py

@@ -1,6 +1,7 @@
 from .ComputeMixin import ComputeMixin
 from .ast import (
-    n, e, e_forward, e_reverse, e_undirected
+    n, e, e_forward, e_reverse, e_undirected,
+    let, remote, ref, call
 )
 from .chain import Chain
 from .predicates.is_in import (
@@ -54,3 +55,39 @@
     notnull, NotNull,
 )
 from .typing import DataFrameT
+
+__all__ = [
+    # Core classes
+    'ComputeMixin', 'Chain',
+    # AST nodes
+    'n', 'e', 'e_forward', 'e_reverse', 'e_undirected',
+    'let', 'remote', 'ref', 'call',
+    # Predicates
+    'is_in', 'IsIn',
+    'duplicated', 'Duplicated',
+    'is_month_start', 'IsMonthStart',
+    'is_month_end', 'IsMonthEnd',
+    'is_quarter_start', 'IsQuarterStart',
+    'is_quarter_end', 'IsQuarterEnd',
+    'is_year_start', 'IsYearStart',
+    'is_year_end', 'IsYearEnd',
+    'is_leap_year', 'IsLeapYear',
+    # Temporal
+    'TemporalValue', 'DateTimeValue', 'DateValue', 'TimeValue',
+    'temporal_value_from_json',
+    # Comparison predicates
+    'gt', 'GT', 'lt', 'LT', 'ge', 'GE', 'le', 'LE',
+    'eq', 'EQ', 'ne', 'NE', 'between', 'Between',
+    'isna', 'IsNA', 'notna', 'NotNA',
+    # String predicates
+    'contains', 'Contains', 'startswith', 'Startswith',
+    'endswith', 'Endswith', 'match', 'Match',
+    'isnumeric', 'IsNumeric', 'isalpha', 'IsAlpha',
+    'isdigit', 'IsDigit', 'islower', 'IsLower',
+    'isupper', 'IsUpper', 'isspace', 'IsSpace',
+    'isalnum', 'IsAlnum', 'isdecimal', 'IsDecimal',
+    'istitle', 'IsTitle', 'isnull', 'IsNull',
+    'notnull', 'NotNull',
+    # Types
+    'DataFrameT'
+]