feat(gfql): infer typed schemas from graph data

[lmeyerov]

Closes #1338

Summary

• Add experimental public schema inference via graphistry.infer_schema(g), g.infer_schema(), and g.bind(infer_schema=True).
• Infer public GraphSchema instances from bound local graph data using the existing label__* boolean column convention for node labels and relationship types.
• Infer node/edge property logical types through the existing Arrow/GFQL row-schema bridge, plus an experimental SchemaInferenceReport for presence/nullability detail.
• Infer edge source/destination topology when edge endpoints join to bound node ids with label evidence.
• Store descriptive schema provenance in GraphSchema.metadata so inferred schemas remain self-identifying after bind(schema=...), Arrow declaration export, and catalog conversion.
• Document opt-in inference, presence states, declared override behavior, and remote/no-data caveats.

API Decisions

• Inference is opt-in only. Existing bind(...) calls do not infer.
• The public return object is the feat(gfql): add public declarative schema model #1457 GraphSchema, not a second schema model or internal GraphSchemaCatalog.
• return_report=True returns (GraphSchema, SchemaInferenceReport) for details not represented directly in GraphSchema.
• Presence states:
  • required: observed value on every row for the label/type.
  • optional: observed value on some rows and null on other rows.
  • maybe_absent: dataframe column exists, but no observed value for that label/type.
  • unknown: no rows available for that label/type.
• Declared-vs-inferred interaction:
  • infer_schema(..., schema=declared) uses declared node/edge definitions over inferred definitions with the same names.
  • bind(schema=..., infer_schema=True) is rejected instead of silently merging contracts.
• Stored schema metadata:
  • Pure inference returns GraphSchema.metadata["source"] == "inferred".
  • Declared definitions overriding inferred definitions returns GraphSchema.metadata["source"] == "mixed".
  • Metadata is descriptive provenance, not a validation/equality contract.

Validation

• python3 -m pytest -q graphistry/tests/compute/gfql/test_public_schema.py graphistry/tests/compute/gfql/test_schema_inference.py -> 33 passed, 1 skipped
• python3 -m pytest -q docs/test_doc_examples.py -k schema -> 1 passed, 29 deselected
• python3 -m pytest -q graphistry/tests/compute/gfql -k "schema and not cudf" -> 84 passed, 17 skipped, 2418 deselected
• python3 -m pytest -q graphistry/tests/compute/gfql -k "not cudf" -> 2315 passed, 44 skipped, 144 deselected, 15 xfailed
• ./bin/ruff.sh graphistry/schema.py graphistry/schema_inference.py graphistry/PlotterBase.py graphistry/pygraphistry.py graphistry/Plottable.py graphistry/__init__.py graphistry/tests/compute/gfql/test_public_schema.py graphistry/tests/compute/gfql/test_schema_inference.py -> pass
• ./bin/typecheck.sh -> pass
• git diff --check -> pass

DGX RAPIDS cuDF smoke:

• Re-run on amended head 617d0002: RAPIDS_VERSION=25.02 PROFILE=gfql TEST_FILES="graphistry/tests/compute/gfql/test_schema_inference.py::test_infer_schema_cudf_matches_pandas_representative_case" ./docker/test-rapids-official-local.sh -> 1 passed, 1 warning (cudf 25.02.02)
• Re-run on amended head 617d0002: RAPIDS_VERSION=26.02 PROFILE=gfql TEST_FILES="graphistry/tests/compute/gfql/test_schema_inference.py::test_infer_schema_cudf_matches_pandas_representative_case" ./docker/test-rapids-official-local.sh -> 1 passed (cudf 26.02.01)
  Full PR CI: green on amended head 617d0002, including test-docs, tck-gfql, test-gfql-core 3.12/3.14, broad core/full-ai/pandas/polars/graphviz/spark/neo4j tail, Read the Docs, and changed-line-coverage.
  Review skill: converged after wave 1 fixed one module-level API guard issue, wave 2 found no blocker/important issues, and wave 3 found no blocker/important metadata/provenance issues on amended head 617d0002.

LOC

• Production / implementation: +405 / -2, net +403 LOC
• Tests / fixtures / baselines: +220 / -1, net +219 LOC
• Comments / docs / changelog: +112 / -14, net +98 LOC

Compiler-plan surface touched: no. The change returns and binds public schema objects and reuses the existing GraphSchema.to_catalog() path; it does not modify logical/physical planning, route names, dispatch contracts, IR metadata, verifier/pass extension points, schema/type-system hooks beyond the public #1338 inference surface, remote schema hooks, or source-span/diagnostic fidelity.

Design-intent preservation evidence: inferred schemas round-trip through g.bind(schema=schema).gfql_validate(...), declared schema definitions override inference when explicitly passed, and source/destination topology validation is anchored by test_bind_infer_schema_is_opt_in_and_round_trips_into_preflight.

[lmeyerov]

Ready for manual review on rebased head a2c9c816.

Validation summary:

• Review skill converged: wave 1 fixed module-level no-plotter guard; wave 2 no blocker/important findings.
• Local: focused schema tests, docs executable example audit, ruff, typecheck, diff check, broad GFQL non-cuDF all pass.
• DGX: RAPIDS 25.02 and 26.02 cuDF smoke both pass for schema inference parity.
• CI: full PR CI green, including docs, tck-gfql, test-gfql-core 3.12/3.14, broad matrix tail, and changed-line-coverage.

PR remains blocked only by required manual review; do not merge until approval.