symbolicai 0.20.2__py3-none-any.whl → 1.0.0__py3-none-any.whl

symai/symbol.py

@@ -1,9 +1,9 @@
 import copy
 import html
 import json
+from collections.abc import Callable, Iterator
 from json import JSONEncoder
-from typing import (Any, Callable, Dict, Generic, Iterator, List, Optional,
-                    Tuple, Type, TypeVar)
+from typing import Any, ClassVar
 
 import numpy as np
 from box import Box
@@ -11,8 +11,6 @@ from box import Box
 from . import core
 from .ops import SYMBOL_PRIMITIVES
 
-T = TypeVar('T')
-
 
 class SymbolEncoder(JSONEncoder):
     def default(self, o):
@@ -30,7 +28,7 @@ class SymbolEncoder(JSONEncoder):
         return JSONEncoder.default(self, o)
 
 
-class Metadata(object):
+class Metadata:
     # create a method that allow to dynamically assign a attribute if not in __dict__
     # example: metadata = Metadata()
     # metadata.some_new_attribute = 'some_value'
@@ -111,7 +109,7 @@ class Metadata(object):
         _val = ''
         if self.value is not None:
             _val += str(self.value)
-        return _val + f"Properties({str({k: str(v) for k, v in self.__dict__.items() if not k.startswith('_')})})"
+        return _val + f"Properties({ {k: str(v) for k, v in self.__dict__.items() if not k.startswith('_')}!s})"
 
     def __repr__(self) -> str:
         '''
@@ -128,7 +126,7 @@ class Metadata(object):
 
 
 class Linker(Metadata):
-    def keys(self) -> List[str]:
+    def keys(self) -> list[str]:
         '''
         Get all keys of the linker.
 
@@ -137,7 +135,7 @@ class Linker(Metadata):
         '''
         return list(self.results.keys())
 
-    def values(self) -> List[Any]:
+    def values(self) -> list[Any]:
         '''
         Get all values of the linker.
 
@@ -160,15 +158,19 @@ class Linker(Metadata):
         '''
         # search all results and return the first one that matches the name
         res = []
+        def match_(key, search_name):
+            if strict:
+                return str(search_name) == str(key)
+            return str(search_name).lower() in str(key).lower()
+
         for k in list(self.results.keys()):
-            match_ = lambda k, name: str(name).lower() in str(k).lower() if not strict else str(name) == str(k)
             if match_(k, name):
                 res.append(self.results[k])
         if single:
             assert len(res) == 1, f'Found {len(res)} results for name {name}. Expected 1.'
         if len(res) == 0:
             return None
-        elif len(res) == 1:
+        if len(res) == 1:
             return res[0]
         return res
 
@@ -207,15 +209,16 @@ class SymbolMeta(type):
         return cls
 
 
-class Symbol(Generic[T], metaclass=SymbolMeta):
-    _mixin                = True
-    _primitives           = SYMBOL_PRIMITIVES
-    _metadata             = Metadata()
-    _metadata._primitives = {}
-    _dynamic_context: Dict[str, List[str]] = {}
-    _RESERVED_PROPERTIES = {'graph', 'linker', 'parent', 'children', 'metadata', 'value', 'root', 'nodes', 'edges', 'global_context', 'static_context', 'dynamic_context', 'shape'}
+class Symbol(metaclass=SymbolMeta):
+    _mixin: ClassVar[bool] = True
+    _primitives: ClassVar[dict[str, type]] = SYMBOL_PRIMITIVES
+    _metadata: ClassVar[Metadata] = Metadata()
+    _metadata_primitives: ClassVar[dict[str, Callable]] = {}
+    _metadata._primitives = _metadata_primitives
+    _dynamic_context: ClassVar[dict[str, list[str]]] = {}
+    _RESERVED_PROPERTIES: ClassVar[set[str]] = {'graph', 'linker', 'parent', 'children', 'metadata', 'value', 'root', 'nodes', 'edges', 'global_context', 'static_context', 'dynamic_context', 'shape'}
 
-    def __init__(self, *value, static_context: Optional[str] = '', dynamic_context: Optional[str] = None, **kwargs) -> None:
+    def __init__(self, *value, static_context: str | None = '', dynamic_context: str | None = None, **kwargs) -> None:
         '''
         Initialize a Symbol instance with a specified value. Unwraps nested symbols.
 
@@ -252,11 +255,11 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         '''
         def _func(k, v):
             # check if property is of type Symbol and not private and a class variable (not a function)
-            if isinstance(v, Symbol) and not k.startswith('_') and not v is self:
+            if isinstance(v, Symbol) and not k.startswith('_') and v is not self:
                 v._parent = self
                 self._children.append(v)
             # else if iterable, check if it contains symbols
-            elif (isinstance(v, list) or isinstance(v, tuple)) and not k.startswith('_'):
+            elif isinstance(v, (list, tuple)) and not k.startswith('_'):
                 for i in v:
                     _func(k, i)
 
@@ -267,45 +270,33 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
     def _unwrap_symbols_args(self, *args, nested: bool = False) -> Any:
         if len(args) == 0:
             return None
-        # check if args is a single value
-        elif len(args) == 1:
-            # get the first args value
-            value = args[0]
-
-            # if the value is a primitive, store it as is
-            if isinstance(value, str) or isinstance(value, int) or isinstance(value, float) or isinstance(value, bool):
-                pass
-
-            # if the value is a symbol, unwrap it
-            elif isinstance(value, Symbol):
-                # if not nested, copy the symbol's value, metadata, parent, and children
-                if not nested:
-                    self._metadata       = value.metadata
-                    self._static_context = value.static_context
-                    self._kwargs         = value._kwargs
-                # unwrap the symbol's value
-                value                    = value.value
-
-            # if the value is a list, tuple, dict, or set, unwrap all nested symbols
-            elif isinstance(value, list) or isinstance(value, dict) or \
-                    isinstance(value, set) or isinstance(value, tuple):
-
-                if isinstance(value, list):
-                    value = [self._unwrap_symbols_args(v, nested=True) for v in value]
-
-                elif isinstance(value, dict):
-                    value = {self._unwrap_symbols_args(k, nested=True): self._unwrap_symbols_args(v, nested=True) for k, v in value.items()}
-
-                elif isinstance(value, set):
-                    value = {self._unwrap_symbols_args(v, nested=True) for v in value}
-
-                elif isinstance(value, tuple):
-                    value = tuple([self._unwrap_symbols_args(v, nested=True) for v in value])
+        if len(args) == 1:
+            return self._unwrap_single_symbol_arg(args[0], nested=nested)
+        if len(args) > 1:
+            return [self._unwrap_symbols_args(a, nested=True) if isinstance(a, Symbol) else a for a in args]
+        return None
 
+    def _unwrap_single_symbol_arg(self, value: Any, *, nested: bool) -> Any:
+        if isinstance(value, (str, int, float, bool)):
             return value
-
-        elif len(args) > 1:
-            return [self._unwrap_symbols_args(a, nested=True) if isinstance(a, Symbol) else a for a in args]
+        if isinstance(value, Symbol):
+            if not nested:
+                self._metadata       = value.metadata
+                self._static_context = value.static_context
+                self._kwargs         = value._kwargs
+            return value.value
+        if isinstance(value, list):
+            return [self._unwrap_symbols_args(v, nested=True) for v in value]
+        if isinstance(value, dict):
+            return {
+                self._unwrap_symbols_args(k, nested=True): self._unwrap_symbols_args(v, nested=True)
+                for k, v in value.items()
+            }
+        if isinstance(value, set):
+            return {self._unwrap_symbols_args(v, nested=True) for v in value}
+        if isinstance(value, tuple):
+            return tuple(self._unwrap_symbols_args(v, nested=True) for v in value)
+        return value
 
     def _construct_dependency_graph(self, *value):
         '''
@@ -316,16 +307,16 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         '''
         # for each value
         for v in value:
-            if isinstance(v, Symbol) and not v is self:
+            if isinstance(v, Symbol) and v is not self:
                 # new instance becomes child of previous instance
                 v._parent = self
                 # add new instance to children of previous instance
                 self._children.append(v)
 
-    def __new__(cls, *args,
-                mixin: Optional[bool] = None,
-                primitives: Optional[List[Type]] = None,
-                callables: Optional[List[Tuple[str, Callable]]] = None,
+    def __new__(cls, *_args,
+                mixin: bool | None = None,
+                primitives: list[type] | None = None,
+                callables: list[tuple[str, Callable]] | None = None,
                 semantic: bool = False,
                 **kwargs) -> "Symbol":
         '''
@@ -348,10 +339,11 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         if not isinstance(primitives, list):
             primitives = [primitives]
         # Initialize instance as a combination of Symbol and the mixin primitive types
+        target_cls = cls
         if use_mixin:
             # create a new cls type that inherits from Symbol and the mixin primitive types
-            cls       = SymbolMeta(cls.__name__, (cls,) + tuple(primitives), {})
-        obj = super().__new__(cls)
+            target_cls = SymbolMeta(cls.__name__, (cls, *tuple(primitives)), {})
+        obj = super().__new__(target_cls)
         # store to inherit when creating new instances
         obj._kwargs = {
             'mixin': use_mixin,
@@ -361,10 +353,9 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             **kwargs
         }
         # configure standard primitives
-        if use_mixin and standard_primitives:
+        if use_mixin and standard_primitives and semantic:
             # allow to iterate over iterables for neuro-symbolic values
-            if semantic:
-                obj.__semantic__ = True
+            obj.__semantic__ = True
         # If metatype has additional runtime primitives, add them to the instance
         if Symbol._metadata._primitives is not None:
             for prim_name in list(Symbol._metadata._primitives.keys()):
@@ -411,7 +402,8 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             value = self.value if self.value is not None else None
             if isinstance(value, Exception):
                 raise value
-            raise AttributeError(f'<class \'{self.__class__.__name__}\'> or nested value of {str(type(value))} have no attribute \'{name}\'')
+            msg = f"<class '{self.__class__.__name__}'> or nested value of {type(value)!s} have no attribute '{name}'"
+            raise AttributeError(msg)
         except AttributeError as ex:
             # if has attribute and is public function
             if hasattr(self.value, name) and not name.startswith('_'):
@@ -440,7 +432,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return memoryview(self.embedding)
 
     @staticmethod
-    def symbols(*values) -> List["Symbol"]:
+    def symbols(*values) -> list["Symbol"]:
         '''
         Create a list of Symbol instances from a list of values.
 
@@ -458,7 +450,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         It returns a tuple that contains:
         - A callable object that when called produces a new object (e.g., the class of the object)
         - A tuple of arguments for the callable object
-        - Optionally, the state which will be passed to the object’s `__setstate__` method
+        - Optionally, the state which will be passed to the object's `__setstate__` method
 
         Returns:
             tuple: A tuple containing the callable object, the arguments for the callable object, and the state of the object.
@@ -476,7 +468,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         # The __reduce__ method returns:
         # - A callable object that when called produces a new object (e.g., the class of the object)
         # - A tuple of arguments for the callable object
-        # - Optionally, the state which will be passed to the object’s `__setstate__` method
+        # - Optionally, the state which will be passed to the object's `__setstate__` method
         return (self._reconstruct_class, (base_cls, self._mixin, primitives), state)
 
     def __reduce_ex__(self, protocol):
@@ -500,12 +492,11 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             # Convert primitive info tuples back to types
             primitives     = [primitive for primitive, name in primitives_info]
             # Create new cls with UnifiedMeta metaclass
-            cls            = SymbolMeta(base_cls.__name__, (base_cls,) + tuple(primitives), {})
-            obj            = cls()
-            return obj
+            cls = SymbolMeta(base_cls.__name__, (base_cls, *tuple(primitives)), {})
+            return cls()
         return base_cls()
 
-    def __getstate__(self) -> Dict[str, Any]:
+    def __getstate__(self) -> dict[str, Any]:
         '''
         Get the state of the symbol for serialization.
 
@@ -532,7 +523,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         self._parent     = None
         self._children   = []
 
-    def json(self) -> Dict[str, Any]:
+    def json(self) -> dict[str, Any]:
         '''
         Get the json-serializable dictionary representation of the Symbol instance.
 
@@ -568,8 +559,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             return value
         # inherit kwargs for new symbol instance
         kwargs = {**self._kwargs, **kwargs}
-        sym    = type_(value, **kwargs)
-        return sym
+        return type_(value, **kwargs)
 
     def _to_type(self, value: Any, **kwargs) -> "Symbol":
         '''
@@ -586,8 +576,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             return value
         # inherit kwargs for new symbol instance
         kwargs = {**self._kwargs, **kwargs}
-        sym    = type_(value, **kwargs)
-        return sym
+        return type_(value, **kwargs)
 
     @property
     def _symbol_type(self) -> "Symbol":
@@ -609,7 +598,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return str(self.value).__hash__()
 
     @property
-    def metadata(self) -> Dict[str, Any]:
+    def metadata(self) -> dict[str, Any]:
         '''
         Get the metadata associated with the symbol.
 
@@ -692,7 +681,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return root
 
     @property
-    def nodes(self) -> List["Symbol"]:
+    def nodes(self) -> list["Symbol"]:
         '''
         Get all nodes descending recursively from the symbol.
 
@@ -709,7 +698,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return nodes
 
     @property
-    def edges(self) -> List[tuple]:
+    def edges(self) -> list[tuple]:
         '''
         Get all edges descending recursively from the symbol.
 
@@ -726,7 +715,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return edges
 
     @property
-    def graph(self) -> (List["Symbol"], List[tuple]):
+    def graph(self) -> (list["Symbol"], list[tuple]):
         '''
         Get the graph representation of the symbol.
 
@@ -736,7 +725,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return self.nodes, self.edges
 
     @property
-    def linker(self) -> List["Symbol"]:
+    def linker(self) -> list["Symbol"]:
         '''
         Returns the link object metadata by descending recursively from the root of the symbol to the root_link object.
 
@@ -756,7 +745,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         return self._parent
 
     @property
-    def children(self) -> List["Symbol"]:
+    def children(self) -> list["Symbol"]:
         '''
         Get the children of the symbol.
 
@@ -765,7 +754,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         '''
         return self._children
 
-    def _root_link(self, sym: Any, **kwargs) -> Any:
+    def _root_link(self, sym: Any, **_kwargs) -> Any:
         '''
         Call the forward method and assign the result to the graph value attribute.
 
@@ -777,7 +766,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             Any: The result of the forward method.
         '''
         # transport results to the root node for global access
-        if not self is self.root and not self.metadata.detach:
+        if self is not self.root and not self.metadata.detach:
             ref = self.root.metadata
             if ref.root_link is None:
                 ref.root_link = Linker()
@@ -788,12 +777,12 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
                 prev = list(ref.root_link.results.values())[-1] # get previous result
             # create new symbol to avoid circular references
             res_ = Symbol(sym)
-            if prev is not None and not prev is res_.root:
+            if prev is not None and prev is not res_.root:
                 prev.children.append(res_.root)
                 res_.root._parent = prev
             ref.root_link.results[self.__repr__()] = res_
 
-    def adapt(self, context: str, types: List[Type] = []) -> None:
+    def adapt(self, context: str, types: list[type] | None = None) -> None:
         '''
         Update the dynamic context with a given runtime context.
 
@@ -802,34 +791,38 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
             type (Type): The type used to update the dynamic context
 
         '''
+        if types is None:
+            types = []
         if not isinstance(types, list):
             types = [types]
         if len(types) == 0:
             types = [type(self)]
 
         for type_ in types:
-            type_ = str(type_)
-            if type_ not in Symbol._dynamic_context:
-                Symbol._dynamic_context[type_] = []
+            type_key = str(type_)
+            if type_key not in Symbol._dynamic_context:
+                Symbol._dynamic_context[type_key] = []
 
-            Symbol._dynamic_context[type_].append(str(context))
+            Symbol._dynamic_context[type_key].append(str(context))
 
-    def clear(self, types: List[Type] = []) -> None:
+    def clear(self, types: list[type] | None = None) -> None:
         '''
         Clear the dynamic context associated with this symbol type.
         '''
+        if types is None:
+            types = []
         if not isinstance(types, list):
             types = [types]
         if len(types) == 0:
             types = [type(self)]
 
         for type_ in types:
-            type_ = str(type_)
-            if type_ not in Symbol._dynamic_context:
-                Symbol._dynamic_context[type_] = []
+            type_key = str(type_)
+            if type_key not in Symbol._dynamic_context:
+                Symbol._dynamic_context[type_key] = []
                 return
 
-            Symbol._dynamic_context[type_].clear()
+            Symbol._dynamic_context[type_key].clear()
 
     def __len__(self) -> int:
         '''
@@ -859,14 +852,13 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         '''
         if self.value is None:
             return ''
-        elif isinstance(self.value, list) or isinstance(self.value, np.ndarray) or isinstance(self.value, tuple):
+        if isinstance(self.value, (list, np.ndarray, tuple)):
             return str([str(v) for v in self.value])
-        elif isinstance(self.value, dict):
+        if isinstance(self.value, dict):
             return str({k: str(v) for k, v in self.value.items()})
-        elif isinstance(self.value, set):
+        if isinstance(self.value, set):
             return str({str(v) for v in self.value})
-        else:
-            return str(self.value)
+        return str(self.value)
 
     def __repr__(self, simplified: bool = False) -> str:
         '''
@@ -901,7 +893,7 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
         Returns:
             Iterator: An iterator for the Symbol's value.
         '''
-        if isinstance(self.value, list) or isinstance(self.value, tuple) or isinstance(self.value, np.ndarray):
+        if isinstance(self.value, (list, tuple, np.ndarray)):
             return iter(self.value)
 
         return self.list('item').value.__iter__()
@@ -960,8 +952,8 @@ class Symbol(Generic[T], metaclass=SymbolMeta):
 # TODO: Workaround for Python bug to enable runtime assignment of lambda function to new Symbol objects.
 # Currently creating multiple lambda functions within class __new__ definition only links last lambda function to all new Symbol attribute assignments.
 # Need to contact Python developers to fix this bug.
-class Call(object):
-    def __new__(self, name, callable: Callable) -> Any:
+class Call:
+    def __new__(cls, name, callable: Callable) -> Any:
         '''
         Prepare a callable for use in a Symbol instance.
 
@@ -976,8 +968,8 @@ class Call(object):
         return (name, _func)
 
 
-class GlobalSymbolPrimitive(object):
-    def __new__(self, name, callable: Callable) -> Any:
+class GlobalSymbolPrimitive:
+    def __new__(cls, name, callable: Callable) -> Any:
         '''
         Prepare a callable for use in a Symbol instance.
 
@@ -1060,7 +1052,7 @@ class Expression(Symbol):
         return json.dumps(self, cls=ExpressionEncoder)
 
     @property
-    def sym_return_type(self) -> Type:
+    def sym_return_type(self) -> type:
         '''
         Returns the casting type of this expression.
 
@@ -1070,7 +1062,7 @@ class Expression(Symbol):
         return self._sym_return_type
 
     @sym_return_type.setter
-    def sym_return_type(self, type: Type) -> None:
+    def sym_return_type(self, type: type) -> None:
         '''
         Sets the casting type of this expression.
 
@@ -1090,10 +1082,10 @@ class Expression(Symbol):
         Returns:
             Symbol: The evaluated result of the implemented forward method.
         '''
-        raise NotImplementedError()
+        raise NotImplementedError
 
     @staticmethod
-    def command(engines: List[str] = ['all'], **kwargs) -> 'Symbol':
+    def command(engines: list[str] | None = None, **kwargs) -> 'Symbol':
         '''
         Execute command(s) on engines.
 
@@ -1104,13 +1096,16 @@ class Expression(Symbol):
         Returns:
             Symbol: An Expression object representing the command execution result.
         '''
+        if engines is None:
+            engines = ['all']
+
         @core.command(engines=engines, **kwargs)
         def _func(_):
             pass
         return Expression(_func(Expression()))
 
     @staticmethod
-    def register(engines: Dict[str, Any], **kwargs) -> 'Symbol':
+    def register(engines: dict[str, Any], **kwargs) -> 'Symbol':
         '''
         Configure multiple engines.
 
@@ -1154,7 +1149,7 @@ class Expression(Symbol):
 
 
 class Result(Expression):
-    def __init__(self, value = None, *args, **kwargs):
+    def __init__(self, value = None, *_args, **kwargs):
         '''
         Create a Result object that stores the results operations, including the raw result, value and metadata, if any.
 
@@ -1169,7 +1164,7 @@ class Result(Expression):
         try:
             # try to make the values easily accessible
             self.raw = Box(value)
-        except:
+        except Exception:
             # otherwise, store the unprocessed view
             self.raw = value