Meta-program Python Objects

Website · Documentation · Bird's-eye view · Tutorials · API

Ordinary objects are built and then sealed — the call that produced them is gone. A pg.Object behaves like any Python object and keeps the structure it was built from — so your code can generate, inspect, diff, patch and tune it as easily as it runs it.

import pygx as pg

class Model(pg.Object):
    units: int = 8

class Trainer(pg.Object):
    model: Model
    lr: float = 0.01

t = Trainer(model=Model(units=128))
t.sym_init_args                     # {'model': Model(units=128), 'lr': 0.01}

# Edit it anywhere in the tree — validated, and everything it touched re-initializes
t.sym_rebind({'model.units': 256})

# Replace any value with a space, and the class IS the search space
space = Trainer(model=Model(units=pg.oneof([64, 128])), lr=pg.oneof([0.1, 0.01]))
list(pg.iter(space))                # 4 programs: (64, 0.1) (64, 0.01) (128, 0.1) (128, 0.01)

No separate schema to keep in sync, no loop to rewrite when a parameter is added, and no path-walking getattr/setattr to apply an override. That one difference is the whole library — everything else is a consequence of it. The idea has a name: symbolic programming, a paradigm where a program can manipulate its own components as if they were plain data.

Install

pip install pygx                # Python 3.12+
pip install "pygx[io]"          # fsspec-backed remote IO (GCS, S3, ...)
pip install "pygx[concurrent]"  # parallel execute/map with retries + progress

More

algo = pg.algo.evolution.regularized_evolution(
    pg.algo.evolution.mutators.Uniform())

for net, feedback in pg.iter(space, 30, algo):
    feedback(score(net))     # your objective; the algorithm does the rest

pg.diff(baseline, candidate)
# Trainer(model=Model(units=Diff(left=8, right=16)))

p = Trainer.partial()    # `model` has no default — so it's a hole
pg.is_partial(p)         # True
p.sym_missing()          # {'model': MISSING_VALUE}

class Layer(pg.Object, topo=True):
    dropout: Any = pg.symbolic.ValueFromParentChain()

Net(dropout=0.5, layer=Layer()).layer.dropout    # 0.5 — read from the ancestor

Sym = pg.symbolize(ThirdPartyClass)     # make it symbolic, no source edits

with pg.detour([(Adam, LAMB)]):         # change what a LIBRARY constructs
    third_party_training_loop()         # → returns a LAMB

with pg.track_origin():
    variant = base.sym_clone()

variant.sym_origin.source is base       # True
variant.sym_origin.tag                  # 'clone'

pg.to_html(trainer)      # an interactive, collapsible tree

See it all on www.pygx.com — every capability with the problem it solves, side by side with the plain-Python alternative.

Fast. Hot paths run in a native Rust core (pygx-core, installed automatically); the pure-Python implementation remains the executable specification, and the full suite runs against both cores on every PR. Validated construction beats pydantic v2 with the whole symbolic model attached, and attribute reads are at dataclass parity — see the full report.

Portable. Wheels for Linux, macOS and Windows on CPython 3.12–3.14, plus a genuinely free-threaded 3.14t wheel (the GIL stays off; see docs/design/gil-free.md §3). Elsewhere PyGX falls back to the pure-Python core with identical behavior.

And when not to reach for it. If your objects are only ever built and read — request payloads, plain records, a config loaded once and never manipulated — a dataclass or pydantic model is the better tool. PyGX earns its keep the moment a program becomes something you operate on.

Documentation

Runnable notebooks live in docs/notebooks/, source examples in examples/.

Upgrading? See the 0.5 migration guide. 0.5.2 removed three long-misspelled names without aliases; earlier versions are covered by the 0.4 guide.

Background

PyGX was originally built at Google Brain / DeepMind by Daiyi Peng to power automated machine learning, under the name PyGlove. The abstraction underneath — symbolic object-oriented programming — turned out to be far more general than AutoML. The original paper was published at NeurIPS 2020, and the same ideas drive Google Cloud Vertex AI NAS, Pax, and Vizier.

@inproceedings{peng2020pyglove,
  title={PyGlove: Symbolic programming for automated machine learning},
  author={Peng, Daiyi and Dong, Xuanyi and Real, Esteban and Tan, Mingxing and Lu, Yifeng and Bender, Gabriel and Liu, Hanxiao and Kraft, Adam and Liang, Chen and Le, Quoc},
  booktitle={Advances in Neural Information Processing Systems (NeurIPS)},
  volume={33},
  pages={96--108},
  year={2020}
}

License

Apache License 2.0. PyGX is derived from PyGlove (also Apache 2.0); see LICENSE and the per-file copyright headers for attribution.

PyGX is developed by Daiyi Peng.