feat(gfql): Implement mark() operation for pattern annotation (#755)

[lmeyerov]

Summary

Implements mark mode for GFQL that annotates nodes/edges with boolean columns without filtering, enabling multi-stage pattern detection and visualization of match vs non-match entities.

Closes #755

Implementation

Core Features

• Instance method: g.mark(gfql=[n({'type': 'person'})], name='is_person')
• Call operation: g.gfql(call('mark', {'gfql': [n()], 'name': 'hit'}))
• Boolean columns: True for matches, False for non-matches (all entities preserved)
• Target inference: Automatically determines nodes vs edges from GFQL pattern
• Multi-format support: Handles Chain, List[ASTObject], and JSON GFQL (remote execution)

Files Changed

• graphistry/compute/mark.py: Core implementation with full validation
• graphistry/compute/ComputeMixin.py: Method wrapper integration
• graphistry/compute/gfql/call_safelist.py: Safelist registration for call('mark')
• docs/source/gfql/builtin_calls.rst: Comprehensive documentation
• docs/design/mark-mode-design.md: Full design document
• graphistry/tests/compute/test_mark.py: 24 comprehensive tests

Examples

Basic Marking

# Mark VIP customers - all nodes preserved
g2 = g.mark(gfql=[n({'customer_type': 'VIP'})], name='is_vip')
# Result: g2._nodes has 'is_vip' column (True for VIPs, False for others)

Accumulating Marks

g2 = g.mark(gfql=[n({'type': 'person'})], name='is_person')
g3 = g2.mark(gfql=[n({'region': 'EMEA'})], name='is_emea')
# Result: Both 'is_person' and 'is_emea' columns present

In let() DAG

g.gfql(let({
    'marked_people': call('mark', {
        'gfql': [n({'type': 'person'})],
        'name': 'is_person'
    }),
    'marked_vips': ref('marked_people', [
        call('mark', {
            'gfql': [n({'vip': True})],
            'name': 'is_vip'
        })
    ]),
    # Filter to VIPs
    'vips': ref('marked_vips', [n({'is_vip': True})])
}))

With Visualization

g.gfql([
    call('mark', {'gfql': [n({'risk': gt(0.8)})], 'name': 'high_risk'}),
    call('encode_point_color', {
        'column': 'high_risk',
        'categorical_mapping': {True: 'red', False: 'green'}
    })
])

Testing

24 comprehensive unit tests covering:

• ✅ Safelist registration and parameter validation
• ✅ Basic node and edge marking
• ✅ All-match and no-match scenarios
• ✅ Multiple mark accumulation
• ✅ call('mark') execution with exact graph verification
• ✅ JSON GFQL deserialization for remote execution
• ✅ let() DAG composition with marks
• ✅ Edge cases (empty graphs, no nodes/edges)

All tests passing: 24/24 ✅

Enhanced test rigor for call('mark'):

• Verifies exact boolean values for specific entities
• Verifies all other columns preserved
• Verifies edges unchanged (pd.testing.assert_frame_equal)
• Confirms JSON and list GFQL produce identical results

Design Decisions

1. Column naming: User-provided names, error on collision (not auto-increment)
2. Boolean values: True/False (not True/NaN) for cleaner downstream use
3. Target inference: Single method, infers nodes vs edges from GFQL pattern
4. let() semantics: Marks accumulate across bindings naturally

Documentation

• ✅ Full API documentation in docstrings
• ✅ Design document: docs/design/mark-mode-design.md
• ✅ Reference documentation: docs/source/gfql/builtin_calls.rst
• ✅ 5 detailed examples in docs
• ✅ Use cases: fraud detection, security analysis, social networks

Commits

1. 49b6617e - feat(gfql): Implement mark() operation
2. e99cc957 - test(gfql): Add comprehensive tests for mark()
3. 4d2babac - test(gfql): Enhance call('mark') test rigor
4. 987c2d05 - docs(gfql): Add mark() to builtin calls reference

Checklist

• Implementation complete
• All tests passing (24/24)
• Documentation added
• Design document created
• Safelist registration
• Remote execution support (JSON GFQL)
• Error handling and validation
• Examples provided

[lmeyerov]

revisit later, see #820