# Enabling Flexible Deserialization with Unknown Types in PyGlove

We're introducing the option to use `pg.from_json(..., convert_unknown=True)` to allow deserialization to proceed even when the original Python class, function, or method definitions are not available at runtime.

## Motivation: the problem of missing type definitions

When serializing and deserializing complex objects with PyGlove, an issue often arises when the code defining parts of the object (like a specific class `A` or a function `foo` from the example code below) is inaccessible in the deserializing environment (e.g., in a different process or a service that only handles data). By default, PyGlove would raise an error.

## Solution: `UnknownSymbol` objects

With `convert_unknown=True`, PyGlove no longer fails. Instead, it converts these missing types into specialized, dictionary-like `UnknownSymbol` objects, which bypass PyGlove type checking:

For unknown typed objects: An instance of a missing class (e.g., `A(x=1)`) is deserialized as a `pg.symbolic.UnknownTypedObject`. This object behaves like a dictionary, allowing access to the serialized attributes (e.g., `x` and `y`). Crucially, its original class name is preserved and accessible via its `type_name` property.

For unknown types, functions, and methods: Similarly, PyGlove converts these missing definitions into their respective symbolic representations:
* `pg.symbolic.UnknownType`
* `pg.symbolic.UnknownFunction`
* `pg.symbolic.UnknownMethod`

This mechanism allows you to load configuration files or serialized objects without requiring a full definition of every single dependency, treating the missing parts as plain data while retaining essential metadata about their original type.

## Example

Process 1: Serialization (Definitions are present)
```python
import pyglove as pg

class A(pg.Object):
  x: int
  y: str

def foo(t):
  return t + 1

# Save the complex object and function to a file.
pg.save(dict(a=A(x=1, y='hello'), b=foo), '/path/to/data.json')
```

Process 2: Deserialization (Definitions for A and foo are missing)
```python
import pyglove as pg
# Class A and function foo are NOT defined in this environment.

# Load the data, allowing conversion of unknown types.
v = pg.load('/path/to/data.json', convert_unknown=True)

# The instance of A is loaded as an UnknownTypedObject.
print(v.a.type_name)
# Output: '__main__.A'
print(v.a.x)
# Output: 1

# The function foo is loaded as an UnknownFunction.
print(v.b.name)
# Output: '__main__.foo'

# Verification of types:
assert isinstance(v.a, pg.symbolic.UnknownTypedObject)
assert isinstance(v.b, pg.symbolic.UnknownFunction)
```

PiperOrigin-RevId: 833908094

Author: daiyip

pyglove/core/symbolic/__init__.py

@@ -147,4 +147,11 @@
 from pyglove.core.symbolic.base import WritePermissionError
 from pyglove.core.symbolic.error_info import ErrorInfo
 
+# Unknown symbols.
+from pyglove.core.symbolic.unknown_symbols import UnknownSymbol
+from pyglove.core.symbolic.unknown_symbols import UnknownType
+from pyglove.core.symbolic.unknown_symbols import UnknownFunction
+from pyglove.core.symbolic.unknown_symbols import UnknownMethod
+from pyglove.core.symbolic.unknown_symbols import UnknownTypedObject
+
 # pylint: enable=g-bad-import-order

pyglove/core/symbolic/base.py

@@ -2042,7 +2042,7 @@ def from_json(
     context: Optional[utils.JSONConversionContext] = None,
     auto_symbolic: bool = True,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
     allow_partial: bool = False,
     root_path: Optional[utils.KeyPath] = None,
     value_spec: Optional[pg_typing.ValueSpec] = None,
@@ -2073,8 +2073,13 @@ class A(pg.Object):
       identify its parent module and automatically import it. For example,
       if the type is 'foo.bar.A', PyGlove will try to import 'foo.bar' and
       find the class 'A' within the imported module.
-    auto_dict: If True, dict with '_type' that cannot be loaded will remain
-      as dict, with '_type' renamed to 'type_name'.
+    convert_unknown: If True, when a '_type' is not registered and cannot
+      be imported, PyGlove will create objects of:
+        - `pg.symbolic.UnknownType` for unknown types;
+        - `pg.symbolic.UnknownTypedObject` for objects of unknown types;
+        - `pg.symbolic.UnknownFunction` for unknown functions;
+        - `pg.symbolic.UnknownMethod` for unknown methods.
+      If False, TypeError will be raised.
     allow_partial: Whether to allow elements of the list to be partial.
     root_path: KeyPath of loaded object in its object tree.
     value_spec: The value spec for the symbolic list or dict.
@@ -2095,15 +2100,20 @@ class A(pg.Object):
   if context is None:
     if (isinstance(json_value, dict) and (
         context_node := json_value.get(utils.JSONConvertible.CONTEXT_KEY))):
-      context = utils.JSONConversionContext.from_json(context_node, **kwargs)
+      context = utils.JSONConversionContext.from_json(
+          context_node,
+          auto_import=auto_import,
+          convert_unknown=convert_unknown,
+          **kwargs
+      )
       json_value = json_value[utils.JSONConvertible.ROOT_VALUE_KEY]
     else:
       context = utils.JSONConversionContext()
 
   typename_resolved = kwargs.pop('_typename_resolved', False)
   if not typename_resolved:
     json_value = utils.json_conversion.resolve_typenames(
-        json_value, auto_import, auto_dict
+        json_value, auto_import, convert_unknown
     )
 
   def _load_child(k, v):
@@ -2177,7 +2187,7 @@ def from_json_str(
     *,
     context: Optional[utils.JSONConversionContext] = None,
     auto_import: bool = True,
-    auto_dict: bool = False,
+    convert_unknown: bool = False,
     allow_partial: bool = False,
     root_path: Optional[utils.KeyPath] = None,
     value_spec: Optional[pg_typing.ValueSpec] = None,
@@ -2205,8 +2215,13 @@ class A(pg.Object):
       identify its parent module and automatically import it. For example,
       if the type is 'foo.bar.A', PyGlove will try to import 'foo.bar' and
       find the class 'A' within the imported module.
-    auto_dict: If True, dict with '_type' that cannot be loaded will remain
-      as dict, with '_type' renamed to 'type_name'.
+    convert_unknown: If True, when a '_type' is not registered and cannot
+      be imported, PyGlove will create objects of:
+        - `pg.symbolic.UnknownType` for unknown types;
+        - `pg.symbolic.UnknownTypedObject` for objects of unknown types;
+        - `pg.symbolic.UnknownFunction` for unknown functions;
+        - `pg.symbolic.UnknownMethod` for unknown methods.
+      If False, TypeError will be raised.
     allow_partial: If True, allow a partial symbolic object to be created.
       Otherwise error will be raised on partial value.
     root_path: The symbolic path used for the deserialized root object.
@@ -2236,7 +2251,7 @@ def _decode_int_keys(v):
       _decode_int_keys(json.loads(json_str)),
       context=context,
       auto_import=auto_import,
-      auto_dict=auto_dict,
+      convert_unknown=convert_unknown,
       allow_partial=allow_partial,
       root_path=root_path,
       value_spec=value_spec,

pyglove/core/symbolic/object.py

@@ -339,7 +339,8 @@ def __init_subclass__(cls):
 
     # Set `__serialization_key__` before JSONConvertible.__init_subclass__
     # is called.
-    setattr(cls, '__serialization_key__', cls.__type_name__)
+    if '__serialization_key__' not in cls.__dict__:
+      setattr(cls, '__serialization_key__', cls.__type_name__)
 
     super().__init_subclass__()
 

pyglove/core/symbolic/object_test.py

@@ -38,6 +38,7 @@
 from pyglove.core.symbolic.origin import Origin
 from pyglove.core.symbolic.pure_symbolic import NonDeterministic
 from pyglove.core.symbolic.pure_symbolic import PureSymbolic
+from pyglove.core.symbolic.unknown_symbols import UnknownTypedObject
 from pyglove.core.views.html import tree_view  # pylint: disable=unused-import
 
 
@@ -3158,7 +3159,7 @@ class Q(Object):
             Q.partial(P.partial()).to_json_str(), allow_partial=True),
         Q.partial(P.partial()))
 
-  def test_serialization_with_auto_dict(self):
+  def test_serialization_with_convert_unknown(self):
 
     class P(Object):
       auto_register = False
@@ -3181,15 +3182,17 @@ class Q(Object):
         }
     )
     self.assertEqual(
-        base.from_json_str(Q(P(1), y='foo').to_json_str(), auto_dict=True),
-        {
-            'p': {
-                'type_name': P.__type_name__,
-                'x': 1
-            },
-            'y': 'foo',
-            'type_name': Q.__type_name__,
-        }
+        base.from_json_str(
+            Q(P(1), y='foo').to_json_str(), convert_unknown=True
+        ),
+        UnknownTypedObject(
+            type_name=Q.__type_name__,
+            p=UnknownTypedObject(
+                type_name=P.__type_name__,
+                x=1
+            ),
+            y='foo'
+        )
     )
 
   def test_serialization_with_converter(self):

pyglove/core/symbolic/unknown_symbols.py

@@ -0,0 +1,147 @@
+# Copyright 2021 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Symbolic types for reprenting unknown types and objects."""
+
+from typing import Annotated, Any, ClassVar, Literal
+from pyglove.core import typing as pg_typing
+from pyglove.core import utils
+from pyglove.core.symbolic import list as pg_list  # pylint: disable=unused-import
+from pyglove.core.symbolic import object as pg_object
+
+
+class UnknownSymbol(pg_object.Object, pg_typing.CustomTyping):
+  """Interface for symbolic representation of unknown symbols."""
+  auto_register = False
+
+  def custom_apply(self, *args, **kwargs) -> tuple[bool, Any]:
+    """Bypass PyGlove type check."""
+    return (False, self)
+
+
+class UnknownType(UnknownSymbol):
+  """Symbolic object for representing unknown types."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_type'
+
+  # TODO(daiyip): Revisit the design on how `pg.typing.Object()` handles
+  # UnknownType. This hacky solution should be removed in the future.
+  __no_type_check__ = True
+
+  name: str
+  args: list[Any] = []
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    json_dict = {'_type': 'type', 'name': self.name}
+    if self.args:
+      json_dict['args'] = utils.to_json(self.args, **kwargs)
+    return json_dict
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    s = f'<unknown-type {self.name}>'
+    if self.args:
+      s += f'[{", ".join(repr(x) for x in self.args)}]'
+    return s
+
+  def __call__(self, **kwargs):
+    return UnknownTypedObject(
+        type_name=self.name, **kwargs
+    )
+
+
+class UnknownCallable(UnknownSymbol):
+  """Symbolic object for representing unknown callables."""
+
+  auto_register = False
+  name: str
+  CALLABLE_TYPE: ClassVar[Literal['function', 'method']]
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    return {'_type': self.CALLABLE_TYPE, 'name': self.name}
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    return f'<unknown-{self.CALLABLE_TYPE} {self.name}>'
+
+
+class UnknownFunction(UnknownCallable):
+  """Symbolic objject for representing unknown functions."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_function'
+  CALLABLE_TYPE = 'function'
+
+
+class UnknownMethod(UnknownCallable):
+  """Symbolic object for representing unknown methods."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_method'
+  CALLABLE_TYPE = 'method'
+
+
+class UnknownTypedObject(UnknownSymbol):
+  """Symbolic object for representing objects of unknown-type."""
+
+  auto_register = True
+  __serialization_key__ = 'unknown_object'
+
+  type_name: str
+  __kwargs__: Annotated[
+      Any,
+      (
+          'Fields of the original object will be kept as symbolic attributes '
+          'of this object so they can be accessed through `__getattr__`.'
+      )
+  ]
+
+  def sym_jsonify(self, **kwargs) -> utils.JSONValueType:
+    """Converts current object to a dict of plain Python objects."""
+    json_dict = self._sym_attributes.to_json(
+        exclude_keys=set(['type_name']), **kwargs
+    )
+    assert isinstance(json_dict, dict)
+    json_dict[utils.JSONConvertible.TYPE_NAME_KEY] = self.type_name
+    return json_dict
+
+  def format(
+      self,
+      compact: bool = False,
+      verbose: bool = True,
+      root_indent: int = 0,
+      **kwargs
+  ) -> str:
+    exclude_keys = kwargs.pop('exclude_keys', set())
+    exclude_keys.add('type_name')
+    kwargs['exclude_keys'] = exclude_keys
+    return self._sym_attributes.format(
+        compact,
+        verbose,
+        root_indent,
+        cls_name=f'<unknown-type {self.type_name}>',
+        key_as_attribute=True,
+        bracket_type=utils.BracketType.ROUND,
+        **kwargs,
+    )

pyglove/core/symbolic/unknown_symbols_test.py

@@ -0,0 +1,100 @@
+# Copyright 2025 The PyGlove Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import unittest
+from pyglove.core import utils
+from pyglove.core.symbolic import unknown_symbols
+
+
+class UnknownTypeTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownType(name='__main__.ABC', args=[int, str])
+    self.assertEqual(t.name, '__main__.ABC')
+    self.assertEqual(t.args, [int, str])
+    self.assertEqual(
+        repr(t),
+        '<unknown-type __main__.ABC>[<class \'int\'>, <class \'str\'>]'
+    )
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'type',
+            'name': '__main__.ABC',
+            'args': [
+                {'_type': 'type', 'name': 'builtins.int'},
+                {'_type': 'type', 'name': 'builtins.str'},
+            ]
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+    self.assertEqual(
+        t(x=1, y=2),
+        unknown_symbols.UnknownTypedObject(type_name='__main__.ABC', x=1, y=2)
+    )
+
+
+class UnknownFunctionTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownFunction(name='__main__.foo')
+    self.assertEqual(t.name, '__main__.foo')
+    self.assertEqual(repr(t), '<unknown-function __main__.foo>')
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'function',
+            'name': '__main__.foo',
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+
+
+class UnknownMethodTest(unittest.TestCase):
+
+  def test_basics(self):
+    t = unknown_symbols.UnknownMethod(name='__main__.ABC.bar')
+    self.assertEqual(t.name, '__main__.ABC.bar')
+    self.assertEqual(repr(t), '<unknown-method __main__.ABC.bar>')
+    self.assertEqual(
+        t.to_json(),
+        {
+            '_type': 'method',
+            'name': '__main__.ABC.bar',
+        }
+    )
+    self.assertEqual(utils.from_json(t.to_json(), convert_unknown=True), t)
+
+
+class UnknownObjectTest(unittest.TestCase):
+
+  def test_basics(self):
+    v = unknown_symbols.UnknownTypedObject(type_name='__main__.ABC', x=1)
+    self.assertEqual(v.type_name, '__main__.ABC')
+    self.assertEqual(v.x, 1)
+    self.assertEqual(repr(v), '<unknown-type __main__.ABC>(x=1)')
+    self.assertEqual(
+        str(v), '<unknown-type __main__.ABC>(\n  x = 1\n)')
+    self.assertEqual(
+        v.to_json(),
+        {
+            '_type': '__main__.ABC',
+            'x': 1,
+        }
+    )
+    self.assertEqual(utils.from_json(v.to_json(), convert_unknown=True), v)
+
+
+if __name__ == '__main__':
+  unittest.main()