feat(gfql): Complete GFQL implementation with AST, Let, and Call operations

[lmeyerov]

Summary

This PR provides the complete GFQL (GraphFrame Query Language) implementation that was missing from the incomplete PRs #715/#716. This code implementation contains the comprehensive core functionality extracted from PR #708.

Complete GFQL Implementation:

• AST Classes: ASTLet (DAG patterns), ASTRemoteGraph, ASTRef, ASTCall
• Let Bindings: DAG execution with topological sorting and dependency resolution
• Call Operations: Security-validated method execution with 50+ allowed functions
• Unified API: gfql(), gfql_remote(), gfql_remote_shape() replacing deprecated chain() methods
• Validation Framework: 676+ lines with structured error types (GFQLSyntaxError, GFQLTypeError, GFQLSchemaError)
• Test Suite: 16 test files covering all new functionality (3,000+ lines)

Key Features

AST Implementation

• ASTLet: Enables DAG patterns with named bindings and execution ordering
• ASTRemoteGraph: Load graphs from remote datasets with authentication
• ASTRef: Reference named bindings within Let patterns
• ASTCall: Safe method execution with comprehensive validation

Let Bindings (DAG Patterns)

result = g.gfql(let({
    'suspects': n({'risk_score': gt(8)}),
    'contacts': ref('suspects', [e(), n()]),
    'evidence': ref('contacts', [e_forward({'type': 'transaction'})])
}))

Call Operations

result = g.gfql([
    call('compute_cugraph', {'alg': 'pagerank', 'out_col': 'influence'}),
    call('layout_cugraph', {'layout': 'force_atlas2'})
])

Unified API

• gfql(): Execute GFQL queries locally
• gfql_remote(): Execute on remote GPU servers
• gfql_remote_shape(): Get metadata without downloading data

Technical Implementation

Core Files

• graphistry/compute/ast.py: 498 changes - Core AST implementations
• graphistry/compute/chain_let.py: 445 lines (NEW) - Let execution engine
• graphistry/compute/gfql/call_executor.py: 82 lines (NEW) - Call execution
• graphistry/compute/gfql/call_safelist.py: 477 lines (NEW) - Security safelist
• graphistry/compute/ComputeMixin.py: 75 changes - Unified API methods

Validation Framework

• Comprehensive validation with structured error codes
• Type safety for all parameters and operations
• Schema validation against graph data
• Security validation for Call operations

Test Coverage

• 16 new test files with 3,000+ lines
• Coverage for AST classes, Let bindings, Call operations
• Integration tests for unified API
• Edge cases and error handling

Files Changed

Total: 30 files, 6,190 insertions

Core Implementation (14 files)

• AST classes and validation framework
• Let execution engine with dependency resolution
• Call system with security safelist
• Unified API methods

Test Suite (16 files)

• Complete test coverage for all new functionality
• Integration tests and edge cases
• 3,000+ lines of comprehensive tests

Addresses Missing Implementation

PRs #715/#716 captured only ~20% of the actual GFQL implementation from PR #708. This PR provides:

• 80% missing core functionality
• Complete AST framework
• Let bindings for DAG patterns
• Call operations with security
• Comprehensive validation
• Full test suite

Test Plan

• All existing tests pass
• New test suite provides comprehensive coverage
• AST validation works correctly
• Let binding execution follows proper dependency order
• Call operations respect security safelist
• Unified API methods function correctly
• Error handling provides clear, actionable messages

Breaking Changes

None. All changes are additive with backward compatibility maintained.

Dependencies

No new external dependencies added.

🤖 Generated with Claude Code

[lmeyerov]

Companion PR: This code PR works together with documentation PR #718.

Relationship:

• This PR (feat(gfql): Complete GFQL implementation with AST, Let, and Call operations #717): Complete GFQL code implementation (31 files + 16 test files)
• PR docs(gfql): Comprehensive GFQL documentation with Let, Call, and advanced patterns #718: Complete GFQL documentation (18 documentation files)
• Stacking: PR docs(gfql): Comprehensive GFQL documentation with Let, Call, and advanced patterns #718 is based on this branch to ensure documentation examples work with the implementation

CI Status: ✅ All checks GREEN
Supersedes: PRs #706, #707, #708, #709, #713, #715 (comprehensive extraction from PR #708)

Both PRs should be merged together to provide the complete GFQL feature set.

[lmeyerov]

Closing as superseded by PR #724.

After thorough analysis:

• feat(gfql): Add GraphOperation type constraints for let() bindings #724 contains all functionality from this PR (41 functions each)
• feat(gfql): Add GraphOperation type constraints for let() bindings #724 adds GraphOperation type constraints (graph_operation.py)
• feat(gfql): Add GraphOperation type constraints for let() bindings #724 includes additional test coverage (test_graph_operation.py)
• No unique code found in feat(gfql): Complete GFQL implementation with AST, Let, and Call operations #717 that isn't in feat(gfql): Add GraphOperation type constraints for let() bindings #724

Functionality preserved in #724 with enhancements.