Skip to content

PyGX

Symbolic Object Model for Python

A symbolic object can be both executed and manipulated, and the two stay in sync. It behaves like any Python object — methods, attributes, validation — and it simultaneously exposes the structure it was built from, so your program is also data your own code can query, edit, diff, and search over.

Ordinary objects are built and then sealed. Trainer(model=Model(units=128)) runs, and the call that produced it is gone. A pg.Object keeps the call:

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}

That one difference is the whole library. Because the structure is still there, a program becomes something your code can operate on:

# Address any value in the tree, at any depth — validated.
t.sym_rebind({'model.units': 64})

# Declare a space of programs where the values live, and enumerate it.
space = Trainer(model=Model(units=pg.oneof([8, 16])), lr=pg.oneof([0.1, 0.01]))
list(pg.iter(space))     # 4 programs

# Compare two programs structurally — which knob differs, and where.
pg.diff(Trainer(model=Model(units=8)), Trainer(model=Model(units=16)))
# Trainer(model=Model(units=Diff(left=8, right=16)))

None of these has a straightforward answer in plain Python: the override arriving as a string, the sweep whose parameters aren't known to a loop, the question of which of two configs differs. The idea has a name — symbolic programming, a paradigm where a program can manipulate its own components as if they were plain data — and PyGX brings it to ordinary class definitions.

If your objects are only ever built and read, you don't need this, and a dataclass or pydantic model is the better tool. PyGX earns its keep at the point where a program becomes something you operate on.

Where to go next

  • Bird's-eye view — a 5–10 minute runnable tour of the core ideas. Start here.
  • User Guide — practical, task-oriented walkthroughs for Python, ML, AutoML, and evolution use cases.
  • Learning PyGX — conceptual material on Symbolic Object-Oriented Programming and Symbolic Detour.
  • API Reference — generated from the source.

Install

pip install pygx

Requires Python 3.12+. The hot paths run in a native Rust core that is installed automatically; on platforms without a wheel, PyGX falls back to the pure-Python core with identical behavior.

PyGX is a continuation and evolution of the PyGlove project from Google Brain / DeepMind, now developed independently.