Research parameter binding for non-string GFQL AST and Chain queries

[lmeyerov]

Current behavior

g.gfql(..., params=...) only accepts params when the query is a string (currently the local Cypher path).

• graphistry/compute/gfql_unified.py documents params as an optional parameter dictionary for string-query compilation.
• Non-string inputs explicitly raise ValueError("params is only supported when query is a string").
• Regression coverage exists in graphistry/tests/compute/test_gfql.py::test_gfql_non_string_rejects_language_and_params.

Why this gap matters

AST / Chain / dict GFQL queries can inline Python values today, but they cannot be reused as parameterized templates in the same way as local Cypher strings. That creates a parity gap for:

• generated or serialized GFQL AST JSON
• agent / UI query templates
• safer late binding of user input without rebuilding the AST object graph
• feature parity expectations when users move between g.gfql("MATCH ...", params=...) and g.gfql([...])

Research questions

• Do we want top-level params to work for AST / Chain / dict / ASTLet inputs?
• If yes, how should placeholders be represented in Python AST objects and JSON?
• Should binding happen before validation / policy hooks / remote serialization, or later?
• What are the semantics for missing params, defaults, type coercion, and nested call(...) params?
• Is the better product decision to keep params string-only and document that choice more explicitly?

Success criteria

• Decide whether AST params are in scope.
• If yes, sketch placeholder semantics, API shape, validation rules, and test coverage.
• If no, document the string-only constraint clearly in API and user-facing docs.