feat(gfql): infer typed graph schemas

Author: lmeyerov

CHANGELOG.md

@@ -9,6 +9,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 <!-- Do Not Erase This Section - Used for tracking unreleased changes -->
 
 ### Added
+- **GFQL schema inference API (#1338)**: Added experimental `graphistry.infer_schema(g)`, `g.infer_schema()`, and `g.bind(infer_schema=True)` for opt-in public `GraphSchema` inference from bound local graph data. Inference derives node/edge property logical types, presence/nullability report details, `label__*` node and relationship labels, and source/destination topology when node label evidence is available. Declared schemas remain explicit and take precedence when passed to `infer_schema(..., schema=...)`; `bind(schema=..., infer_schema=True)` is rejected instead of silently merging contracts.
 - **GFQL NetworkX CALL parity (#1058)**: Expanded the local Cypher `graphistry.nx.*` CALL surface with explicit NetworkX dispatch for `degree_centrality`, `closeness_centrality`, `eigenvector_centrality`, `katz_centrality`, `connected_components`, `strongly_connected_components`, `core_number`, and multi-output `hits`, including row and `.write()` coverage.
 - **NetworkX/SciPy optional dependency policy (#1618)**: Declared supported `networkx>=2.5,<4` and optional `scipy>=1.5,<2` ranges for NetworkX-backed GFQL CALL procedures, with runtime version guards and a focused lower/current-upper CI matrix.
 - **GFQL public schema declarations (#1337)**: Added experimental `graphistry.schema` exports for `NodeType`, `EdgeType`, `GraphSchema`, and `EdgeTopology`, plus top-level `graphistry` re-exports. `NodeType` and `EdgeType` accept Arrow-first `pyarrow.Schema` declarations, preserve dtype/nullability through GFQL `RowSchema`, and export back to Arrow with label/type columns via `to_arrow()`. `graphistry.bind(..., schema=schema)` / `g.bind(schema=schema)` attach public schema declarations to plotters, and Cypher preflight validation consumes the adapted internal `GraphSchemaCatalog` for declared labels, properties, relationship types, and source/destination topology checks. `GraphSchema(strict=False)` makes schema-bound `g.gfql_validate(...)` permissive by default while explicit call-level `strict=True` still forces strict validation.

docs/source/gfql/schema.rst

@@ -5,8 +5,9 @@ GFQL accepts public schema declarations through the stable
 ``graphistry.schema`` import path. Use this when application code owns a graph
 contract and wants Cypher preflight checks to fail before query execution.
 The API is experimental in this release: the import path and core declaration
-objects are intended to be stable, while inference, coercion, remote transport,
-and planner use are still follow-on surfaces.
+objects are intended to be stable, while coercion, remote transport, and
+planner use are still follow-on surfaces. Inference is also experimental and
+must be requested explicitly.
 
 The schema is optional. When you provide one, PyGraphistry uses it as the
 declared contract for local GFQL validation. When you do not provide one,
@@ -118,27 +119,100 @@ This is a correctness and documentation surface first: applications can state
 what labels, relationship types, properties, and topology they expect, then
 validate user-authored or generated Cypher before running it. The same typed
 contract is also the foundation for later inference, coercion, remote transport,
-and planner/performance work, but this page covers the declared local contract.
+and planner/performance work.
 
-Provided vs. Inferred Schema
-----------------------------
+Provided Or Inferred Schema
+---------------------------
 
-In this release, schemas are **provided**, not inferred. You create
-``NodeType``, ``EdgeType``, and ``GraphSchema`` objects directly and attach them
-with ``graphistry.bind(..., schema=schema)`` or ``g.bind(schema=schema)``.
+You can provide a schema directly or infer one from bound local data.
 
-Without an explicit ``GraphSchema``:
+Use a provided schema when application code owns the contract:
 
-* ``g.gfql_validate(...)`` can still use local dataframe columns already bound
-  on ``g._nodes`` and ``g._edges`` for schema-aware checks.
-* It does not infer node types, edge types, Arrow dtypes, nullability, or
-  topology from data.
+.. code-block:: python
+
+   g = graphistry.edges(edges_df, "src", "dst").nodes(nodes_df, "id")
+   g = g.bind(schema=schema)
+
+Use inference when the graph data should define the first draft contract:
+
+.. code-block:: python
+
+   schema = g.infer_schema()
+   g = g.bind(schema=schema)
+
+For one-step local binding, use:
+
+.. code-block:: python
+
+   g = g.bind(infer_schema=True)
+
+Inference is opt-in. ``graphistry.bind(...)`` and ``g.bind(...)`` do not infer a
+schema unless ``infer_schema=True`` is passed.
+
+Inference Rules
+---------------
+
+``graphistry.infer_schema(g)`` and ``g.infer_schema()`` return a public
+``GraphSchema``. They inspect currently bound ``nodes`` and ``edges`` dataframes:
+
+* Node types come from boolean ``label__<Label>`` columns on the node table.
+* Edge types come from boolean ``label__<TYPE>`` columns on the edge table.
+* Node properties are non-label node columns observed on rows for a label.
+* Edge properties are non-label edge columns, excluding the bound source,
+  destination, and edge-id columns.
+* Source/destination topology is inferred when edges reference bound node ids
+  and those nodes have label columns. Edge-only graphs keep edge types and
+  properties, but do not invent endpoint labels.
 * A remote-only graph such as ``graphistry.bind(dataset_id="...")`` has no
   local dataframe columns, so local validation is limited to syntax, compile,
   and structural checks unless you also bind a declared schema.
 
-Schema inference from existing plottables is tracked separately from this
-declared-schema API.
+Inference uses the same Arrow/GFQL row-schema bridge as declared schemas for
+logical property types. The returned ``GraphSchema`` can be passed to
+``g.bind(schema=schema)`` and used by ``g.gfql_validate(...)``.
+
+Presence And Nullability
+------------------------
+
+The public ``GraphSchema`` stores the inferred logical type and scalar
+nullability needed by validation. For more detail, request the experimental
+report:
+
+.. code-block:: python
+
+   schema, report = g.infer_schema(return_report=True)
+
+The report tracks property presence separately from type:
+
+``required``
+  The property has observed values on every row for that node label or edge
+  type.
+
+``optional``
+  The property has observed values on some rows and nulls on other rows for
+  that node label or edge type.
+
+``maybe_absent``
+  The column exists on the dataframe but has no observed value for that node
+  label or edge type. This commonly means another label/type uses the column.
+
+``unknown``
+  No rows were available for that node label or edge type.
+
+Declared Overrides
+------------------
+
+Declared schemas stay explicit. Passing ``schema=...`` to ``infer_schema()``
+uses declared node and edge definitions in preference to inferred definitions
+with the same names, while keeping inferred definitions for other names.
+
+.. code-block:: python
+
+   schema = g.infer_schema(schema=declared_schema)
+
+``g.bind(schema=..., infer_schema=True)`` is rejected. Use either a provided
+schema or inferred schema in a single bind call so the validation contract is
+unambiguous.
 
 Local vs. Remote GFQL
 ---------------------

graphistry/Plottable.py

@@ -364,9 +364,13 @@ def bind(
         nodes_file_id: Optional[str] = None,
         edges_file_id: Optional[str] = None,
         schema: Optional[Any] = None,
+        infer_schema: Any = False,
     ) -> 'Plottable':
         ...
 
+    def infer_schema(self, *, schema: Optional[Any] = None, return_report: bool = False) -> Any:
+        ...
+
     def copy(self) -> 'Plottable':
         ...
 

graphistry/PlotterBase.py

@@ -1618,6 +1618,7 @@ def bind(self,
             nodes_file_id: Optional[str] = None,
             edges_file_id: Optional[str] = None,
             schema: Optional[Any] = None,
+            infer_schema: Any = False,
         ) -> Plottable:
         """Relate data attributes to graph structure and visual representation. To facilitate reuse and replayable notebooks, the binding call is chainable. Invocation does not effect the old binding: it instead returns a new Plotter instance with the new bindings added to the existing ones. Both the old and new bindings can then be used for different graphs.
 
@@ -1690,6 +1691,9 @@ def bind(self,
         :param schema: Optional experimental public GFQL schema declaration from ``graphistry.schema``.
         :type schema: Optional[Any]
 
+        :param infer_schema: Infer an experimental public GFQL schema from currently bound data and attach it.
+        :type infer_schema: bool
+
         :returns: Plotter
         :rtype: Plotter
 
@@ -1769,7 +1773,16 @@ def bind(self,
         res._url = url or self._url
         res._nodes_file_id = nodes_file_id or self._nodes_file_id
         res._edges_file_id = edges_file_id or self._edges_file_id
-        res._gfql_schema = schema if schema is not None else self._gfql_schema
+        if schema is not None and infer_schema:
+            raise ValueError("schema and infer_schema cannot both be set")
+        if infer_schema and self._gfql_schema is not None:
+            raise ValueError("schema and infer_schema cannot both be set")
+        if infer_schema:
+            from graphistry.schema_inference import infer_schema as _infer_schema
+
+            res._gfql_schema = _infer_schema(res)
+        else:
+            res._gfql_schema = schema if schema is not None else self._gfql_schema
 
         # Invalidate dataset_id if we're changing encodings, not setting IDs
         encoding_params_changed = any([
@@ -1788,6 +1801,12 @@ def bind(self,
     def copy(self) -> Plottable:
         return copy.copy(self)
 
+    def infer_schema(self, *, schema: Optional[Any] = None, return_report: bool = False) -> Any:
+        """Infer an experimental public GFQL schema from currently bound data."""
+        from graphistry.schema_inference import infer_schema
+
+        return infer_schema(self, schema=schema, return_report=return_report)
+
 
     def nodes(self, nodes: Union[Callable, Any], node=None, *args, **kwargs) -> Plottable:
         """Specify the set of nodes and associated data.

graphistry/__init__.py

@@ -42,6 +42,7 @@
     encode_point_badge,
     encode_edge_badge,
     apply_encodings,
+    infer_schema,
     hypergraph,
     bolt,
     cypher,
@@ -140,6 +141,12 @@
     NodeType,
 )
 
+from graphistry.schema_inference import (
+    InferredProperty,
+    PresenceState,
+    SchemaInferenceReport,
+)
+
 from graphistry.privacy import (
     Mode, Privacy
 )

graphistry/pygraphistry.py

@@ -1925,12 +1925,14 @@ def bind(
         nodes_file_id: Optional[str] = None,
         edges_file_id: Optional[str] = None,
         schema: Optional[Any] = None,
+        infer_schema: Any = False,
     ) -> Plotter:
         """Create a base plotter.
 
         Typically called at start of a program. For parameters, see ``plotter.bind()`` .
         The ``schema`` parameter accepts the experimental public GFQL schema
-        declarations from ``graphistry.schema``.
+        declarations from ``graphistry.schema``. ``infer_schema=True`` infers
+        that schema from currently bound local data.
 
         :returns: Plotter
         :rtype: Plotter
@@ -1974,8 +1976,17 @@ def bind(
             nodes_file_id=nodes_file_id,
             edges_file_id=edges_file_id,
             schema=schema,
+            infer_schema=infer_schema,
         ))
 
+    def infer_schema(self, g: Optional[Any] = None, *, schema: Optional[Any] = None, return_report: bool = False) -> Any:
+        """Infer an experimental public GFQL schema from a plotter."""
+        from graphistry.schema_inference import infer_schema
+
+        if g is None:
+            raise ValueError("graphistry.infer_schema(g) requires a plotter; use g.infer_schema() for bound graphs")
+        return infer_schema(g, schema=schema, return_report=return_report)
+
     def from_dataset_id(self, dataset_id: str, api_token: Optional[str] = None) -> Plotter:
         """Fetch existing remote dataset metadata and hydrate a Plotter.
 
@@ -2763,6 +2774,7 @@ def _handle_api_response(self, response):
 encode_point_badge = PyGraphistry.encode_point_badge
 encode_edge_badge = PyGraphistry.encode_edge_badge
 apply_encodings = PyGraphistry.apply_encodings
+infer_schema = PyGraphistry.infer_schema
 infer_labels = PyGraphistry.infer_labels
 name = PyGraphistry.name
 description = PyGraphistry.description