feat(gfql): Auto-generate JSON Schema for GFQL wire protocol

[lmeyerov]

Feature Request

Problem

The GFQL wire protocol documentation needs a complete JSON Schema, but manually maintaining it is error-prone and likely to drift from the implementation.

Proposed Solution

Create an automated JSON Schema generator that introspects the GFQL AST classes to produce a complete, valid JSON Schema. This would:

1. Inspect AST classes (Chain, ASTNode, ASTEdge, predicates, etc.)
2. Extract type information from class definitions and type hints
3. Generate proper JSON Schema with all definitions including:
   • FilterDict structure
   • All predicate types (GT, LT, IsIn, Contains, etc.)
   • Temporal type definitions
   • Proper discriminated unions using the "type" field

Implementation Options

1. Pydantic Models (Recommended)

   • Add optional Pydantic support to AST classes
   • Use BaseModel.model_json_schema() for automatic generation
   • Benefits: Validation, OpenAPI compatibility, maintained by community

2. Custom Generator

   • Introspect existing classes using Python's inspect module
   • Generate schema from type annotations and class structure
   • Benefits: No new dependencies

3. Runtime Analysis

   • Generate schema by analyzing to_json() output
   • Benefits: Guaranteed to match actual serialization

Benefits

• Always up-to-date schema matching implementation
• Enable client libraries in other languages to validate messages
• Support tooling like JSON Schema validators and code generators
• Better documentation for API consumers

Related Code

• AST classes: graphistry/models/gfql/ast.py
• Predicates: graphistry/models/gfql/predicates/
• Serialization: ASTSerializable.to_json() methods