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

symai/ops/primitives.py

@@ -1,19 +1,18 @@
 import ast
 import json
-import os
+import numbers
 import pickle
 import uuid
-from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterable, List,
-                    Optional, Tuple, Type, Union)
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, Union
 
 import numpy as np
 import torch
-from pydantic import ValidationError
 
 from .. import core, core_ext
-from ..models import CustomConstraint, LengthConstraint, LLMDataModel
 from ..prompts import Prompt
-from ..utils import CustomUserWarning
+from ..utils import UserMessage
 from .measures import calculate_frechet_distance, calculate_mmd
 
 if TYPE_CHECKING:
@@ -41,20 +40,21 @@ class Primitive:
 
 
 class OperatorPrimitives(Primitive):
-    def __try_type_specific_func(self, other, func, op: str = None):
+    __hash__ = None
+
+    def __try_type_specific_func(self, other, func, op: str | None = None):
         if not isinstance(other, self._symbol_type):
             other = self._to_type(other)
         # None shortcut
-        if not self.__disable_none_shortcut__:
-            if  self.value is None or other.value is None:
-                CustomUserWarning(f"unsupported {self._symbol_type.__class__} value operand type(s) for {op}: '{type(self.value)}' and '{type(other.value)}'", raise_with=TypeError)
+        if not self.__disable_none_shortcut__ and (self.value is None or other.value is None):
+            UserMessage(f"unsupported {self._symbol_type.__class__} value operand type(s) for {op}: '{type(self.value)}' and '{type(other.value)}'", raise_with=TypeError)
         # try type specific function
         try:
             # try type specific function
             value = func(self, other)
             if value is NotImplemented:
                 operation = '' if op is None else op
-                CustomUserWarning(f"unsupported {self._symbol_type.__class__} value operand type(s) for {operation}: '{type(self.value)}' and '{type(other.value)}'", raise_with=TypeError)
+                UserMessage(f"unsupported {self._symbol_type.__class__} value operand type(s) for {operation}: '{type(self.value)}' and '{type(other.value)}'", raise_with=TypeError)
             return value
         except Exception as ex:
             self._metadata._error = ex
@@ -66,7 +66,7 @@ class OperatorPrimitives(Primitive):
         This function raises an error if the neuro-symbolic engine is disabled.
         '''
         if self.__disable_nesy_engine__:
-            CustomUserWarning(f"unsupported {self.__class__} value operand type(s) for {func.__name__}: '{type(self.value)}'", raise_with=TypeError)
+            UserMessage(f"unsupported {self.__class__} value operand type(s) for {func.__name__}: '{type(self.value)}'", raise_with=TypeError)
 
     def __bool__(self) -> bool:
         '''
@@ -80,7 +80,7 @@ class OperatorPrimitives(Primitive):
         if isinstance(self.value, bool):
             val = self.value
         elif self.value is not None:
-            val = True if self.value else False
+            val = bool(self.value)
 
         return val
 
@@ -680,8 +680,8 @@ class OperatorPrimitives(Primitive):
         Returns:
             Symbol: A new symbol with the result of the OR operation.
         '''
-        # exclude the evaluation for the Aggregator class
-        from ..collect.stats import Aggregator
+        # Exclude the evaluation for the Aggregator class; keep import local to avoid ops.primitives <-> collect.stats cycle.
+        from ..collect.stats import Aggregator # noqa
         if isinstance(other, Aggregator):
             return NotImplemented
 
@@ -709,8 +709,8 @@ class OperatorPrimitives(Primitive):
         Returns:
             Symbol: A new Symbol object with the concatenated value.
         '''
-        # exclude the evaluation for the Aggregator class
-        from ..collect.stats import Aggregator
+        # Exclude the evaluation for the Aggregator class; keep import local to avoid ops.primitives <-> collect.stats cycle.
+        from ..collect.stats import Aggregator # noqa
         if isinstance(other, Aggregator):
             return NotImplemented
 
@@ -739,8 +739,8 @@ class OperatorPrimitives(Primitive):
         Returns:
             Symbol: A new Symbol object with the concatenated value.
         '''
-        # exclude the evaluation for the Aggregator class
-        from ..collect.stats import Aggregator
+        # Exclude the evaluation for the Aggregator class; keep import local to avoid ops.primitives <-> collect.stats cycle.
+        from ..collect.stats import Aggregator # noqa
         if isinstance(other, Aggregator):
             return NotImplemented
 
@@ -848,11 +848,12 @@ class OperatorPrimitives(Primitive):
         Returns:
             Symbol: A new Symbol object with the concatenated value.
         '''
-        if isinstance(self.value, str) and isinstance(other, str) or \
-            isinstance(self.value, str) and isinstance(other, self._symbol_type) and isinstance(other.value, str):
+        if (isinstance(self.value, str) and isinstance(other, str)) or \
+            (isinstance(self.value, str) and isinstance(other, self._symbol_type) and isinstance(other.value, str)):
             other = self._to_type(other)
             return self._to_type(f'{self.value}{other.value}')
-        CustomUserWarning(f'This method is only supported for string concatenation! Got {type(self.value)} and {type(other)} instead.', raise_with=TypeError)
+        UserMessage(f'This method is only supported for string concatenation! Got {type(self.value)} and {type(other)} instead.', raise_with=TypeError)
+        return None
 
     def __rmatmul__(self, other: Any) -> 'Symbol':
         '''
@@ -917,7 +918,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
 
     def __itruediv__(self, other: Any) -> 'Symbol':
@@ -936,7 +938,8 @@ class OperatorPrimitives(Primitive):
             self._value = result
             return self
 
-        CustomUserWarning('Division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
 
     def __floordiv__(self, other: Any) -> 'Symbol':
@@ -954,7 +957,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __rfloordiv__(self, other: Any) -> 'Symbol':
         '''
@@ -971,7 +975,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __ifloordiv__(self, other: Any) -> 'Symbol':
         '''
@@ -989,7 +994,8 @@ class OperatorPrimitives(Primitive):
             self._value = result
             return self
 
-        CustomUserWarning('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Floor division operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __pow__(self, other: Any) -> 'Symbol':
         '''
@@ -1006,7 +1012,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
 
     def __rpow__(self, other: Any) -> 'Symbol':
@@ -1024,7 +1031,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __ipow__(self, other: Any) -> 'Symbol':
         '''
@@ -1042,7 +1050,8 @@ class OperatorPrimitives(Primitive):
             self._value = result
             return self
 
-        CustomUserWarning('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Power operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __mod__(self, other: Any) -> 'Symbol':
         '''
@@ -1059,7 +1068,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Modulo operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Modulo operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __rmod__(self, other: Any) -> 'Symbol':
         '''
@@ -1076,7 +1086,9 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        raise NotImplementedError('Modulo operation not supported! Might change in the future.') from self._metadata._error
+        msg = 'Modulo operation not supported! Might change in the future.'
+        UserMessage(msg)
+        raise NotImplementedError(msg) from self._metadata._error
 
     def __imod__(self, other: Any) -> 'Symbol':
         '''
@@ -1094,7 +1106,8 @@ class OperatorPrimitives(Primitive):
             self._value = result
             return self
 
-        CustomUserWarning('Modulo operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Modulo operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __mul__(self, other: Any) -> 'Symbol':
         '''
@@ -1111,7 +1124,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __rmul__(self, other: Any) -> 'Symbol':
         '''
@@ -1128,7 +1142,8 @@ class OperatorPrimitives(Primitive):
         if result is not None:
             return self._to_type(result)
 
-        CustomUserWarning('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
     def __imul__(self, other: Any) -> 'Symbol':
         '''
@@ -1146,7 +1161,8 @@ class OperatorPrimitives(Primitive):
             self._value = result
             return self
 
-        CustomUserWarning('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        UserMessage('Multiply operation not supported semantically! Might change in the future.', raise_with=NotImplementedError)
+        return None
 
 
 class CastingPrimitives(Primitive):
@@ -1165,14 +1181,14 @@ class CastingPrimitives(Primitive):
     @property
     def sem(self) -> "Symbol":
         """
-        Return a semantic view of this Symbol.

+        Return a semantic view of this Symbol.

         (Useful after calling `.syn` in a chain.)
         """
         if getattr(self, "__semantic__", False):
             return self
         return self._to_type(self.value, semantic=True)
 
-    def cast(self, as_type: Type) -> Any:
+    def cast(self, as_type: type) -> Any:
         '''
         Cast the Symbol's value to a specific type.
 
@@ -1184,7 +1200,7 @@ class CastingPrimitives(Primitive):
         '''
         return as_type(self.value)
 
-    def to(self, as_type: Type) -> Any:
+    def to(self, as_type: type) -> Any:
         '''
         Cast the Symbol's value to a specific type.
 
@@ -1250,7 +1266,7 @@ class IterationPrimitives(Primitive):
     This mixin contains functions that perform iteration operations on symbols or symbol values.
     The functions in this mixin are bound to the 'neurosymbolic' engine for evaluation.
     '''
-    def __getitem__(self, key: Union[str, int, slice]) -> 'Symbol':
+    def __getitem__(self, key: str | int | slice) -> 'Symbol':
         '''
         Get the item of the Symbol value with the specified key or index.
         If the Symbol value is a list, tuple, or numpy array, the key can be an integer or slice.
@@ -1270,7 +1286,7 @@ class IterationPrimitives(Primitive):
             try:
                 return self.value[key]
             except Exception:
-                CustomUserWarning(f'Key {key} not found in {self.value}', raise_with=Exception)
+                UserMessage(f'Key {key} not found in {self.value}', raise_with=Exception)
 
         @core.getitem()
         def _func(_, index: str):
@@ -1278,7 +1294,7 @@ class IterationPrimitives(Primitive):
 
         return self._to_type(_func(self, key))
 
-    def __setitem__(self, key: Union[str, int, slice], value: Any) -> None:
+    def __setitem__(self, key: str | int | slice, value: Any) -> None:
         '''
         Set the item of the Symbol value with the specified key or index to the given value.
         If the Symbol value is a list, the key can be an integer or slice.
@@ -1292,17 +1308,18 @@ class IterationPrimitives(Primitive):
         Raises:
             KeyError: If the key or index is not found in the Symbol value.
         '''
-        from ..post_processors import ASTPostProcessor
+        # Local import avoids ops.primitives -> post_processors -> symbol -> ops circular load.
+        from ..post_processors import ASTPostProcessor # noqa
 
         if not isinstance(self.value, (str, dict, list)):
-            CustomUserWarning(f'Setting item is not supported for {type(self.value)}. Supported types are str, dict, and list.', raise_with=TypeError)
+            UserMessage(f'Setting item is not supported for {type(self.value)}. Supported types are str, dict, and list.', raise_with=TypeError)
 
         if not self.__semantic__:
             try:
                 self.value[key] = value
                 return
             except Exception:
-                CustomUserWarning(f'Key {key} not found in {self.value}', raise_with=Exception)
+                UserMessage(f'Key {key} not found in {self.value}', raise_with=Exception)
 
         @core.setitem()
         def _func(_, index: str, value: str):
@@ -1314,7 +1331,7 @@ class IterationPrimitives(Primitive):
         except Exception:
             self._value = result # It was a string, or something failed (because } wasn't close, etc)
 
-    def __delitem__(self, key: Union[str, int]) -> None:
+    def __delitem__(self, key: str | int) -> None:
         '''
         Delete the item of the Symbol value with the specified key or index.
         If the Symbol value is a dictionary, the key can be a string or an integer.
@@ -1326,17 +1343,18 @@ class IterationPrimitives(Primitive):
         Raises:
             KeyError: If the key or index is not found in the Symbol value.
         '''
-        from ..post_processors import ASTPostProcessor
+        # Local import avoids ops.primitives -> post_processors -> symbol -> ops circular load.
+        from ..post_processors import ASTPostProcessor # noqa
 
         if not isinstance(self.value, (str, dict, list)):
-            CustomUserWarning(f'Setting item is not supported for {type(self.value)}. Supported types are str, dict, and list.', raise_with=TypeError)
+            UserMessage(f'Setting item is not supported for {type(self.value)}. Supported types are str, dict, and list.', raise_with=TypeError)
 
         if not self.__semantic__:
             try:
                 del self.value[key]
                 return
             except Exception:
-                CustomUserWarning(f'Key {key} not found in {self.value}', raise_with=Exception)
+                UserMessage(f'Key {key} not found in {self.value}', raise_with=Exception)
 
         @core.delitem()
         def _func(_, index: str):
@@ -1427,7 +1445,7 @@ class StringHelperPrimitives(Primitive):
     '''
     This mixin contains functions that provide additional help for symbols or their values.
     '''
-    def split(self, delimiter: str, **kwargs) -> 'Symbol':
+    def split(self, delimiter: str, **_kwargs) -> 'Symbol':
         '''
         Splits the symbol value by a specified delimiter.
         Uses the core.split decorator to create a _func method that splits the symbol value by the specified delimiter.
@@ -1442,7 +1460,7 @@ class StringHelperPrimitives(Primitive):
         assert isinstance(self.value, str), f'self.value must be a string, got {type(self.value)}'
         return self._to_type([*self.value.split(delimiter)])
 
-    def join(self, delimiter: str = ' ', **kwargs) -> 'Symbol':
+    def join(self, delimiter: str = ' ', **_kwargs) -> 'Symbol':
         '''
         Joins the symbol value with a specified delimiter.
 
@@ -1456,7 +1474,7 @@ class StringHelperPrimitives(Primitive):
         assert isinstance(self.value, Iterable), f'value must be an iterable, got {type(self.value)}'
         return self._to_type(delimiter.join(self.value))
 
-    def startswith(self, prefix: str, **kwargs) -> bool:
+    def startswith(self, prefix: str, **_kwargs) -> bool:
         '''
         Checks if the symbol value starts with a specified prefix.
         Uses the core.startswith decorator to create a _func method that checks if the symbol value starts with the specified prefix.
@@ -1479,7 +1497,7 @@ class StringHelperPrimitives(Primitive):
 
         return _func(self, prefix)
 
-    def endswith(self, suffix: str, **kwargs) -> bool:
+    def endswith(self, suffix: str, **_kwargs) -> bool:
         '''
         Checks if the symbol value ends with a specified suffix.
         Uses the core.endswith decorator to create a _func method that checks if the symbol value ends with the specified suffix.
@@ -1574,7 +1592,7 @@ class ExpressionHandlingPrimitives(Primitive):
         if not hasattr(self, '_accumulated_results'):
             self._accumulated_results = []
 
-    def get_results(self) -> List['Symbol']:
+    def get_results(self) -> list['Symbol']:
         '''
         Retrieves accumulated results from previous interpretations.
 
@@ -1589,7 +1607,7 @@ class ExpressionHandlingPrimitives(Primitive):
         self.init_results()
         self._accumulated_results = []
 
-    def interpret(self, prompt: Optional[str] = "Evaluate the symbolic expressions and return only the result:\n", accumulate: bool = False, **kwargs) -> 'Symbol':
+    def interpret(self, prompt: str | None = "Evaluate the symbolic expressions and return only the result:\n", accumulate: bool = False, **kwargs) -> 'Symbol':
         '''
         Evaluates simple symbolic expressions.
         Uses the core.expression decorator to create a _func method that evaluates the given expression.
@@ -1639,7 +1657,7 @@ class DataHandlingPrimitives(Primitive):
 
         return self._to_type(_func(self))
 
-    def summarize(self, context: Optional[str] = None, **kwargs) -> 'Symbol':
+    def summarize(self, context: str | None = None, **kwargs) -> 'Symbol':
         '''
         Summarizes the symbol value.
         Uses the core.summarize decorator with an optional context to create a _func method that summarizes the symbol value.
@@ -1670,7 +1688,7 @@ class DataHandlingPrimitives(Primitive):
 
         return self._to_type(_func(self))
 
-    def filter(self, criteria: str, include: Optional[bool] = False, **kwargs) -> 'Symbol':
+    def filter(self, criteria: str, include: bool | None = False, **kwargs) -> 'Symbol':
         '''
         Filters the symbol value based on a specified criteria.
         Uses the core.filtering decorator with the provided criteria and include flag to create a _func method to filter the symbol value.
@@ -1707,7 +1725,7 @@ class DataHandlingPrimitives(Primitive):
         try:
             iter(self.value)
         except TypeError:
-            CustomUserWarning('Map can only be applied to iterable objects', raise_with=AssertionError)
+            UserMessage('Map can only be applied to iterable objects', raise_with=AssertionError)
 
         @core.map(instruction=instruction, **kwargs)
         def _func(_):
@@ -1807,7 +1825,7 @@ class UniquenessPrimitives(Primitive):
     This mixin includes functions that work with unique aspects of symbol values, like extracting unique information or composing new unique symbols.
     Future functionalities might include finding duplicate information, defining levels of uniqueness, etc.
     '''
-    def unique(self, keys: Optional[List[str]] = [], **kwargs) -> 'Symbol':
+    def unique(self, keys: list[str] | None = None, **kwargs) -> 'Symbol':
         '''
         Extracts unique information from the symbol value, using provided keys.
         Uses the core.unique decorator with a list of keys to create a _func method that extracts unique data from the symbol value.
@@ -1818,6 +1836,8 @@ class UniquenessPrimitives(Primitive):
         Returns:
             Symbol: A new symbol with the unique information.
         '''
+        if keys is None:
+            keys = []
         @core.unique(keys=keys, **kwargs)
         def _func(_) -> str:
             pass
@@ -1844,7 +1864,7 @@ class PatternMatchingPrimitives(Primitive):
     This mixin houses functions that deal with ranking symbols, extracting details based on patterns, and correcting symbols.
     It will house future functionalities that involve sorting, complex pattern detections, advanced correction techniques etc.
     '''
-    def rank(self, measure: Optional[str] = 'alphanumeric', order: Optional[str] = 'desc', **kwargs) -> 'Symbol':
+    def rank(self, measure: str | None = 'alphanumeric', order: str | None = 'desc', **kwargs) -> 'Symbol':
         '''
         Ranks the symbol value based on a measure and a sort order.
         Uses the core.rank decorator with the specified measure and order to create a _func method that ranks the symbol value.
@@ -1899,7 +1919,7 @@ class PatternMatchingPrimitives(Primitive):
 
         return self._to_type(_func(self))
 
-    def translate(self, language: Optional[str] = 'English', **kwargs) -> 'Symbol':
+    def translate(self, language: str | None = 'English', **kwargs) -> 'Symbol':
         '''
         Translates the symbol value to the specified language.
         Uses the @core.translate decorator to translate the symbol's value to the specified language.
@@ -1917,7 +1937,7 @@ class PatternMatchingPrimitives(Primitive):
 
         return self._to_type(_func(self))
 
-    def choice(self, cases: List[str], default: str, **kwargs) -> 'Symbol':
+    def choice(self, cases: list[str], default: str, **kwargs) -> 'Symbol':
         '''
         Chooses one of the cases based on the symbol value.
         Uses the @core.case decorator, selects one of the cases based on the symbol's value.
@@ -1942,7 +1962,7 @@ class QueryHandlingPrimitives(Primitive):
     This mixin helps in transforming, preparing, and executing queries, and it is designed to be extendable as new ways of handling queries are developed.
     Future methods could potentially include query optimization, enhanced query formatting, multi-level query execution, query error handling, etc.
     '''
-    def query(self, context: str, prompt: Optional[str] = None, examples: Optional[List[Prompt]] = None, **kwargs) -> 'Symbol':
+    def query(self, context: str, prompt: str | None = None, examples: list[Prompt] | None = None, **kwargs) -> 'Symbol':
         '''
         Queries the symbol value based on a specified context.
         Uses the @core.query decorator, queries based on the context, prompt, and examples.
@@ -2004,7 +2024,7 @@ class ExecutionControlPrimitives(Primitive):
     This mixin represents the core methods for dealing with symbol execution.
     Possible future methods could potentially include async execution, pipeline chaining, execution profiling, improved error handling, version management, embedding more complex execution control structures etc.
     '''
-    def analyze(self, exception: Exception, query: Optional[str] = '', **kwargs) -> 'Symbol':
+    def analyze(self, exception: Exception, query: str | None = '', **kwargs) -> 'Symbol':
         '''Uses the @core.analyze decorator, analyzes an exception and returns a symbol.
 
         Args:
@@ -2120,7 +2140,7 @@ class ExecutionControlPrimitives(Primitive):
 
         return self._to_type(_func(self))
 
-    def stream(self, expr: 'Expression', token_ratio: Optional[float] = 0.6, **kwargs) -> 'Symbol':
+    def stream(self, expr: 'Expression', token_ratio: float | None = 0.6, **kwargs) -> 'Symbol':
         '''
         Streams the Symbol's value through an Expression object.
         This method divides the Symbol's value into chunks and processes each chunk through the given Expression object.
@@ -2156,7 +2176,7 @@ class ExecutionControlPrimitives(Primitive):
         else:
             yield expr(self, **kwargs)
 
-    def ftry(self, expr: 'Expression', retries: Optional[int] = 1, **kwargs) -> 'Symbol':
+    def ftry(self, expr: 'Expression', retries: int | None = 1, **kwargs) -> 'Symbol':
         # TODO: find a way to pass on the constraints and behavior from the self.expr to the corrected code
         '''
         Tries to evaluate a Symbol using a given Expression.
@@ -2198,33 +2218,32 @@ class ExecutionControlPrimitives(Primitive):
                 retry_cnt += 1
                 if retry_cnt > retries:
                     raise e
+                # analyze the error
+                payload = f'[ORIGINAL_USER_PROMPT]\n{prompt["prompt_instruction"]}\n\n' if 'prompt_instruction' in prompt else ''
+                payload = payload + f'[ORIGINAL_USER_DATA]\n{code}\n\n[ORIGINAL_GENERATED_OUTPUT]\n{prompt["out_msg"]}'
+                probe   = sym.analyze(query="What is the issue in this expression?", payload=payload, exception=e)
+                # attempt to correct the error
+                payload = f'[ORIGINAL_USER_PROMPT]\n{prompt["prompt_instruction"]}\n\n' if 'prompt_instruction' in prompt else ''
+                payload = payload + f'[ANALYSIS]\n{probe}\n\n'
+                context = f'Try to correct the error of the original user request based on the analysis above: \n [GENERATED_OUTPUT]\n{prompt["out_msg"]}\n\n'
+                constraints = expr.constraints if hasattr(expr, 'constraints') else []
+
+                if hasattr(expr, 'post_processor'):
+                    post_processor = expr.post_processor
+                    sym = code.correct(
+                        context=context,
+                        exception=e,
+                        payload=payload,
+                        constraints=constraints,
+                        post_processor=post_processor
+                    )
                 else:
-                    # analyze the error
-                    payload = f'[ORIGINAL_USER_PROMPT]\n{prompt["prompt_instruction"]}\n\n' if 'prompt_instruction' in prompt else ''
-                    payload = payload + f'[ORIGINAL_USER_DATA]\n{code}\n\n[ORIGINAL_GENERATED_OUTPUT]\n{prompt["out_msg"]}'
-                    probe   = sym.analyze(query="What is the issue in this expression?", payload=payload, exception=e)
-                    # attempt to correct the error
-                    payload = f'[ORIGINAL_USER_PROMPT]\n{prompt["prompt_instruction"]}\n\n' if 'prompt_instruction' in prompt else ''
-                    payload = payload + f'[ANALYSIS]\n{probe}\n\n'
-                    context = f'Try to correct the error of the original user request based on the analysis above: \n [GENERATED_OUTPUT]\n{prompt["out_msg"]}\n\n'
-                    constraints = expr.constraints if hasattr(expr, 'constraints') else []
-
-                    if hasattr(expr, 'post_processor'):
-                        post_processor = expr.post_processor
-                        sym = code.correct(
-                            context=context,
-                            exception=e,
-                            payload=payload,
-                            constraints=constraints,
-                            post_processor=post_processor
-                        )
-                    else:
-                        sym = code.correct(
-                            context=context,
-                            exception=e,
-                            payload=payload,
-                            constraints=constraints
-                        )
+                    sym = code.correct(
+                        context=context,
+                        exception=e,
+                        payload=payload,
+                        constraints=constraints
+                    )
 
 
 class DictHandlingPrimitives(Primitive):
@@ -2257,7 +2276,7 @@ class TemplateStylingPrimitives(Primitive):
     This mixin includes functionalities for stylizing symbols and applying templates.
     Future functionalities might include a variety of new stylizing methods, application of more complex templates, etc.
     '''
-    def template(that, template: str, placeholder: Optional[str] = '{{placeholder}}', **kwargs) -> 'Symbol':
+    def template(that, template: str, placeholder: str | None = '{{placeholder}}', **_kwargs) -> 'Symbol':
         '''
         Applies a template to the Symbol.
         This method uses the @core.template decorator to apply the given template and placeholder to the Symbol.
@@ -2277,7 +2296,7 @@ class TemplateStylingPrimitives(Primitive):
 
         return _func(that)
 
-    def style(self, description: str, libraries: Optional[List] = [], **kwargs) -> 'Symbol':
+    def style(self, description: str, libraries: list | None = None, **kwargs) -> 'Symbol':
         '''
         Applies a style to the Symbol.
         This method uses the @core.style decorator to apply the given style description, libraries, and placeholder to the Symbol.
@@ -2291,6 +2310,8 @@ class TemplateStylingPrimitives(Primitive):
         Returns:
             Symbol: A Symbol object with the style applied.
         '''
+        if libraries is None:
+            libraries = []
         @core.style(description=description, libraries=libraries, **kwargs)
         def _func(_):
             pass
@@ -2362,16 +2383,17 @@ class EmbeddingPrimitives(Primitive):
         '''
         # if the embedding is not yet computed, compute it
         if self._metadata.embedding is None:
-            if ((isinstance(self.value, list) or isinstance(self.value, tuple)) and all([type(x) == int or type(x) == float or type(x) == bool for x in self.value])) \
+            if (isinstance(self.value, (list, tuple)) and all(isinstance(x, (int, float, bool)) for x in self.value)) \
                 or isinstance(self.value, np.ndarray):
-                if isinstance(self.value, list) or isinstance(self.value, tuple):
+                if isinstance(self.value, (list, tuple)):
                     assert len(self.value) > 0, 'Cannot compute embedding of empty list'
-                    if isinstance(self.value[0], Symbol):
+                    symbol_type = self._symbol_type
+                    if isinstance(self.value[0], symbol_type):
                         # convert each element to numpy array
                         self._metadata.embedding = np.asarray([x.embedding for x in self.value])
                     elif isinstance(self.value[0], str):
                         # embed each string
-                        self._metadata.embedding = np.asarray([Symbol(x).embedding for x in self.value])
+                        self._metadata.embedding = np.asarray([symbol_type(x).embedding for x in self.value])
                     else:
                         # convert to numpy array
                         self._metadata.embedding = np.asarray(self.value)
@@ -2390,23 +2412,195 @@ class EmbeddingPrimitives(Primitive):
 
     def _ensure_numpy_format(self, x, cast=False):
         # if it is a Symbol, get its value
-        if not isinstance(x, np.ndarray) or not isinstance(x, torch.Tensor) or not isinstance(x, list):
+        if not isinstance(x, (np.ndarray, torch.Tensor, list)):
             if not isinstance(x, self._symbol_type): #@NOTE: enforce Symbol to avoid circular import
                 if not cast:
-                    raise TypeError(f'Cannot compute similarity with type {type(x)}')
+                    msg = f'Cannot compute similarity with type {type(x)}'
+                    UserMessage(msg)
+                    raise TypeError(msg)
                 x = self._symbol_type(x)
             # evaluate the Symbol as an embedding
             x = x.embedding
         # if it is a list, convert it to numpy
-        if isinstance(x, list) or isinstance(x, tuple):
+        if isinstance(x, (list, tuple)):
             assert len(x) > 0, 'Cannot compute similarity with empty list'
             x = np.asarray(x)
         # if it is a tensor, convert it to numpy
         elif isinstance(x, torch.Tensor):
             x = x.detach().cpu().numpy()
-        return x.squeeze()[:, None]
+        else:
+            x = np.asarray(x)
 
-    def similarity(self, other: Union['Symbol', list, np.ndarray, torch.Tensor], metric: Union['cosine', 'angular-cosine', 'product', 'manhattan', 'euclidean', 'minkowski', 'jaccard'] = 'cosine', eps: float = 1e-8, normalize: Optional[Callable] = None, **kwargs) -> float:
+        x = np.squeeze(x)
+        if x.ndim == 0:
+            x = x[None]
+
+        return x[:, None]
+
+    def _prepare_embedding_operand(self, operand):
+        if isinstance(operand, (list, tuple)):
+            if self._is_numeric_sequence(operand):
+                return self._ensure_numpy_format(operand, cast=True)
+            formatted = [
+                self._ensure_numpy_format(item, cast=True) for item in operand
+            ]
+            return np.concatenate(formatted, axis=1)
+        return self._ensure_numpy_format(operand, cast=True)
+
+    def _is_numeric_sequence(self, operand: Iterable):
+        for item in operand:
+            if isinstance(item, (list, tuple, np.ndarray, torch.Tensor, self._symbol_type)):
+                return False
+            if isinstance(item, (numbers.Real, np.generic)):
+                continue
+            return False
+        return True
+
+    def _get_similarity_handler(self, metric, eps, kwargs):
+        def _cosine_similarity(lhs, rhs):
+            return lhs.T@rhs / (np.sqrt(lhs.T@lhs) * np.sqrt(rhs.T@rhs) + eps)
+
+        def _angular_cosine_similarity(lhs, rhs):
+            c = kwargs.get('c', 1)
+            return 1 - (c * np.arccos(lhs.T@rhs / (np.sqrt(lhs.T@lhs) * np.sqrt(rhs.T@rhs) + eps)) / np.pi)
+
+        def _product_similarity(lhs, rhs):
+            return lhs.T@rhs
+
+        def _manhattan_similarity(lhs, rhs):
+            return np.abs(lhs - rhs).sum(axis=0, keepdims=True)
+
+        def _euclidean_similarity(lhs, rhs):
+            return np.sqrt(np.sum((lhs - rhs)**2, axis=0, keepdims=True))
+
+        def _minkowski_similarity(lhs, rhs):
+            p = kwargs.get('p', 3)
+            return np.sum(np.abs(lhs - rhs)**p, axis=0, keepdims=True)**(1/p)
+
+        def _jaccard_similarity(lhs, rhs):
+            intersection = np.minimum(lhs, rhs)
+            union = np.maximum(lhs, rhs)
+            return np.sum(intersection, axis=0, keepdims=True) / (np.sum(union, axis=0, keepdims=True) + eps)
+
+        metric_handlers = {
+            'cosine': _cosine_similarity,
+            'angular-cosine': _angular_cosine_similarity,
+            'product': _product_similarity,
+            'manhattan': _manhattan_similarity,
+            'euclidean': _euclidean_similarity,
+            'minkowski': _minkowski_similarity,
+            'jaccard': _jaccard_similarity,
+        }
+
+        handler = metric_handlers.get(metric)
+        if handler is None:
+            msg = (
+                f"Similarity metric {metric} not implemented. Available metrics: "
+                "'cosine', 'angular-cosine', 'product', 'manhattan', 'euclidean', 'minkowski', 'jaccard'"
+            )
+            UserMessage(msg)
+            raise NotImplementedError(msg)
+        return handler
+
+    def _get_kernel_handler(self, kernel):
+        kernel_handlers = {
+            'gaussian': self._kernel_gaussian,
+            'rbf': self._kernel_rbf,
+            'laplacian': self._kernel_laplacian,
+            'polynomial': self._kernel_polynomial,
+            'sigmoid': self._kernel_sigmoid,
+            'linear': self._kernel_linear,
+            'cauchy': self._kernel_cauchy,
+            't-distribution': self._kernel_t_distribution,
+            'inverse-multiquadric': self._kernel_inverse_multiquadric,
+            'cosine': self._kernel_cosine,
+            'angular-cosine': self._kernel_angular_cosine,
+            'frechet': self._kernel_frechet,
+            'mmd': self._kernel_mmd,
+        }
+
+        handler = kernel_handlers.get(kernel)
+        if handler is None:
+            msg = "Kernel function {kernel} not implemented. Available functions: 'gaussian'"
+            UserMessage(msg.format(kernel=kernel))
+            raise NotImplementedError(msg.format(kernel=kernel))
+        return handler
+
+    def _kernel_gaussian(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        return np.exp(-gamma * np.sum((lhs - rhs)**2, axis=0))
+
+    def _kernel_rbf(self, lhs, rhs, _eps, kwargs):
+        bandwidth = kwargs.get('bandwidth')
+        gamma = kwargs.get('gamma', 1)
+        distance_sq = np.sum((lhs - rhs)**2, axis=0)
+        if bandwidth is not None:
+            val = 0
+            for a in bandwidth:
+                gamma = 1.0 / (2 * a)
+                val += np.exp(-gamma * distance_sq)
+            return val
+        return np.exp(-gamma * distance_sq)
+
+    def _kernel_laplacian(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        return np.exp(-gamma * np.sum(np.abs(lhs - rhs), axis=0))
+
+    def _kernel_polynomial(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        degree = kwargs.get('degree', 3)
+        coef = kwargs.get('coef', 1)
+        return (gamma * np.sum((lhs * rhs), axis=0) + coef)**degree
+
+    def _kernel_sigmoid(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        coef = kwargs.get('coef', 1)
+        return np.tanh(gamma * np.sum((lhs * rhs), axis=0) + coef)
+
+    def _kernel_linear(self, lhs, rhs, _eps, _kwargs):
+        return np.sum((lhs * rhs), axis=0)
+
+    def _kernel_cauchy(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        return 1 / (1 + np.sum((lhs - rhs)**2, axis=0) / gamma)
+
+    def _kernel_t_distribution(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        degree = kwargs.get('degree', 1)
+        return 1 / (1 + (np.sum((lhs - rhs)**2, axis=0) / (gamma * degree))**(degree + 1) / 2)
+
+    def _kernel_inverse_multiquadric(self, lhs, rhs, _eps, kwargs):
+        gamma = kwargs.get('gamma', 1)
+        return 1 / np.sqrt(np.sum((lhs - rhs)**2, axis=0) / gamma**2 + 1)
+
+    def _kernel_cosine(self, lhs, rhs, eps, _kwargs):
+        numerator = np.sum(lhs * rhs, axis=0)
+        denominator = np.sqrt(np.sum(lhs**2, axis=0)) * np.sqrt(np.sum(rhs**2, axis=0)) + eps
+        return 1 - (numerator / denominator)
+
+    def _kernel_angular_cosine(self, lhs, rhs, eps, kwargs):
+        c = kwargs.get('c', 1)
+        numerator = np.sum(lhs * rhs, axis=0)
+        denominator = np.sqrt(np.sum(lhs**2, axis=0)) * np.sqrt(np.sum(rhs**2, axis=0)) + eps
+        return c * np.arccos(numerator / denominator) / np.pi
+
+    def _kernel_frechet(self, lhs, rhs, eps, kwargs):
+        sigma1 = kwargs.get('sigma1')
+        sigma2 = kwargs.get('sigma2')
+        assert sigma1 is not None and sigma2 is not None, 'Frechet distance requires covariance matrices for both inputs'
+        return calculate_frechet_distance(lhs.T, sigma1, rhs.T, sigma2, eps)
+
+    def _kernel_mmd(self, lhs, rhs, eps, _kwargs):
+        return calculate_mmd(lhs.T, rhs.T, eps=eps)
+
+    def similarity(
+        self,
+        other: Union['Symbol', list, np.ndarray, torch.Tensor],
+        metric: Literal['cosine', 'angular-cosine', 'product', 'manhattan', 'euclidean', 'minkowski', 'jaccard'] = 'cosine',
+        eps: float = 1e-8,
+        normalize: Callable | None = None,
+        **kwargs,
+    ) -> float:
         '''
         Calculates the similarity between two Symbol objects using a specified metric.
         This method compares the values of two Symbol objects and calculates their similarity according to the specified metric.
@@ -2427,45 +2621,29 @@ class EmbeddingPrimitives(Primitive):
             NotImplementedError: If the given metric is not supported.
         '''
         v = self._ensure_numpy_format(self)
-        if isinstance(other, list) or isinstance(other, tuple):
-            o = []
-            for i in range(len(other)):
-                o.append(self._ensure_numpy_format(other[i], cast=True))
-            o = np.concatenate(o, axis=1)
-        else:
-            o = self._ensure_numpy_format(other, cast=True)
-
-        if   metric == 'cosine':
-            val     = v.T@o / (np.sqrt(v.T@v) * np.sqrt(o.T@o) + eps)
-        elif metric == 'angular-cosine':
-            c       = kwargs.get('c', 1)
-            val     = 1 - (c * np.arccos((v.T@o / (np.sqrt(v.T@v) * np.sqrt(o.T@o) + eps))) / np.pi)
-        elif metric == 'product':
-            val     = v.T@o
-        elif metric == 'manhattan':
-            val     = np.abs(v - o).sum(axis=0, keepdims=True)
-        elif metric == 'euclidean':
-            val     = np.sqrt(np.sum((v - o)**2, axis=0, keepdims=True))
-        elif metric == 'minkowski':
-            p       = kwargs.get('p', 3)
-            val     = np.sum(np.abs(v - o)**p, axis=0, keepdims=True)**(1/p)
-        elif metric == 'jaccard':
-            intersection = np.minimum(v, o)
-            union = np.maximum(v, o)
-            val = np.sum(intersection, axis=0, keepdims=True) / (np.sum(union, axis=0, keepdims=True) + eps)
-        else:
-            raise NotImplementedError(f"Similarity metric {metric} not implemented. Available metrics: 'cosine', 'angular-cosine', 'product', 'manhattan', 'euclidean', 'minkowski', 'jaccard'")
+        o = self._prepare_embedding_operand(other)
+        handler = self._get_similarity_handler(metric, eps, kwargs)
+        val = handler(v, o)
 
         # get the similarity value(s)
         shape = val.shape
-        if len(shape) >= 2 and min(shape) > 1: val = val.diagonal()
-        elif len(shape) >= 1 and shape[0] > 1: val = val
-        else:                                  val = val.item()
-        if normalize is not None:              val = normalize(val)
+        if len(shape) >= 2 and min(shape) > 1:
+            val = val.diagonal()
+        elif len(shape) < 1 or shape[0] <= 1:
+            val = val.item()
+        if normalize is not None:
+            val = normalize(val)
 
         return val
 
-    def distance(self, other: Union['Symbol', list, np.ndarray, torch.Tensor], kernel: Union['gaussian', 'rbf', 'laplacian', 'polynomial', 'sigmoid', 'linear', 'cauchy', 't-distribution', 'inverse-multiquadric', 'cosine', 'angular-cosine', 'frechet', 'mmd'] = 'gaussian',  eps: float = 1e-8, normalize: Optional[Callable] = None, **kwargs) -> float:
+    def distance(
+        self,
+        other: Union['Symbol', list, np.ndarray, torch.Tensor],
+        kernel: Literal['gaussian', 'rbf', 'laplacian', 'polynomial', 'sigmoid', 'linear', 'cauchy', 't-distribution', 'inverse-multiquadric', 'cosine', 'angular-cosine', 'frechet', 'mmd'] = 'gaussian',
+        eps: float = 1e-8,
+        normalize: Callable | None = None,
+        **kwargs,
+    ) -> float:
         '''
         Calculates the kernel between two Symbol objects.
 
@@ -2483,82 +2661,18 @@ class EmbeddingPrimitives(Primitive):
             NotImplementedError: If the given kernel is not supported.
         '''
         v = self._ensure_numpy_format(self)
-        if isinstance(other, list) or isinstance(other, tuple):
-            o = []
-            for i in range(len(other)):
-                o.append(self._ensure_numpy_format(other[i], cast=True))
-            o = np.concatenate(o, axis=1)
-        else:
-            o = self._ensure_numpy_format(other, cast=True)
-
-        # compute the kernel value
-        if   kernel == 'gaussian':
-            gamma   = kwargs.get('gamma', 1)
-            val     = np.exp(-gamma * np.sum((v - o)**2, axis=0))
-        elif kernel == 'rbf':
-            # vectors are expected to be normalized
-            bandwidth = kwargs.get('bandwidth', None)
-            gamma     = kwargs.get('gamma', 1)
-            d         = np.sum((v - o)**2, axis=0)
-            if bandwidth is not None:
-                val   = 0
-                for a in bandwidth:
-                    gamma = 1.0 / (2 * a)
-                    val  += np.exp(-gamma * d)
-            else:
-                # if no bandwidth is given, default to the gaussian kernel
-                val = np.exp(-gamma * d)
-        elif kernel == 'laplacian':
-            gamma   = kwargs.get('gamma', 1)
-            val     = np.exp(-gamma * np.sum(np.abs(v - o), axis=0))
-        elif kernel == 'polynomial':
-            gamma   = kwargs.get('gamma', 1)
-            degree  = kwargs.get('degree', 3)
-            coef    = kwargs.get('coef', 1)
-            val     = (gamma * np.sum((v * o), axis=0) + coef)**degree
-        elif kernel == 'sigmoid':
-            gamma   = kwargs.get('gamma', 1)
-            coef    = kwargs.get('coef', 1)
-            val     = np.tanh(gamma * np.sum((v * o), axis=0) + coef)
-        elif kernel == 'linear':
-            val     = np.sum((v * o), axis=0)
-        elif kernel == 'cauchy':
-            gamma   = kwargs.get('gamma', 1)
-            val     = 1 / (1 + np.sum((v - o)**2, axis=0) / gamma)
-        elif kernel == 't-distribution':
-            gamma   = kwargs.get('gamma', 1)
-            degree  = kwargs.get('degree', 1)
-            val     = 1 / (1 + (np.sum((v - o)**2, axis=0) / (gamma * degree))**(degree + 1) / 2)
-        elif kernel == 'inverse-multiquadric':
-            gamma   = kwargs.get('gamma', 1)
-            val     = 1 / np.sqrt(np.sum((v - o)**2, axis=0) / gamma**2 + 1)
-        elif kernel == 'cosine':
-            val     = 1 - (np.sum(v * o, axis=0) / (np.sqrt(np.sum(v**2, axis=0)) * np.sqrt(np.sum(o**2, axis=0)) + eps))
-        elif kernel == 'angular-cosine':
-            c       = kwargs.get('c', 1)
-            val     = c * np.arccos((np.sum(v * o, axis=0) / (np.sqrt(np.sum(v**2, axis=0)) * np.sqrt(np.sum(o**2, axis=0)) + eps))) / np.pi
-        elif kernel == 'frechet':
-            sigma1  = kwargs.get('sigma1', None)
-            sigma2  = kwargs.get('sigma2', None)
-            assert sigma1 is not None and sigma2 is not None, 'Frechet distance requires covariance matrices for both inputs'
-            v       = v.T
-            o       = o.T
-            val     = calculate_frechet_distance(v, sigma1, o, sigma2, eps)
-        elif kernel == 'mmd':
-            v       = v.T
-            o       = o.T
-            val     = calculate_mmd(v, o, eps=eps)
-        else:
-            raise NotImplementedError(f"Kernel function {kernel} not implemented. Available functions: 'gaussian'")
+        o = self._prepare_embedding_operand(other)
+        handler = self._get_kernel_handler(kernel)
+        val = handler(v, o, eps, kwargs)
 
         # get the kernel value(s)
         shape = val.shape
-        if len(shape) >= 1 and shape[0] > 1: val = val
-        else:                                val = val.item()
-        if normalize is not None:            val = normalize(val)
+        val = val if len(shape) >= 1 and shape[0] > 1 else val.item()
+        if normalize is not None:
+            val = normalize(val)
         return val
 
-    def zip(self, **kwargs) -> List[Tuple[str, List, Dict]]:
+    def zip(self, **kwargs) -> list[tuple[str, list, dict]]:
         '''
         Zips the Symbol's value with its embeddings and a query containing the value.
         This method zips the Symbol's value along with its embeddings and a query containing the value.
@@ -2577,19 +2691,21 @@ class EmbeddingPrimitives(Primitive):
         elif isinstance(self.value, list):
             pass
         else:
-            raise ValueError(f'Expected id to be a string, got {type(self.value)}')
+            msg = f'Expected id to be a string, got {type(self.value)}'
+            UserMessage(msg)
+            raise ValueError(msg)
 
         embeds = self.embed(**kwargs).value
         idx    = [str(uuid.uuid4()) for _ in range(len(self.value))]
         query  = [{'text': str(self.value[i])} for i in range(len(self.value))]
 
         # convert embeds to list if it is a tensor or numpy array
-        if type(embeds) == np.ndarray:
+        if isinstance(embeds, np.ndarray):
             embeds = embeds.tolist()
-        elif type(embeds) == torch.Tensor:
+        elif isinstance(embeds, torch.Tensor):
             embeds = embeds.cpu().numpy().tolist()
 
-        return list(zip(idx, embeds, query))
+        return list(zip(idx, embeds, query, strict=False))
 
 
 class IOHandlingPrimitives(Primitive):
@@ -2630,7 +2746,7 @@ class IOHandlingPrimitives(Primitive):
             return self.sym_return_type(self.value if condition else '') | res
         return self._to_type(self.value if condition else '') | self._to_type(res)
 
-    def open(self, path: str = None, **kwargs) -> 'Symbol':
+    def open(self, path: str | None = None, **kwargs) -> 'Symbol':
         '''
         Open a file and store its content in an Expression object as a string.
 
@@ -2654,7 +2770,9 @@ class IOHandlingPrimitives(Primitive):
 
         path = path if path is not None else self.value
         if path is None:
-            raise ValueError('Path is not provided; either provide a path or set the value of the Symbol to the path')
+            msg = 'Path is not provided; either provide a path or set the value of the Symbol to the path'
+            UserMessage(msg)
+            raise ValueError(msg)
 
         @core.opening(path=path, **kwargs)
         def _func(_):
@@ -2726,7 +2844,7 @@ class PersistencePrimitives(Primitive):
 
         return func_name
 
-    def save(self, path: str, replace: Optional[bool] = False, serialize: Optional[bool] = True) -> None:
+    def save(self, path: str, replace: bool | None = False, serialize: bool | None = True) -> None:
         '''
         Save the current Symbol to a file.
 
@@ -2738,22 +2856,24 @@ class PersistencePrimitives(Primitive):
         Returns:
             Symbol: The current Symbol.
         '''
-        file_path = path
+        file_path = Path(path)
 
         if not replace:
             cnt = 0
-            while os.path.exists(file_path):
-                filename, file_extension = os.path.splitext(path)
-                file_path = f'{filename}_{cnt}{file_extension}'
+            candidate = file_path
+            while candidate.exists():
+                candidate = candidate.with_name(f'{file_path.stem}_{cnt}{file_path.suffix}')
                 cnt += 1
+            file_path = candidate
 
         if serialize:
             # serialize the object via pickle instead of writing the string
-            path_ = str(file_path) + '.pkl' if not str(file_path).endswith('.pkl') else str(file_path)
-            with open(path_, 'wb') as f:
+            path_str = str(file_path)
+            pickle_path = Path(path_str if path_str.endswith('.pkl') else f'{path_str}.pkl')
+            with pickle_path.open('wb') as f:
                 pickle.dump(self, file=f)
         else:
-            with open(str(file_path), 'w') as f:
+            with file_path.open('w') as f:
                 f.write(str(self))
 
     def load(self, path: str) -> Any:
@@ -2766,9 +2886,8 @@ class PersistencePrimitives(Primitive):
         Returns:
             Symbol: The loaded Symbol.
         '''
-        with open(path, 'rb') as f:
-            obj = pickle.load(f)
-        return obj
+        with Path(path).open('rb') as f:
+            return pickle.load(f)
 
 
 class OutputHandlingPrimitives(Primitive):
@@ -2789,7 +2908,7 @@ class OutputHandlingPrimitives(Primitive):
             Symbol: The resulting Symbol after the output operation.
         '''
         @core.output(**kwargs)
-        def _func(_, *func_args, **func_kwargs):
+        def _func(_, *_func_args, **_func_kwargs):
             return self.value
 
         return self._to_type(_func(self, self.value, *args))
@@ -2833,12 +2952,13 @@ class FineTuningPrimitives(Primitive):
             # return tensor
             return self._metadata.data
         # if the data is a numpy array, convert it to tensor
-        elif isinstance(self._metadata.data, np.ndarray):
+        if isinstance(self._metadata.data, np.ndarray):
             # convert to tensor
             self._metadata.data = torch.from_numpy(self._metadata.data)
             return self._metadata.data
-        else:
-            raise TypeError(f'Expected data to be a tensor or numpy array, got {type(self._metadata.data)}')
+        msg = f'Expected data to be a tensor or numpy array, got {type(self._metadata.data)}'
+        UserMessage(msg)
+        raise TypeError(msg)
 
     @data.setter
     def data(self, data: torch.Tensor) -> None: