feat: add g.to_file() / graphistry.from_file() for Plottable serialization

[exrhizo]

Summary

• Adds g.to_file(path) and graphistry.from_file(path) for saving/loading Plottable graphs to disk
• Uses parquet for DataFrames, JSON manifest for bindings/settings/metadata, with SHA256 integrity verification
• Supports directory (default, debuggable) and zip archive formats
• Remote server state dropped by default with warning; opt-in via restore_remote=True
• Pydantic 2 as optional dep: pip install graphistry[serialization]
• Tripwire tests catch field drift when new attrs are added to Plottable/PlotterBase
• Golden fixture (v1_bundle) committed for backwards-compatibility testing

New files

File	Purpose
graphistry/io/bundle.py	Generic bundle engine (SHA256, parquet I/O, manifest, zip)
graphistry/io/plottable_bundle.py	Plottable adapter with field groups, to_file, from_file
graphistry/tests/test_io_bundle.py	17 tests for bundle engine
graphistry/tests/test_io_plottable_bundle.py	17 tests for plottable roundtrip, tripwire, golden fixture
graphistry/tests/fixtures/v1_bundle/	Golden fixture (~10KB)

Modified files

• Plottable.py — add _node_target_encoder field + to_file() protocol signature
• PlotterBase.py — add to_file() method (lazy import)
• pygraphistry.py — add standalone from_file() function
• __init__.py — export from_file
• io/__init__.py — lazy import comment
• setup.py — add serialization extra

Test plan

• 34 unit tests pass locally (17 bundle + 17 plottable)
• Existing metadata tests pass (no regressions)
• Smoke test: g.to_file() → graphistry.from_file() roundtrip
• cd docker && WITH_BUILD=0 WITH_LINT=0 WITH_TYPECHECK=0 ./test-cpu-local.sh graphistry/tests/test_io_bundle.py graphistry/tests/test_io_plottable_bundle.py
• Full CI: cd docker && WITH_BUILD=0 ./test-cpu-local.sh

🤖 Generated with Claude Code

[lmeyerov]

can we move the tests to like tests/io/test_bundle.py ?

[lmeyerov]

should test add serialization / ci.yml add it?

[lmeyerov]

also unsure about mypy implications

[lmeyerov]

1. should we also do to_folder / from_folder ?
2. should from_ / to_ accept bytes, not just a path, for diskless flows like http?
3. for to_, allow selection of parquet vs json/csv, and extra kwargs passthrough? This can be good for bigger files, like picking snappy compression, and avoiding the indirection of .zip .

Some of this is scope creep so I can imagine landing without

[lmeyerov]

Serialization is great, thank you! I believe this largely stems for already-reviewed louie pydantics + some changes.

See comments

Change request:

• test/ folder organization to use test/io/*

Discussion (non-blocking?):

• pydantic dep: agreed on making optional, see comments on setup.py, ci. Maybe eventually we can do serialization without it, but not a blocker imo: pydantic is neutral as ~no format implications. I believe our notebooks/streamlit have pydantic2? (cc @mj3cheun @aucahuasi )
• Adding io/ vs reusing models/ is sensible, eg, arrow_uploader bits should probably migrate to that too
• I had some non-blocking requests like format control (ex: picking parquet / zip compression settings, in-memory, and csv/json instead of only binary formats)
• Bigger discussion: Format standardization. : upload / remote_gfql / remote_python do plottable -> remote nexus/fep, so I have to wonder what the relationship between the payload formats is / should be . If these bundles work with the python client, I'd imagine they should work with js / REST / etc . Eg, mandating parquet/arrow can be friction for browser users. But maybe it's ok, esp for v1.

cc @aucahuasi @mj3cheun

[lmeyerov]

Thinking more: we have a datasets.json format that we already upload... can/should that be what we're using?

Using the same format, but converting to reading/writing via pydantic, would be great, and step forward in autodocs here vs current manual: https://hub.graphistry.com/docs/api/2/rest/upload/#createdataset2 . The various repos have validators for them too.

A lot can be derived based on the REST docs, this repo, and FEP's or nexus's dataset loaders

[lmeyerov]

@exrhizo while dev team figures out long-lived version, maybe we mark this experimental somehow just to get landed and unblock things?

We don't have a standard convention right now to mark things this way, maybe we do _experimental on the method name? Then we can support it going forward a bit longer, and after stable version is official, Mark this deprecated, etc, and eventually phase out for the official method name

[exrhizo]

I want to add that the remote data that is serialized includes what graphistry server & dataset id - so that a client can find an upload

[lmeyerov]

Oh that is a little trippy... Interesting.